Decompose

🚀 Decompose

Deterministic text classification for AI agents. Decompose turns any text into classified, structured semantic units instantly without an LLM or setup, just with one function call.

Stop prompting. Start decomposing.

🚀 Quick Start

Decompose is designed to perform deterministic text classification for AI agents. It can instantly transform any text into classified and structured semantic units without relying on an LLM or any setup, simply through a single function call.

Before and After Example

Before: Your agent reads this

The contractor shall provide all materials per ASTM C150-20. Maximum load
shall not exceed 500 psf per ASCE 7-22. Notice to proceed within 14 calendar
days of contract execution. Retainage of 10% applies to all payments.
For general background, the project is located in Denver, CO...

After: Your agent reads this

[
  {
    "text": "The contractor shall provide all materials per ASTM C150-20.",
    "authority": "mandatory",
    "risk": "compliance",
    "type": "requirement",
    "irreducible": true,
    "attention": 8.0,
    "entities": ["ASTM C150-20"]
  },
  {
    "text": "Maximum load shall not exceed 500 psf per ASCE 7-22.",
    "authority": "prohibitive",
    "risk": "safety_critical",
    "type": "constraint",
    "irreducible": true,
    "attention": 10.0,
    "entities": ["ASCE 7-22"]
  }
]

As shown above, every unit is classified, every standard is extracted, and every risk is scored. This way, your agent can clearly identify what matters.

📦 Installation

pip install decompose-mcp

💻 Usage Examples

Use as MCP Server

Add to your agent's MCP config (Claude Code, Cursor, Windsurf, etc.):

{
  "mcpServers": {
    "decompose": {
      "command": "uvx",
      "args": ["decompose-mcp", "--serve"]
    }
  }
}

Your agent will then have access to two tools:

• decompose_text — Decompose any text.
• decompose_url — Fetch a URL and decompose its content.

OpenClaw

You can install the skill from ClawHub or configure it directly:

{
  "mcpServers": {
    "decompose": {
      "command": "python3",
      "args": ["-m", "decompose", "--serve"]
    }
  }
}

Or install the skill using the command: clawdhub install decompose-mcp

Use as CLI

# Pipe text
cat spec.txt | decompose --pretty

# Inline
decompose --text "The contractor shall provide all materials per ASTM C150-20."

# Compact output (smaller JSON)
cat document.md | decompose --compact

Use as Library

from decompose import decompose_text, filter_for_llm

result = decompose_text("The contractor shall provide all materials per ASTM C150-20.")

for unit in result["units"]:
    print(f"[{unit['authority']}] [{unit['risk']}] {unit['text'][:60]}...")

# Pre-filter for LLM context — keep only high-value units
filtered = filter_for_llm(result, max_tokens=4000)
print(f"{filtered['meta']['reduction_pct']}% token reduction")
llm_input = filtered["text"]  # Ready for your LLM

📚 Documentation

What Each Field Means

What to Build With This

Decompose is not the end goal. It's a crucial pre - LLM step that many developers overlook, not because it's difficult, but because they're unaware of its existence. Documents have a structure that can be classified, and this classification should occur before reasoning.

Without:  document → chunk → embed → retrieve → LLM → answer  (100% of tokens)
With:     document → decompose → filter/route → LLM → answer  (20-40% of tokens)

Filter: built-in LLM pre-filter

filter_for_llm() retains mandatory, safety - critical, financial, and compliance units, eliminating boilerplate content before it reaches your LLM or vector store.

from decompose import decompose_text, filter_for_llm

result = decompose_text(open("contract.md").read())
filtered = filter_for_llm(result, max_tokens=4000)

# filtered["text"] = high-value units only, ready for LLM
# filtered["meta"]["reduction_pct"] = how much was dropped (typically 60-80%)

# Or use the units directly for embedding
for unit in filtered["units"]:
    embed_and_store(unit["text"], metadata={
        "authority": unit["authority"],
        "risk": unit["risk"],
        "attention": unit["attention"],
    })

Route: risk-based processing

Safety - critical content is directed to one processing chain, financial content to another, and boilerplate content can be skipped.

from decompose import decompose_text

result = decompose_text(spec_text)

for unit in result["units"]:
    if unit["risk"] == "safety_critical":
        safety_chain.process(unit)       # Full analysis + human review
    elif unit["risk"] == "financial":
        audit_chain.process(unit)         # Flag for finance team
    elif unit["attention"] < 0.5:
        pass                              # Skip boilerplate
    else:
        general_chain.process(unit)       # Standard LLM analysis

Measure: token cost reduction

from decompose import decompose_text

result = decompose_text(spec_text)
total = len(result["units"])
high = [u for u in result["units"] if u["attention"] >= 1.0]

print(f"{len(high)}/{total} units need LLM analysis")
print(f"{100 - len(high) * 100 // total}% token reduction")

You can find runnable scripts in the directory.

Why No LLM?

Decompose operates based on pure regex and heuristics. It doesn't require Ollama, an API key, a GPU, or any inference cost.

This design has several advantages:

• Fast: It can process a 50 - page spec in less than 500ms.
• Deterministic: The same input always yields the same output.
• Offline: It can work in an air - gapped environment, on a plane, or in a CI pipeline.
• Composable: Your agent's LLM can perform reasoning on the structured output, while Decompose handles the preprocessing.

The LLM is used by your agent, and Decompose enhances the performance of whatever model you're using.

Built by Echology

Decompose is developed by Echology and is extracted from AECai, a document intelligence platform for Architecture, Engineering, and Construction firms. Its classification patterns, entity extraction, and irreducibility detection have been thoroughly tested against thousands of real AEC documents, including specs, contracts, RFIs, inspection reports, and pay applications.

Decompose has gained its independence. It originated as AECai's text classification module, demonstrated its generality across different domains (insurance, trading, regulatory), and was released as a standalone tool. It is free and licensed under the MIT license.

Case Study: Open Scripture Intelligence

The same chunking and entity extraction patterns used for classifying engineering specs can also structure the Bible. Open Scripture Intelligence utilizes 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 that the methodology is domain - agnostic.

Blog

• When Regex Beats an LLM — Decompose classifies the MCP spec in 3.78ms
• Why Your Agent Needs a Cognitive Primitive — attention scoring, irreducibility, and routing
• What "Simulation - Aware" Actually Means — the architecture behind AECai

📄 License

MIT — Copyright (c) 2025 - 2026 Echology, Inc.