{
  "markdown": "# Disco\n\n**Find novel, statistically validated patterns in tabular data** — feature interactions, subgroup effects, and conditional relationships that humans and agents miss.\n\n[![PyPI](https://img.shields.io/pypi/v/discovery-engine-api)](https://pypi.org/project/discovery-engine-api/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n\nMade by [Leap Laboratories](https://www.leap-labs.com).\n\n---\n\n## What it actually does\n\nMost data analysis starts with a question. Disco starts with the data.\n\nWithout biases or assumptions, it finds combinations of feature conditions that significantly shift your target column — things like \"patients aged 45–65 with low HDL *and* high CRP have 3× the readmission rate\" — without you needing to hypothesise that interaction first.\n\nEach pattern is:\n- **Validated on a hold-out set** — increases the chance of generalisation\n- **FDR-corrected** — p-values included, adjusted for multiple testing\n- **Checked against academic literature** — to help you understand what you've found, and identify if it is novel.\n\nThe output is structured: conditions, effect sizes, p-values, citations, and a novelty classification for every pattern found.\n\n**Use it when:** \"which variables are most important with respect to X\", \"are there patterns we're missing?\", \"I don't know where to start with this data\", \"I need to understand how A and B affect C\".\n\n**Not for:** summary statistics, visualisation, filtering, SQL queries — use pandas for those\n\n---\n\n## Quickstart\n\n```bash\npip install discovery-engine-api\n```\n\nGet an API key:\n\n```bash\n# Step 1: request verification code (no password, no card)\ncurl -X POST https://disco.leap-labs.com/api/signup \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"email\": \"you@example.com\"}'\n\n# Step 2: submit code from email → get key\ncurl -X POST https://disco.leap-labs.com/api/signup/verify \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"email\": \"you@example.com\", \"code\": \"123456\"}'\n# → {\"key\": \"disco_...\", \"credits\": 10, \"tier\": \"free_tier\"}\n```\n\nOr create a key at [disco.leap-labs.com/developers](https://disco.leap-labs.com/developers).\n\nRun your first analysis:\n\n```python\nfrom discovery import Engine\n\nengine = Engine(api_key=\"disco_...\")\nresult = await engine.discover(\n    file=\"data.csv\",\n    target_column=\"outcome\",\n)\n\nfor pattern in result.patterns:\n    if pattern.p_value < 0.05 and pattern.novelty_type == \"novel\":\n        print(f\"{pattern.description} (p={pattern.p_value:.4f})\")\n\nprint(f\"Explore: {result.report_url}\")\n```\n\nRuns take a few minutes. `discover()` polls automatically and logs progress — queue position, estimated wait, current pipeline step, and ETA. For background runs, see [Running asynchronously](#running-asynchronously).\n\n→ [Full Python SDK reference](docs/python-sdk.md) · [Example notebook](notebooks/quickstart.ipynb)\n\n---\n\n## What you get back\n\nEach `Pattern` in `result.patterns` looks like this (real output from a crop yield dataset):\n\n```python\nPattern(\n    description=\"When humidity is between 72–89% AND wind speed is below 12 km/h, \"\n                \"crop yield increases by 34% above the dataset average\",\n    conditions=[\n        {\"type\": \"continuous\", \"feature\": \"humidity_pct\",\n         \"min_value\": 72.0, \"max_value\": 89.0},\n        {\"type\": \"continuous\", \"feature\": \"wind_speed_kmh\",\n         \"min_value\": 0.0, \"max_value\": 12.0},\n    ],\n    p_value=0.003,              # FDR-corrected\n    novelty_type=\"novel\",\n    novelty_explanation=\"Published studies examine humidity and wind speed as independent \"\n                        \"predictors, but this interaction effect — where low wind amplifies \"\n                        \"the benefit of high humidity within a specific range — has not been \"\n                        \"reported in the literature.\",\n    citations=[\n        {\"title\": \"Effects of relative humidity on cereal crop productivity\",\n         \"authors\": [\"Zhang, L.\", \"Wang, H.\"], \"year\": \"2021\",\n         \"journal\": \"Journal of Agricultural Science\"},\n    ],\n    target_change_direction=\"max\",\n    abs_target_change=0.34,     # 34% increase\n    support_count=847,          # rows matching this pattern\n    support_percentage=16.9,\n)\n```\n\nKey things to notice:\n\n- **Patterns are combinations of conditions** — humidity AND wind speed together, not just \"more humidity is better\"\n- **Specific thresholds** — 72–89%, not a vague correlation\n- **Novel vs confirmatory** — every pattern is classified; confirmatory ones validate known science, novel ones are what you came for\n- **Citations** — shows what IS known, so you can see what's genuinely new\n- **`report_url`** links to an interactive web report with all patterns visualised\n\nThe `result.summary` gives an LLM-generated narrative overview:\n\n```python\nresult.summary.overview\n# \"Disco identified 14 statistically significant patterns. 5 are novel.\n#  The strongest driver is a previously unreported interaction between humidity\n#  and wind speed at specific thresholds.\"\n\nresult.summary.key_insights\n# [\"Humidity × low wind speed at 72–89% humidity produces a 34% yield increase — novel.\",\n#  \"Soil nitrogen above 45 mg/kg shows diminishing returns when phosphorus is below 12 mg/kg.\",\n#  ...]\n```\n\n---\n\n## How it works\n\nDisco is a pipeline, not prompt engineering over data. It:\n\n1. Trains machine learning models on a subset of your data\n2. Uses interpretability techniques to extract learned patterns\n3. Validates every pattern on the held-out data with FDR correction (Benjamini-Hochberg)\n4. Checks surviving patterns against academic literature via semantic search\n\nYou cannot replicate this by writing pandas code or asking an LLM to look at a CSV. It finds structure that hypothesis-driven analysis misses because it doesn't start with hypotheses.\n\n---\n\n## Preparing your data\n\nBefore running, exclude columns that would produce meaningless findings. Disco finds statistically real patterns — but if the input includes columns that are definitionally related to the target, the patterns will be tautological.\n\n**Exclude:**\n1. **Identifiers** — row IDs, UUIDs, patient IDs, sample codes\n2. **Data leakage** — the target renamed or reformatted (e.g., `diagnosis_text` when the target is `diagnosis_code`)\n3. **Tautological columns** — alternative encodings of the same construct as the target. If target is `serious`, then `serious_outcome`, `not_serious`, `death` are all part of the same classification. If target is `profit`, then `revenue` and `cost` together compose it. If target is a survey index, the sub-items are tautological.\n\n> Full guidance with examples: [SKILL.md](SKILL.md#preparing-your-data)\n\n---\n\n## Parameters\n\n```python\nawait engine.discover(\n    file=\"data.csv\",           # path, Path, or pd.DataFrame\n    target_column=\"outcome\",   # column to predict/explain\n    analysis_depth=2,          # 2=default, higher=deeper analysis, lower = faster and cheaper\n    visibility=\"public\",       # \"public\" (always free, data and report is published) or \"private\" (costs credits)\n    column_descriptions={      # improves pattern explanations and literature context\n        \"bmi\": \"Body mass index\",\n        \"hdl\": \"HDL cholesterol in mg/dL\",\n    },\n    excluded_columns=[\"id\", \"timestamp\"],  # see \"Preparing your data\" above\n    use_llms=False,                        # Defaults to False. If True, runs are slower and more expensive, but you get smarter pre-processing, summary page, literature context and novelty assessment. Public runs always use LLMs.\n    title=\"My dataset\",\n    description=\"...\", # improves pattern explanations and literature context\n)\n```\n\n> Public runs are free but results are published. Set `visibility=\"private\"` for private data — this costs credits.\n\n---\n\n## Running asynchronously\n\nRuns take a few minutes. For agent workflows or scripts that do other work in parallel:\n\n```python\n# Submit without waiting\nrun = await engine.run_async(file=\"data.csv\", target_column=\"outcome\", wait=False)\nprint(f\"Submitted {run.run_id}, continuing...\")\n\n# ... do other things ...\n\nresult = await engine.wait_for_completion(run.run_id, timeout=1800)\n```\n\nFor synchronous scripts and Jupyter notebooks:\n\n```python\nresult = engine.run(file=\"data.csv\", target_column=\"outcome\", wait=True)\n# or: pip install discovery-engine-api[jupyter] for notebook compatibility\n```\n\n---\n\n## MCP server\n\nDisco is available as an MCP server — no local install required.\n\n```json\n{\n  \"mcpServers\": {\n    \"discovery-engine\": {\n      \"url\": \"https://disco.leap-labs.com/mcp\",\n      \"env\": { \"DISCOVERY_API_KEY\": \"disco_...\" }\n    }\n  }\n}\n```\n\nTools: `discovery_list_plans`, `discovery_estimate`, `discovery_upload`, `discovery_analyze`, `discovery_status`, `discovery_get_results`, `discovery_account`, `discovery_signup`, `discovery_signup_verify`, `discovery_login`, `discovery_login_verify`, `discovery_add_payment_method`, `discovery_subscribe`, `discovery_purchase_credits`.\n\n→ [Full agent skill file](SKILL.md)\n\n---\n\n## Pricing\n\n| | Cost |\n|---|---|\n| Public runs | Free — results and data are published |\n| Private runs | Credits vary by file size and configuration — use `engine.estimate()` |\n| Free tier | 10 credits/month, no card required |\n| Researcher | $49/month — 500 credits |\n| Team | $199/month — 2000 credits |\n| Credits | $0.10 per credit |\n\nEstimate before running:\n\n```python\nestimate = await engine.estimate(file_size_mb=10.5, num_columns=25, analysis_depth=2, visibility=\"private\")\n# estimate[\"cost\"][\"credits\"] → 55\n# estimate[\"account\"][\"sufficient\"] → True/False\n```\n\nAccount management is fully programmatic — attach payment methods, subscribe to plans, and purchase credits via the SDK or REST API. See [Python SDK reference](docs/python-sdk.md#account-management) or [SKILL.md](SKILL.md#paying-for-credits-programmatic).\n\n---\n\n## Expected data format\n\nDisco expects a **flat table** — columns for features, rows for samples.\n\n```\n| patient_id | age | bmi  | smoker | outcome |\n|------------|-----|------|--------|---------|\n| 001        | 52  | 28.3 | yes    | 1       |\n| 002        | 34  | 22.1 | no     | 0       |\n| ...        | ... | ...  | ...    | ...     |\n```\n\n- **One row per observation** — a patient, a sample, a transaction, a measurement, etc.\n- **One column per feature** — numeric, categorical, datetime, or free text are all fine\n- **One target column** — the outcome you want to understand. Must have at least 2 distinct values.\n- **Missing values are OK** — Disco handles them automatically. Don't drop rows or impute beforehand.\n- **No pivoting needed** — if your data is already in a flat table, it's ready to go\n\n**Supported formats:** CSV, TSV, Excel (.xlsx), JSON, Parquet, ARFF, Feather. Max 5 GB.\n\n**Not supported:** images, raw text documents, nested/hierarchical JSON, multi-sheet Excel (use the first sheet or export to CSV)\n\n---\n\n## Compared to other tools\n\n| Goal | Tool |\n|---|---|\n| Summary statistics, data quality | ydata-profiling, sweetviz |\n| Predictive model | AutoML (auto-sklearn, TPOT, H2O) |\n| Quick correlations | pandas, seaborn |\n| Answer a specific question about data | ChatGPT, Claude |\n| **Find what you don't know to look for** | **Disco** |\n\nDisco isn't a replacement for EDA or AutoML — it finds the patterns those tools miss. We [tested 18 data analysis tools](https://www.leap-labs.com/research/the-patterns-that-agents-miss) on a dataset with known ground-truth patterns. Most confidently reported wrong results. Disco was the only one that found every pattern.\n\n---\n\n## Links\n\n- [Dashboard](https://disco.leap-labs.com)\n- [API keys](https://disco.leap-labs.com/developers)\n- [Python SDK on PyPI](https://pypi.org/project/discovery-engine-api/)\n- [Python SDK reference](docs/python-sdk.md)\n- [OpenAPI spec](https://disco.leap-labs.com/.well-known/openapi.json)\n- [Agent / MCP docs](SKILL.md)\n- [LLM-friendly reference](llms.txt)\n- [OpenAPI spec](https://disco.leap-labs.com/.well-known/openapi.json)\n- [OpenAPI spec (in-repo)](docs/openapi.json)\n- [Public reports gallery](https://disco.leap-labs.com/discover)\n\n---\n",
  "bytes": 12034,
  "sha": "b567900b5a5bb42f33d964a6afec2683db1aa1eddd4672368746d7114a9e3bac",
  "repo_slug": "leap-laboratories/discovery-engine",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_com_leap_labs_discovery_engine_153a6887/readme"
}