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.31.tar.gz
(335.5 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.31.tar.gz.
File metadata
- Download URL: stats_compass_core-0.1.31.tar.gz
- Upload date:
- Size: 335.5 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 |
6ffbc7d7d2a3509e107b5bd9fb0a596ce5aaaf263f2c4b022856874d85867ee8
|
|
| MD5 |
950e02baca262e51fef7f24ac72ee7dd
|
|
| BLAKE2b-256 |
6ece33f30cd4c76031f9d55162605e18ade6d393db8cd52545fb94ee50316f62
|
File details
Details for the file stats_compass_core-0.1.31-py3-none-any.whl.
File metadata
- Download URL: stats_compass_core-0.1.31-py3-none-any.whl
- Upload date:
- Size: 397.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 |
9a6fe4d46fb5497357e400a67fcc323c45cac3d48d6bfe593896f2b4e6202bdb
|
|
| MD5 |
ab4d6c0c93e8a5db3c0ae19d09e849cf
|
|
| BLAKE2b-256 |
1f25a380ae57db7827315bd6fe038bbd363ec44120ee2f780eb0fa6536396de2
|
