TableIntelligence *
A deterministic, reproducible intelligence layer for single-table data.
tabint is a Python library of statistical and machine-learning operations for
one table at a time. Each operation is a plain, directly-callable function with a
structured, inspectable result — plus an MCP server that exposes the same
deterministic functions to any MCP-capable agent (Claude Cowork, Codex, Cursor).
The design goal that sets it apart: the same question yields the same, correct answer every time, with the method it chose made explicit. Code-generation tools that write fresh pandas on every run can't promise that; this library is built so the computation is deterministic and the statistical method is selected by transparent rules, not improvised.
Status: working library + MCP server. Phases 0–8 of the roadmap are implemented and tested (225 tests passing); see the roadmap below.
Install
The package is on PyPI. Requires Python ≥ 3.10.
# MCP server — no install needed, runs isolated via uvx
uvx tabint-mcp --help
# or install the CLI + MCP server into your environment
pip install tabint
Verify it landed:
tabint --help # the CLI
tabint-mcp --help # the MCP server (stdio transport)
No
uvx? Install it withcurl -LsSf https://astral.sh/uv/install.sh | sh, or usepipx run tabint-mcp --helpinstead.
Intended usage
Single table — the flat convenience API:
from tabint import Session
s = Session.load("customers.csv")
s.profile() # describe every column
s.analyze_association("city", "spending") # picks the right test by dtype
model = s.train_classifier(target="churn") # returns a TrainedModel
model.predict(new_row) # predict lives on the model
Multiple related tables — one workspace, foreign keys detected automatically:
s = Session.load(["orders.csv", "customers.csv", "products.csv"])
s.relationships() # infers the FK graph:
# orders.customer_id → customers.customer_id (100%)
# orders.product_id → products.product_id (100%)
enriched = s.join(["orders", "customers"]) # materializes a new joined table
enriched.analyze_association("order_total", "tier") # analytics run on it
s.table("customers").cluster() # per-table handle for any table
Every analytic operates on one table — either an uploaded table or one produced
by join. Joins are the only cross-table operation; they collapse related tables
into a single table the rest of the library can reason about.
Use it from an AI agent (CLI + MCP)
The core is exposed to any MCP-capable agent through a terminal CLI
(tabint) and an MCP server (tabint-mcp), both driven by a persistent
session key. First do the install above, then register the server with your
agent.
Environment variables
All agents need these in the server's env. Set them once and reuse the block
in every config below.
| Variable | Required | Default | Purpose |
|---|---|---|---|
TABINT_API_KEY |
yes | — | Your ti_… key from https://shubhamrandive.com/dashboard/account. Absent → free role (all analytics still work; Pro-only connectors/reports/outreach are gated). |
TABINT_CONTROL_PLANE_URL |
no | https://shubhamrandive.com |
Base URL of the control plane (reports, folders, key validation). |
TABULAR_BASE |
no | current dir | Where on-disk sessions are stored (<base>/.tableint/sessions/). |
Claude Code / Claude Cowork / Claude Desktop
Register the server (Claude Code CLI):
claude mcp add tabint \
--env TABINT_API_KEY=ti_your_key_here \
--env TABINT_CONTROL_PLANE_URL=https://shubhamrandive.com \
-- uvx tabint-mcp
…or paste the JSON block into the MCP config (Cowork / Desktop):
{
"mcpServers": {
"tabint": {
"command": "uvx",
"args": ["tabint-mcp"],
"env": {
"TABINT_API_KEY": "ti_your_key_here",
"TABINT_CONTROL_PLANE_URL": "https://shubhamrandive.com"
}
}
}
}
OpenAI Codex (CLI)
Add to ~/.codex/config.toml (Codex reads MCP servers from [mcp_servers.*]):
[mcp_servers.tabint]
command = "uvx"
args = ["tabint-mcp"]
env = { TABINT_API_KEY = "ti_your_key_here", TABINT_CONTROL_PLANE_URL = "https://shubhamrandive.com" }
Cursor
Add to .cursor/mcp.json in your project (or Settings → MCP for global):
{
"mcpServers": {
"tabint": {
"command": "uvx",
"args": ["tabint-mcp"],
"env": {
"TABINT_API_KEY": "ti_your_key_here",
"TABINT_CONTROL_PLANE_URL": "https://shubhamrandive.com"
}
}
}
}
Verify it works
After registering the server in any agent, ask it to call the account_status
tool — it should return your role:
> call account_status
{"role": "pro", "pro_features_unlocked": true, ...} # or {"role": "free", ...} if no key set
Or from the CLI directly:
tabint load orders.csv customers.csv # -> {"session_key": "s_ab12", "tables": [...], "relationships": [...]}
tabint associate order_total tier --session s_ab12 --table orders
See docs/agent-integration.md for the full tool
list and troubleshooting. This replaces the originally-planned bespoke agent
harness: any MCP-capable agent orchestrates the same deterministic functions.
Documentation
docs/vision.md— what this is and why it existsdocs/architecture.md— the layered design and contractsdocs/algorithms.md— the full algorithm taxonomydocs/roadmap.md— phased build plandocs/adding-an-algorithm.md— the recipe for each new functionCONTRIBUTING.md
Algorithm roadmap
Tick a box when a function is implemented, tested, and documented. This list is the single source of truth for "what to build next" — pick an unchecked item, research it, implement it against an existing library, add it to the test harness, then check it here.
Phase 0 — Foundation (build first; everything depends on it)
-
store— load a table, run SQL, write columns back (DuckDB) -
results.Result— the structured return contract -
validation.dtypes— column type classification (the routing input) -
validation.assumptions— normality / equal-variance / sample-size checks -
identity— operation identity + caching key -
Session— state holder that delegates to the analytics layer - eval harness — fixture CSVs + known-correct answers
Phase 1 — Descriptive
-
profile— per-column type, distribution, missingness, cardinality, range -
detect_outliers— IQR and z-score flags -
association_matrix— pairwise association with the right measure per dtype
Phase 2 — Association / hypothesis testing (flagship — build carefully)
-
analyze_association— dtype-routed test selection + effect size
Phase 3 — Clustering
-
cluster— scale, fit, pick k (silhouette), write labels back as a column -
profile_clusters— characterize each cluster in plain terms
Phase 4 — Supervised learning
-
train_classifier— fast lane, single model, proper split (returnsTrainedModel) -
train_regressor— fast lane, single model, proper split -
backend="tabicl"— opt-in TabICL v2 tabular foundation model (in-context learning, no per-task training; needs thetabiclextra). Defaultbackend="gbt". -
TrainedModel.predict/.predict_proba— bundled preprocessing -
evaluate— full metric set + confusion matrix -
add_predictions— write a model's predictions back as a column - slow lane: AutoGluon wrapper as a job (infra ready via
jobs; wrapper not yet written) -
jobs— Job registry + background runner
Phase 5 — Model interpretation
-
feature_importance— gain-based / permutation importance -
explain_prediction— per-row SHAP values
Phase 6 — Dimensionality reduction
-
reduce_dimensions— PCA, UMAP/t-SNE (PCA + t-SNE native; UMAP optional)
Phase 7 — Time series (optional; only if tables have a time axis)
-
decompose— trend / seasonality / residual -
forecast— ARIMA / Prophet (ARIMA via statsmodels; Prophet optional) -
detect_changepoints— where a series shifts (ruptures;insightsextra)
Phase 8 — Insight-extraction primitives (the "so what / why / what to do" layer)
-
explain_metric— ranked key drivers + segment rules (shallow sklearn tree) -
market_basket— association-rule / cross-sell mining (mlxtend;insightsextra) -
causal_effect— backdoor effect estimate + refutation (DoWhy;insightsextra) -
rfm— Recency/Frequency/Monetary quintile segmentation (pandas) -
retention_cohorts— monthly cohort retention matrix (pandas) -
compare_periods— before/after shift with significance + effect size (scipy)
Later — large-data + orchestration (beyond V0)
- large-data strategies (sampling, out-of-core, approximate methods)
- natural-language
ask()agent over the deterministic core
Scope
Every analytic operates on a single table. Multiple related tables can be
loaded into one workspace (a shared DuckDB database); foreign keys are detected
automatically and a join collapses related tables into a single derived table
that the analytics then treat like any other. Reshaping beyond FK joins (pivots,
complex multi-way transforms) remains upstream of where these algorithms begin.
License
Apache License 2.0 — see LICENSE. The distributed package (library,
CLI, and MCP server) is fully open source. Monetization lives entirely in the
hosted control plane (connectors, reports, outreach, and the Pro role), not in
the client software.
Metadata
Release files for tabint 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| tabint-0.1.1.tar.gz | 136.6 kB | With provenance | Details for tabint-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| tabint-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for tabint-0.1.1-py3-none-any.whl |
Total release size: 264.8 kB
Release files / tabint-0.1.1.tar.gz
| Download URL | tabint-0.1.1.tar.gz |
|---|---|
| Size | 136.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
5c1e293a7adc4e4cdb65905b8c2b2c4c329bcba8dff112094ee8c5aba40f9187
|
|
BLAKE2b-256 checksum How to use checksums |
1879dbd7a5df13acc893543612d43fd6ea2ef68370a45935633dfaaac9ffeb05
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 22, 2026.
Transparency logRelease files / tabint-0.1.1-py3-none-any.whl
| Download URL | tabint-0.1.1-py3-none-any.whl |
|---|---|
| Size | 128.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
bfb35e06db793a013428cf6a21bc7d48b5217f5435c7fd0a3c0430a1a890a014
|
|
BLAKE2b-256 checksum How to use checksums |
31e8bbf63549f4d58e5373d5c5c7f0d060809b8de39ecf7afddf9376a9d24416
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 22, 2026.
Transparency logSecurity for tabint 0.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for tabint-0.1.1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 22, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.