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.35.tar.gz
(337.3 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.35.tar.gz.
File metadata
- Download URL: stats_compass_core-0.1.35.tar.gz
- Upload date:
- Size: 337.3 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 |
423e2ba82f2e03d794ead79a3ad17bdbf0560921df71ba8d8f26de0973c6427f
|
|
| MD5 |
e5baa18340a8b5de1ec538531d0c2418
|
|
| BLAKE2b-256 |
a3986b28dfbc5b9bc5ecb34359f95a4e6c97daba80ae2b598f17c8b1e5039333
|
File details
Details for the file stats_compass_core-0.1.35-py3-none-any.whl.
File metadata
- Download URL: stats_compass_core-0.1.35-py3-none-any.whl
- Upload date:
- Size: 399.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 |
77ca4e2d0c563df84f0b0def9e23b721e9211bf519423a6f3d4e289a2c3144a4
|
|
| MD5 |
f5418ce57c84a683941f3e3241a4ac81
|
|
| BLAKE2b-256 |
db18792f37b426111e6ab8f10d4872fcffbc26da65ccad4d209b2fab775e66d2
|
