stats-compass-core

Stateful pandas toolkit for AI agents. 50+ data tools via MCP.

What is this?

A Python library that turns pandas operations into JSON-serializable tools for LLM agents. Unlike raw pandas, it manages server-side state. DataFrames and trained models persist across tool calls.

Looking for the MCP server? See stats-compass-mcp.

Quick Start

pip install stats-compass-core[all]

from stats_compass_core import DataFrameState, registry
import pandas as pd

# Initialize state (one per session)
state = DataFrameState()

# Load data
df = pd.read_csv("data.csv")
state.set_dataframe(df, name="my_data", operation="load")

# Call tools via registry
result = registry.invoke("eda", "describe", state, {"dataframe_name": "my_data"})
print(result.model_dump_json())  # JSON-serializable output

# Run complete workflows
result = registry.invoke("workflows", "run_classification", state, {
    "target_column": "churn",
    "feature_columns": ["age", "tenure", "balance"],
    "config": {"model_type": "random_forest", "generate_plots": True}
})

What's Included

See docs/TOOLS.md for the complete list of 50+ tools.

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                     stats-compass-core                          │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │                   DataFrameState                        │    │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐      │    │
│  │  │ DataFrames  │  │   Models    │  │   History   │      │    │
│  │  │ (by name)   │  │  (by ID)    │  │  (lineage)  │      │    │
│  │  └─────────────┘  └─────────────┘  └─────────────┘      │    │
│  └─────────────────────────────────────────────────────────┘    │
│                              │                                  │
│              ┌───────────────┼───────────────┐                  │
│              ▼               ▼               ▼                  │
│  ┌──────────────────┐ ┌──────────────┐ ┌───────────────────┐    │
│  │ Workflow Tools   │ │  Sub-Tools   │ │  Result Models    │    │
│  │  (orchestrate)   │ │  (atomic)    │ │  (JSON-safe)      │    │
│  └──────────────────┘ └──────────────┘ └───────────────────┘    │
└─────────────────────────────────────────────────────────────────┘

Key concepts:

1. DataFrameState - Stores DataFrames and models server-side
2. Registry - Discovers and invokes tools by category/name
3. Result Models - All tools return Pydantic models (JSON-serializable)
4. Workflows - High-level tools that chain sub-tools together

See ARCHITECTURE.md for detailed design docs.

Installation Options

Documentation

• TOOLS.md - Complete tool reference (50+ tools)
• EXAMPLES.md - Detailed usage examples
• API.md - Core classes and methods
• ARCHITECTURE.md - Design decisions

Development

git clone https://github.com/oogunbiyi21/stats-compass-core.git
cd stats-compass-core
poetry install --with dev
poetry run pytest

See docs/CONTRIBUTING.md for contribution guidelines.

License

MIT