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
| Category | Tools | Description |
|---|---|---|
| Data | load_csv, get_schema, list_dataframes |
Load and inspect data |
| Cleaning | drop_na, impute, dedupe, handle_outliers |
Clean messy data |
| Transforms | filter, groupby, pivot, encode, scale |
Reshape and transform |
| EDA | describe, correlations, hypothesis_test |
Statistical analysis |
| Plots | histogram, scatter, bar, roc_curve |
Visualizations (base64 PNG) |
| ML | train_*, evaluate, predict, cross_validate |
Machine learning |
| Workflows | run_preprocessing, run_classification, run_regression |
Multi-step pipelines |
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:
- DataFrameState - Stores DataFrames and models server-side
- Registry - Discovers and invokes tools by category/name
- Result Models - All tools return Pydantic models (JSON-serializable)
- Workflows - High-level tools that chain sub-tools together
See ARCHITECTURE.md for detailed design docs.
Installation Options
| Use Case | Command |
|---|---|
| Core only (data, cleaning, EDA) | pip install stats-compass-core |
| With ML (scikit-learn) | pip install stats-compass-core[ml] |
| With plotting (matplotlib) | pip install stats-compass-core[plots] |
| With time series (statsmodels) | pip install stats-compass-core[timeseries] |
| Everything | pip install stats-compass-core[all] |
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
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
stats_compass_core-0.1.30.tar.gz
(334.9 kB
view details)
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file stats_compass_core-0.1.30.tar.gz.
File metadata
- Download URL: stats_compass_core-0.1.30.tar.gz
- Upload date:
- Size: 334.9 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
poetry/2.1.3 CPython/3.12.5 Darwin/24.6.0
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
84dde41f9bec06a040296c44a34c0c02e6ae78b5acefdf67bb8c58bace4c31bc
|
|
| MD5 |
9205d5a321312820a68456c72f98a10e
|
|
| BLAKE2b-256 |
94d04ae36a3d1aa92da8cee8e87c881be671a71f47fd840113ae561b240cc91d
|
File details
Details for the file stats_compass_core-0.1.30-py3-none-any.whl.
File metadata
- Download URL: stats_compass_core-0.1.30-py3-none-any.whl
- Upload date:
- Size: 397.1 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
poetry/2.1.3 CPython/3.12.5 Darwin/24.6.0
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
80331098953e7d5e05aa7efc26b269e9cf1727383b6878cffdc530ba024b0225
|
|
| MD5 |
ad7a23943fd99d6f9c41160bc2dbccb9
|
|
| BLAKE2b-256 |
1a0532d7e87efd7ea9502fa694cd442c9119b2e792829fcff2299db9b84a15a9
|
