Semantic Extractor

Griffe + constraints, served over MCP.

Ground truth about framework usage rules, not just API signatures.

---

The Problem

Griffe tells you what a framework has. It doesn't tell you how the framework forces you to use it.

• Which decorators can nest?
• What signature transformations happen?
• What are the type constraints?
• Where can a decorator legally be placed?

LLMs need these rules to generate correct code.

---

The Solution

Semantic Extractor compiles framework source code into a structured IR bundle that captures:

Layer	What It Captures	Example
API signatures	Functions, classes, methods (Griffe-compatible)	def command(...)
Decorator placement	Where decorators can legally appear	`COMMAND_BUILDER = FUNCTION
Signature invariants	How decorators transform function signatures	--kebab-case → snake_case parameter
Type constraints	Validation rules for parameters	Path constraints: exists, file_okay, writable
Graph edges	Parent-child relationships	group → command (contains_command)
Node roles	Multi-role bitmask	`COMMAND

Then serves it over MCP for token-efficient, on-demand retrieval.

---

The Pattern

Framework Source Code
        ↓
[Semantic Extractor] → Static Analysis → IR Bundle (JSON)
        ↓
[MCP Server] → Queryable Knowledge for LLMs
        ↓
LLM asks: "What are the constraints on @click.option?"
MCP replies: "Must be FUNCTION. Transforms kebab-case to snake_case. Injects as keyword argument."

Griffe gives you the mirror. Semantic Extractor gives you the compiler.

---

What It Offers That Traditional MCP Tools Don't

	Traditional MCP	Semantic Extractor
Knowledge source	Documentation (stale, incomplete)	Source code (ground truth)
What it knows	What the framework does	How the framework must be used
Granularity	Function-level	Constraint-level
Output	Natural language descriptions	Structured invariants + rules
Guarantees	"Probably correct"	Ground truth from source

---

Supported Frameworks (Validated)

Python

• Click (decorator constraints, signature invariants)
• Loguru (lazy evaluation, binding, sinks)
• Flask (routes, methods, blueprints)
• HTTPX (client, request/response)
• SQLModel (models, relationships)
• Textual (widgets, bindings, messages)
• Starlette (routes, middleware)
• Dishka (dependency injection)
• Griffe (API extraction)
• Snoop (debugging)

Lua/Luau

• Luau (Roblox) (type system, constraints)
• Lua (bundle)

Swift

• SwiftUI (view modifiers, state, bindings)

---

MCP Tools (Planned)

Tool	Description
get_framework_info	Framework metadata, version, capabilities
get_decorator_constraint	Placement rules for a decorator
get_signature_invariant	Signature transformation rules
get_type_constraint	Type validation rules
get_command_edges	Parent-child relationship graph
get_node_role	Role bitmask for a symbol

The LLM doesn't guess. It retrieves ground truth.

---

Example: Click Decorator Constraints

# Without Semantic Extractor
LLM: "I'll nest a @click.command inside another @click.command"
# → Wrong. Only groups can nest commands.

# With Semantic Extractor
LLM → MCP: get_decorator_constraint("command")
MCP → LLM: "COMMAND_BUILDER = FUNCTION | TOP_LEVEL. Cannot be nested."
LLM: "I must use @click.group to nest commands."

The LLM retrieves the rule before generating incorrect code.

---

Repository Structure

semantic-extractor/
├── extractors/
│   ├── python/
│   │   ├── calyx_click_v6.py
│   │   ├── calyx_loguru.py
│   │   ├── calyx_flask_v6.py
│   │   └── ...
│   ├── lua/
│   └── swift/
├── bundles/
│   ├── calyx_click_v6.json
│   ├── calyx_loguru_v6.json
│   └── ...
├── mcp/
│   └── server.py (coming soon)
└── README.md

---

License

MIT

---

Griffe tells you what exists. Semantic Extractor tells you how it must be used.