Metadata-Version: 2.4
Name: elemm
Version: 0.6.0
Summary: A protocol for autonomous LLM agents to navigate web applications via semantic landmarks.
Author: Marc Stöcker
License: GPL-3.0-only
Project-URL: Homepage, https://github.com/v3rm1ll1on/elemm
Project-URL: Bug Tracker, https://github.com/v3rm1ll1on/elemm/issues
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Operating System :: OS Independent
Classifier: Framework :: FastAPI
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi
Requires-Dist: pydantic>=2.0
Provides-Extra: examples
Requires-Dist: uvicorn; extra == "examples"
Requires-Dist: httpx; extra == "examples"
Requires-Dist: mcp>=0.1.0; extra == "examples"
Dynamic: license-file

# Elemm: LLM Landmark Protocol

Elemm is a protocol standard for hierarchical structuring of API interfaces for AI agents. It enables agents to efficiently navigate complex toolsets with minimal token consumption and maximum precision.

## Core Concepts

### 1. Landmarks
Landmarks are marked entry points within an API. They function as signposts that guide agents through various functional modules (e.g., IT, HR, Finance).

### 2. Hierarchical Navigation
Instead of presenting a flat list of hundreds of tools, Elemm provides context-specific toolsets. The agent actively navigates between modules, which increases accuracy and minimizes the risk of hallucinations or incorrect tool selection.

### 3. Hybrid Mode (Auto-Flattening)
For small or flat APIs (less than 10 landmarks without a group structure), Elemm automatically switches to a hybrid mode. In this mode, all tools are made directly visible to eliminate navigation overhead for simple tasks.

### 4. Agent Repair Kit (Self-Healing)
Elemm utilizes dynamic correction hints (Remedies). In case of validation errors (HTTP 422), the protocol provides the agent with precise instructions for error resolution instead of having to keep these permanently in the context.

## Features

- **Token Optimization**: Static tool descriptions are stripped of redundant instructions. Contextual help is only delivered when needed.
- **Session Isolation**: Complete separation of navigation states in multi-agent operations through isolated bridge instances per connection.
- **Deep Type Discovery**: Automatic extraction of Enum and Literal types from Pydantic models for precise JSON schemas.
- **Native MCP Support**: Full compatibility with the Model Context Protocol (both Stdio and SSE).

## Quick Start

### Installation

```bash
pip install elemm
```

### Integration with FastAPI

```python
from fastapi import FastAPI
from elemm.fastapi import FastAPIProtocolManager as Elemm

app = FastAPI()
ai = Elemm(agent_welcome="Welcome to the Enterprise ERP System.")

# Define a landmark
@app.get("/finance/audit")
@ai.landmark(id="finance", type="navigation", opens_group="finance")
async def finance_module():
    return {"status": "Active"}

# Register a tool in a group
@app.post("/finance/transfer")
@ai.action(id="transfer", group="finance")
async def transfer_funds(amount: float):
    return {"result": "Success"}

ai.bind_to_app(app)
ai.bind_mcp_sse(app, route_prefix="/mcp")
```

## Migration Path: From Flat to Hierarchical in 3 Steps

If you have an existing flat FastAPI application, you can migrate to the landmark protocol without breaking your existing API:

### 1. Categorize your Routes
Organize your routes using standard FastAPI tags. These tags will become the basis for your navigational structure.

```python
app = FastAPI(openapi_tags=[
    {"name": "it_ops", "description": "Manage infrastructure and logs."}
])

@app.get("/logs", tags=["it_ops"])
async def get_logs(): ...
```

### 2. Initialize and Bind
Initialize the Elemm manager and bind it to your application. This automatically detects your tags and prepares the discovery layer.

```python
from elemm.fastapi import FastAPIProtocolManager as Elemm
ai = Elemm(agent_welcome="You are an Ops Specialist.")

# This automatically creates 'explore_it_ops' from your tags
ai.bind_to_app(app)
```

### 3. Define Entry Points
Mark specific routes as navigation landmarks to activate the hierarchical view.

```python
@app.get("/it/portal")
@ai.landmark(id="it_portal", type="navigation", opens_group="it_ops")
async def it_portal():
    return {"status": "IT Portal Active"}
```

Once these steps are completed, an AI agent will no longer be overwhelmed by a flat list but will instead navigate through your defined modules.

## Architecture and Security

Elemm is designed for enterprise production use:
- **Context Firewall**: The MCP bridge validates tool calls against the agent's current navigation state.
- **Reverse Proxy Support**: Automatically respects `root_path` when behind Nginx or Traefik.
- **Circular Reference Safety**: Safely handles complex, recursive Pydantic models.

## License
GNU General Public License v3.0. Created by Marc Stöcker.
