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.33.tar.gz
(335.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.33.tar.gz.
File metadata
- Download URL: stats_compass_core-0.1.33.tar.gz
- Upload date:
- Size: 335.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 |
1c78a261f186b5e4b8a5aec94a03c0413691c65226931c964a80acbce2bb5f36
|
|
| MD5 |
2a275fa663807a8ffe6209c143401f43
|
|
| BLAKE2b-256 |
6cdbd7aa3ca53ad937a28072ccac8c25e7dfa19a9dbb1329eab9bb42ff98d9bc
|
File details
Details for the file stats_compass_core-0.1.33-py3-none-any.whl.
File metadata
- Download URL: stats_compass_core-0.1.33-py3-none-any.whl
- Upload date:
- Size: 398.6 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 |
2e6b2cfb86b4be8c6c0d7e9a3fb40c0ea6d22b8d5ad911defbe3b537e6575804
|
|
| MD5 |
b335682e84bc5c01e40b35cc5b4ba4aa
|
|
| BLAKE2b-256 |
e75c27d9a047eb6f8664900dee3b668afa9d5b4552600543907ef9403badaaf9
|
