semantic-frame: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

semantic-frame is a Python library that converts raw numerical data (NumPy, Pandas, Polars) into token-efficient natural language descriptions optimized for LLM consumption. Instead of sending thousands of data points to an AI agent, send a 50-word semantic summary.

Core value proposition: 95%+ token reduction, zero hallucination risk (deterministic math via NumPy/scipy, not LLM guesses).

Build and Development Commands

# Install dependencies
uv sync

# Run all tests with coverage
uv run pytest

# Run specific test file
uv run pytest tests/test_analyzers.py

# Run single test
uv run pytest tests/test_analyzers.py::TestClassifyTrend::test_rising_sharp -v

# Type checking
uv run mypy semantic_frame

# Linting
uv run ruff check semantic_frame

# Format
uv run ruff format semantic_frame

# Run pre-commit hooks manually
uv run pre-commit run --all-files

# Install docs dependencies
uv sync --group docs

# Build documentation
uv run mkdocs build

# Serve docs locally (with live reload, runs on port 8001)
uv run mkdocs serve

Pre-commit Hooks

Pre-commit hooks are configured for code quality. Install with:

uv run pre-commit install

Hooks run automatically on git commit:

• trailing-whitespace: Remove trailing whitespace
• end-of-file-fixer: Ensure files end with newline
• check-yaml: Validate YAML syntax
• check-added-large-files: Prevent large file commits
• check-merge-conflict: Prevent committing conflict markers
• ruff: Linting with auto-fix
• ruff-format: Code formatting
• mypy: Type checking (excludes tests/)

Architecture

The library follows a 4-stage pipeline:

Input (NumPy/Pandas/Polars) → Profiler → Classifier → Narrator → Output (text/json/SemanticResult)

Module Structure

semantic_frame/
├── main.py              # Public API: describe_series(), describe_dataframe()
├── core/
│   ├── enums.py         # Semantic vocabulary (TrendState, VolatilityState, StructuralChange, etc.)
│   ├── analyzers.py     # Math engine (NumPy/scipy stats, no LLMs)
│   ├── correlations.py  # Cross-column correlation analysis (Pearson/Spearman)
│   └── translator.py    # Orchestrates pipeline: profile → analyze → narrate
├── narrators/
│   ├── time_series.py   # Generates narratives for ordered data
│   ├── distribution.py  # Generates narratives for unordered data
│   └── correlation.py   # Generates narratives for column relationships
├── interfaces/
│   ├── json_schema.py   # Pydantic models (SemanticResult, AnomalyInfo, etc.)
│   └── llm_templates.py # LangChain/agent integration helpers
├── integrations/
│   ├── anthropic.py     # Native Anthropic Claude tool use (optional dep)
│   ├── langchain.py     # LangChain BaseTool wrapper (optional dep)
│   ├── crewai.py        # CrewAI tool decorator wrapper (optional dep)
│   └── mcp.py           # Model Context Protocol server (optional dep)
└── trading/             # Trading-specific analysis (v0.4.0)
    ├── drawdown.py      # Equity curve drawdown analysis
    ├── metrics.py       # Win rate, Sharpe, profit factor calculations
    ├── rankings.py      # Multi-agent/strategy comparison
    ├── anomalies.py     # Enhanced anomaly detection with severity
    ├── windows.py       # Multi-timeframe trend alignment
    ├── regime.py        # Market regime detection (bull/bear/sideways)
    ├── allocation.py    # Portfolio allocation suggestions (educational)
    ├── enums.py         # Trading-specific enums (DrawdownSeverity, etc.)
    └── schemas.py       # Pydantic models for trading results