Metadata-Version: 2.4
Name: elemm
Version: 1.3.1
Summary: AI Landmarks: The specialized protocol for autonomous agent discovery.
Author: Marc Stöcker
License: Business Source License 1.1
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 :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Framework :: FastAPI
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic>=2.0
Requires-Dist: httpx>=0.24.0
Requires-Dist: mcp>=0.1.0
Requires-Dist: pyyaml
Requires-Dist: starlette
Requires-Dist: uvicorn
Requires-Dist: fastapi
Requires-Dist: websockets
Dynamic: license-file

# Elemm: The Landmark Manifest Protocol

[![PyPI version](https://img.shields.io/pypi/v/elemm?style=flat-square&color=blue)](https://pypi.org/project/elemm/)
[![Downloads](https://img.shields.io/pypi/dm/elemm?style=flat-square&color=darkgreen)](https://pypi.org/project/elemm/)
[![Build Status](https://img.shields.io/github/actions/workflow/status/v3rm1ll1on/elemm/workflow.yml?branch=main&style=flat-square)](https://github.com/v3rm1ll1on/elemm/actions/workflows/workflow.yml)
[![License](https://img.shields.io/badge/License-BSL_1.1-orange?style=flat-square)](https://github.com/v3rm1ll1on/elemm/blob/main/LICENSE)
[![Discord](https://img.shields.io/badge/Discord-%235865F2.svg?style=flat-square&logo=discord&logoColor=white)](https://discord.gg/Na5aBca8bR)
[![Python versions](https://img.shields.io/badge/python-3.10+-blue?style=flat-square)](https://pypi.org/project/elemm/)
[![Website](https://img.shields.io/badge/Website-elemm.dev-teal?style=flat-square)](https://elemm.dev)

<p align="center">
  <a href="https://elemm.dev">
    <img src="docs/images/elemm_logo.png" alt="Elemm Logo" width="600" />
  </a>
</p>

**The Infrastructure for the Agentic Web.**

Elemm is the **Landmark Manifest Protocol**, a next-generation communication framework designed to transform how autonomous LLM agents interact with the digital world. Instead of static tool definitions, Elemm provides a **dynamic, manifest-driven architecture** that enables agents to discover, navigate, and execute complex workflows across distributed APIs with unprecedented efficiency.

---

## Quick Start

### 1. Install
```bash
python3 -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install elemm
```

### 2. Generate your MCP Client Configuration

The easiest way to connect your MCP Client (e.g., Cursor, Claude Desktop) is to use the built-in configuration generator. It automatically detects your OS, paths, and WSL environment:

```bash
elemm-gateway cfg-gen
```

Follow the interactive prompts to generate your JSON config snippet, then copy and paste it into your MCP client's configuration file.

### 3. Start the Dashboard (Optional but Recommended)

Launch the interactive dashboard to monitor tokens, manage credentials (Vault), configure security policies, and generate configs visually:

```bash
elemm-dashboard
```
Open `http://localhost:8090` in your browser.

### 4. Start Discovering

Once connected, tell your agent:
> *"Use Elemm to connect to https://petstore.swagger.io/v2/swagger.json and list all available pets."*

The Gateway provides **9 core tools** to the agent. All domain-specific actions are discovered on-the-fly via the Elemm protocol.

### 5. Build Your Own Landmark Server (Optional)

You can turn any Python function into a high-performance landmark using decorators. Depending on your needs, you can expose these landmarks in two ways:

#### Option A: FastAPI (Web-based via HTTP/SSE)
Exposes the landmarks as a standard web service / API:

```python
import uvicorn
from fastapi import FastAPI
from elemm import AIProtocolManager, MetadataRegistry
from elemm.gateways.fastapi import FastAPIGateway

app = FastAPI()
registry = MetadataRegistry("landmarks.yaml")
manager = AIProtocolManager(registry=registry)

@manager.landmark("security:quarantine_node")
async def quarantine_node(node_id: str, urgent: bool = False):
    """Quarantines a compromised server node."""
    return {"status": "success", "node": node_id}

# Expose the Elemm manifest and endpoint dynamically on your FastAPI app
gateway = FastAPIGateway(manager)
gateway.bind_to_app(app)

if __name__ == "__main__":
    uvicorn.run(app, host="0.0.0.0", port=8000)
```

#### Option B: Standalone MCP (Local via STDIO)
Exposes the landmarks directly as a local STDIO MCP server:

```python
from elemm import ElemmGateway

# Initialize the high-level gateway wrapper
gateway = ElemmGateway(name="MySecurityServer")

@gateway.action("security:quarantine_node")
async def quarantine_node(node_id: str, urgent: bool = False):
    """Quarantines a compromised server node."""
    return {"status": "success", "node": node_id}

# Run directly as a local STDIO MCP Server!
if __name__ == "__main__":
    gateway.run_mcp()
```

### Advanced Usage

- **Pydantic Discovery**: Elemm automatically generates schemas from Pydantic models.
- **Response Hygiene**: Built-in `_select`, `_filter`, `_limit`, and `_offset` parameters prevent context overflow.
- **Session Isolation**: Use `session_id` to run parallel tasks without cross-contamination.
- **Self-Healing**: The SmartRepair engine provides agents with actionable remedies when errors occur.
- **Search**: Use `search_landmarks(query)` with Python REGEX to locate tools instantly without full hierarchy traversal.
- **Dashboard**: Start the dashboard via `elemm-dashboard` for a real-time observability UI on port 8090.

---

## The Vision: Agentic Web
In the Agentic Web, every API is a "Landmark". Agents no longer need massive, hardcoded system prompts to understand a service. They discover capabilities on-the-fly via a standardized manifest, just like a human navigates a website.

- **Unified Discovery**: Every Elemm-compliant server exposes its structure at `/.well-known/elemm-manifest.md`.
- **Zero System Prompt**: By providing rich semantic landmarks and manifest-driven discovery, you can eliminate thousands of tokens from your system prompts. The protocol *is* the documentation.
- **One MCP Server, Infinite APIs**: The built-in **Elemm Gateway** connects to any OpenAPI, GraphQL, or native Elemm service. A single `pip install` gives you a universal MCP server that discovers and loads landmarks on-the-fly, allowing you to scale your agent's capabilities without ever restarting your infrastructure.

---

## The Philosophy: Decoupling Intelligence

Elemm is more than just a protocol; it's a shift toward **Decentralized Intelligence**. In the traditional SaaS model, providers often bundle their APIs with expensive, centralized LLM interfaces. Elemm decouples the "Body" (the API) from the "Brain" (the Agent).

### Bring Your Own Agent (BYOA)
With Elemm, API providers only define the **Landmarks** and **Manifests**. The user brings their own autonomous agent to the platform. This shifts the computational burden and cost of "reasoning" to the edge—the user's own system.

### Sustainability & Efficiency
By eliminating the need for massive, repetitive system prompts and context-heavy tool injections, Elemm significantly reduces the global token footprint of AI interactions.
- **Lower Latency**: No more waiting for centralized "gatekeeper" models to process 20k tokens of documentation.
- **Reduced CO2 & Energy**: Fewer tokens mean less GPU compute time, directly translating into a lower carbon footprint for every autonomous task.
- **Cost Sovereignty**: Providers save on LLM hosting and token costs, while users get the freedom to choose the model that best fits their task and budget.

---

## Core Advantages

Standard protocols like MCP often struggle with large-scale toolsets. Elemm provides a structural solution:

- **Efficient Discovery**: Agents only see a high-level manifest, loading detailed tool schemas only when needed (on-demand inspection).
- **Direct Search**: `search_landmarks(query)` enables regex-based tool discovery without traversing the full hierarchy — ideal for large API surfaces.
- **Atomic Sequencing**: Execute multiple tool calls in a single LLM turn with native variable piping (`$step0.id`).
- **Multi-Protocol Gateway**: Connect to any **OpenAPI**, **GraphQL**, or **native Elemm** service through a single MCP server.
- **Security Policy Engine**: Built-in Guardian mode with Zero-Trust whitelist, pattern blacklists, landmark restrictions, HTTP method filtering, and Data Loss Prevention.
- **SmartRepair Engine**: Built-in error handling that provides agents with actionable remedies instead of cryptic stack traces.
- **Token Economy**: Reduces input tokens by up to 90% in complex forensic and administrative scenarios.
- **Observability Dashboard**: Optional web UI for real-time monitoring, API exploration, and configuration management.

---

## Documentation

*   **[Website & Live Docs](https://elemm.dev)**: Visit our official website for the latest documentation and updates.
*   **[Getting Started](docs/GETTING_STARTED.md)**: Install and run your first Elemm setup.
*   **[Gateway Reference](docs/GATEWAY.md)**: Complete reference for the Elemm Gateway (OpenAPI, GraphQL, Security, Vault).
*   **[Developer Guide](docs/DEVELOPER_GUIDE.md)**: Build your own landmark servers with decorators and Pydantic.
*   **[Architecture Overview](docs/ARCHITECTURE.md)**: Deep dive into the Elemm philosophy and package structure.
*   **[Protocol Specification](docs/PROTOCOL_SPEC.md)**: Technical details for implementers.
*   **[Dashboard & Observability](docs/DASHBOARD.md)**: The Gateway UI — monitoring, config, and API explorer.
*   **[Benchmarking Results](docs/BENCHMARKING.md)**: Performance analysis vs. standard MCP.

---

## License & Commercial Use

Copyright (C) 2026 Marc Stöcker.

Licensed under the **Business Source License 1.1 (BSL 1.1)**.

### What does this mean for you?

* **Startups, Indie Developers & Solo Creators:** If your organization has **fewer than 50 employees** (full-time equivalents) AND **less than $5,000,000 USD** in annual gross revenue, you can use Elemm (both Core and Gateway) **completely free of charge** for any purpose, including commercial production.
* **Large Enterprises:** If you exceed either of these thresholds, you must obtain a commercial license. Please reach out to `v3rm1ll1on@proton.me` to discuss commercial licensing.
* **Long-Term Open Source Guarantee:** 4 years after the release of each version, the license for that version automatically converts to the **Mozilla Public License 2.0 (MPL 2.0)**, ensuring Elemm remains free and open-source in the long run.

For the full license terms, please see the [LICENSE](LICENSE) file.
