{
  "markdown": "# Decompose\n\n[![CI](https://github.com/echology-io/decompose/actions/workflows/ci.yml/badge.svg)](https://github.com/echology-io/decompose/actions/workflows/ci.yml)\n[![PyPI](https://img.shields.io/pypi/v/decompose-mcp)](https://pypi.org/project/decompose-mcp/)\n[![Python](https://img.shields.io/pypi/pyversions/decompose-mcp)](https://pypi.org/project/decompose-mcp/)\n\n<!-- mcp-name: io.github.echology-io/decompose -->\n\n**Stop prompting. Start decomposing.**\n\nDeterministic text classification for AI agents. Decompose turns any text into classified, structured semantic units — instantly. No LLM. No setup. One function call.\n\n---\n\n### Before: your agent reads this\n\n```\nThe contractor shall provide all materials per ASTM C150-20. Maximum load\nshall not exceed 500 psf per ASCE 7-22. Notice to proceed within 14 calendar\ndays of contract execution. Retainage of 10% applies to all payments.\nFor general background, the project is located in Denver, CO...\n```\n\n### After: your agent reads this\n\n```json\n[\n  {\n    \"text\": \"The contractor shall provide all materials per ASTM C150-20.\",\n    \"authority\": \"mandatory\",\n    \"risk\": \"compliance\",\n    \"type\": \"requirement\",\n    \"irreducible\": true,\n    \"attention\": 8.0,\n    \"entities\": [\"ASTM C150-20\"]\n  },\n  {\n    \"text\": \"Maximum load shall not exceed 500 psf per ASCE 7-22.\",\n    \"authority\": \"prohibitive\",\n    \"risk\": \"safety_critical\",\n    \"type\": \"constraint\",\n    \"irreducible\": true,\n    \"attention\": 10.0,\n    \"entities\": [\"ASCE 7-22\"]\n  }\n]\n```\n\nEvery unit classified. Every standard extracted. Every risk scored. Your agent knows what matters.\n\n---\n\n## Install\n\n```bash\npip install decompose-mcp\n```\n\n## Use as MCP Server\n\nAdd to your agent's MCP config (Claude Code, Cursor, Windsurf, etc.):\n\n```json\n{\n  \"mcpServers\": {\n    \"decompose\": {\n      \"command\": \"uvx\",\n      \"args\": [\"decompose-mcp\", \"--serve\"]\n    }\n  }\n}\n```\n\nYour agent gets two tools:\n- **`decompose_text`** — decompose any text\n- **`decompose_url`** — fetch a URL and decompose its content\n\n### OpenClaw\n\nInstall the skill from ClawHub or configure directly:\n\n```json\n{\n  \"mcpServers\": {\n    \"decompose\": {\n      \"command\": \"python3\",\n      \"args\": [\"-m\", \"decompose\", \"--serve\"]\n    }\n  }\n}\n```\n\nOr install the skill: `clawdhub install decompose-mcp`\n\n## Use as CLI\n\n```bash\n# Pipe text\ncat spec.txt | decompose --pretty\n\n# Inline\ndecompose --text \"The contractor shall provide all materials per ASTM C150-20.\"\n\n# Compact output (smaller JSON)\ncat document.md | decompose --compact\n```\n\n## Use as Library\n\n```python\nfrom decompose import decompose_text, filter_for_llm\n\nresult = decompose_text(\"The contractor shall provide all materials per ASTM C150-20.\")\n\nfor unit in result[\"units\"]:\n    print(f\"[{unit['authority']}] [{unit['risk']}] {unit['text'][:60]}...\")\n\n# Pre-filter for LLM context — keep only high-value units\nfiltered = filter_for_llm(result, max_tokens=4000)\nprint(f\"{filtered['meta']['reduction_pct']}% token reduction\")\nllm_input = filtered[\"text\"]  # Ready for your LLM\n```\n\n---\n\n## What Each Field Means\n\n| Field | Values | What It Tells Your Agent |\n|-------|--------|--------------------------|\n| `authority` | mandatory, prohibitive, directive, permissive, conditional, informational | Is this a hard requirement or background? |\n| `risk` | safety_critical, security, compliance, financial, contractual, advisory, informational | How much does this matter? |\n| `type` | requirement, definition, reference, constraint, narrative, data | What kind of content is this? |\n| `irreducible` | true/false | Must this be preserved verbatim? |\n| `attention` | 0.0 - 10.0 | How much compute should the agent spend here? |\n| `entities` | standards, codes, regulations | What formal references are cited? |\n| `actionable` | true/false | Does someone need to do something? |\n\n---\n\n## What to Build With This\n\nDecompose is not the destination. It's the step before the LLM that most developers skip — not because it's hard, but because nobody showed them it exists. Documents have structure. That structure is classifiable. And classification should happen before reasoning.\n\n```\nWithout:  document → chunk → embed → retrieve → LLM → answer  (100% of tokens)\nWith:     document → decompose → filter/route → LLM → answer  (20-40% of tokens)\n```\n\n### Filter: built-in LLM pre-filter\n\n`filter_for_llm()` keeps mandatory, safety-critical, financial, and compliance units — drops boilerplate before it reaches your LLM or vector store.\n\n```python\nfrom decompose import decompose_text, filter_for_llm\n\nresult = decompose_text(open(\"contract.md\").read())\nfiltered = filter_for_llm(result, max_tokens=4000)\n\n# filtered[\"text\"] = high-value units only, ready for LLM\n# filtered[\"meta\"][\"reduction_pct\"] = how much was dropped (typically 60-80%)\n\n# Or use the units directly for embedding\nfor unit in filtered[\"units\"]:\n    embed_and_store(unit[\"text\"], metadata={\n        \"authority\": unit[\"authority\"],\n        \"risk\": unit[\"risk\"],\n        \"attention\": unit[\"attention\"],\n    })\n```\n\n### Route: risk-based processing\n\nSafety-critical content goes to one chain. Financial content goes to another. Boilerplate gets skipped.\n\n```python\nfrom decompose import decompose_text\n\nresult = decompose_text(spec_text)\n\nfor unit in result[\"units\"]:\n    if unit[\"risk\"] == \"safety_critical\":\n        safety_chain.process(unit)       # Full analysis + human review\n    elif unit[\"risk\"] == \"financial\":\n        audit_chain.process(unit)         # Flag for finance team\n    elif unit[\"attention\"] < 0.5:\n        pass                              # Skip boilerplate\n    else:\n        general_chain.process(unit)       # Standard LLM analysis\n```\n\n### Measure: token cost reduction\n\n```python\nfrom decompose import decompose_text\n\nresult = decompose_text(spec_text)\ntotal = len(result[\"units\"])\nhigh = [u for u in result[\"units\"] if u[\"attention\"] >= 1.0]\n\nprint(f\"{len(high)}/{total} units need LLM analysis\")\nprint(f\"{100 - len(high) * 100 // total}% token reduction\")\n```\n\nSee [`examples/`](examples/) for runnable scripts.\n\n---\n\n## Why No LLM?\n\nDecompose runs on pure regex and heuristics. No Ollama, no API key, no GPU, no inference cost.\n\nThis is intentional:\n- **Fast**: <500ms for a 50-page spec\n- **Deterministic**: Same input always produces same output\n- **Offline**: Works air-gapped, on a plane, on CI\n- **Composable**: Your agent's LLM reasons over the structured output — decompose handles the preprocessing\n\nThe LLM is what *your agent* uses. Decompose makes whatever model you're running work better.\n\n---\n\n## Built by Echology\n\nDecompose is built by [Echology](https://echology.io) and extracted from [AECai](https://aecai.io), a document intelligence platform for Architecture, Engineering, and Construction firms. The classification patterns, entity extraction, and irreducibility detection are battle-tested against thousands of real AEC documents — specs, contracts, RFIs, inspection reports, pay applications.\n\nDecompose earned its independence — it started as AECai's text classification module, proved general enough to work across domains (insurance, trading, regulatory), and was released standalone. Free, MIT-licensed.\n\n### Case Study: Open Scripture Intelligence\n\nThe same chunking and entity extraction patterns that classify engineering specs also structure the Bible. [Open Scripture Intelligence](https://github.com/echology-io/open-scripture-intelligence) uses Decompose's Markdown-aware chunker and regex entity extraction to transform 31,100 verses into a knowledge graph with 344,799 cross-reference edges and semantic embeddings — proving the methodology is domain-agnostic.\n\n### Blog\n\n- [When Regex Beats an LLM](https://echology.io/blog/regex-beats-llm) — Decompose classifies the MCP spec in 3.78ms\n- [Why Your Agent Needs a Cognitive Primitive](https://echology.io/blog/cognitive-primitive) — attention scoring, irreducibility, and routing\n- [What \"Simulation-Aware\" Actually Means](https://echology.io/blog/simulation-aware) — the architecture behind AECai\n\n**License:** MIT — Copyright (c) 2025-2026 Echology, Inc.\n",
  "bytes": 8071,
  "sha": "ce508138dc690507c0cc606bde1b1fde86b4b6152cc6ddb4eccdd5d24f46013e",
  "repo_slug": "echology-io/decompose",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_echology_io_decompose_9e12ce7b/readme"
}