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.34.tar.gz
(336.0 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.34.tar.gz.
File metadata
- Download URL: stats_compass_core-0.1.34.tar.gz
- Upload date:
- Size: 336.0 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 |
c10c59488fbef51c9dd90d88c74c4b2a949b26eb76ce386e123db08e77e24c3b
|
|
| MD5 |
ac5a1974fd65ab3300fb358c1264afb7
|
|
| BLAKE2b-256 |
869c0066ce9f2d5ed0039ac0c674b9beefe63c87abc91ee75e4c369bdbd46127
|
File details
Details for the file stats_compass_core-0.1.34-py3-none-any.whl.
File metadata
- Download URL: stats_compass_core-0.1.34-py3-none-any.whl
- Upload date:
- Size: 398.7 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 |
c2c4b40403bebe39d9eb74a8a9fec77cc40e7c6851a7676b96ce177bc7a44bed
|
|
| MD5 |
0c5596dd66c85ef978b8e6c39741755d
|
|
| BLAKE2b-256 |
82dab74e7f1eba520b8ee1b52c40e1c7e6b9568c5eab019d069c0d1ecd71967f
|
