Metadata-Version: 2.4
Name: letta-ejentum
Version: 0.2.0
Summary: Letta tools for the Ejentum Reasoning Harness. Eight agent-callable functions registered with a Letta server via tools.upsert_from_function: four dynamic (reasoning, code, anti_deception, memory) and four adaptive (adaptive_reasoning, adaptive_code, adaptive_anti_deception, adaptive_memory) that pre-fit the operation to the task via an adapter LLM. Each call returns a structured cognitive injection: a natural-language procedure plus an executable reasoning topology.
Project-URL: Homepage, https://ejentum.com
Project-URL: Documentation, https://ejentum.com/docs/api_reference
Project-URL: Repository, https://github.com/ejentum/letta-ejentum
Project-URL: Issues, https://github.com/ejentum/letta-ejentum/issues
Project-URL: Changelog, https://github.com/ejentum/letta-ejentum/blob/main/CHANGELOG.md
Project-URL: Pricing, https://ejentum.com/pricing
Author-email: Ejentum <info@ejentum.com>
License-Expression: MIT
License-File: LICENSE
Keywords: agentic-ai,ai,anti-deception,cognitive-scaffold,ejentum,letta,llm,memgpt,reasoning-harness,stateful-agents
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: <3.14,>=3.10
Requires-Dist: letta-client>=0.1.0
Requires-Dist: requests>=2.31.0
Provides-Extra: dev
Requires-Dist: build>=1.2.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.6.0; extra == 'dev'
Description-Content-Type: text/markdown

# letta-ejentum

[Letta](https://letta.com) tools for the Ejentum Reasoning Harness. Exposes eight Python functions that upload to a Letta server via `client.tools.upsert_from_function`, plus a `register_ejentum_tools(client)` one-liner that uploads all eight.

Use the harness before the agent generates on complex, multi-step, or multi-constraint tasks where the model's default reasoning template would miss a constraint, take a shortcut, or drift across turns. Each call returns a *cognitive operation*: a structured procedure (numbered steps with a failure pattern to refuse and a falsification test) paired with an executable reasoning topology (a DAG of those steps with decision gates, parallel branches, bounded loops, and meta-cognitive exit nodes). The agent reads both layers before producing its response.

Four dynamic functions (`reasoning`, `code`, `anti_deception`, `memory`) are available on all tiers including the 30-day free trial. Four adaptive functions (`adaptive_reasoning`, `adaptive_code`, `adaptive_anti_deception`, `adaptive_memory`) additionally run an adapter LLM that rewrites the matched operation with task-specific identifiers; they require the Go or Super tier.

Letta uses `func.__name__` as the registered tool name. Python identifiers cannot contain hyphens, so function symbols here use underscores; the on-wire API mode strings stay hyphenated (`anti-deception`, `adaptive-anti-deception`). The translation lives inline in each function body, which Letta's serializer captures.

## Install

```bash
pip install letta-ejentum
```

## Configuration

`EJENTUM_API_KEY` must be set in the **Letta server's** environment, not the local shell. Harness functions execute on the server in Letta's sandbox; the caller process is not the execution environment.

See the Letta docs on tool-env configuration for your deployment (self-hosted, Letta Cloud, etc.). Get an Ejentum API key at [ejentum.com/pricing](https://ejentum.com/pricing).

## Usage

### Register all eight

```python
import os
from letta_client import Letta
from letta_ejentum import register_ejentum_tools

client = Letta(api_key=os.environ["LETTA_API_KEY"])

tools = register_ejentum_tools(client)
tool_ids = [t.id for t in tools]

agent = client.agents.create(
    model="anthropic/claude-sonnet-4-6",
    embedding="openai/text-embedding-3-small",
    tool_ids=tool_ids,
)

response = client.agents.messages.create(
    agent_id=agent.id,
    messages=[
        {"role": "user", "content":
            "We have spent three months on the GraphQL gateway. "
            "Should we keep going or pivot to REST?"},
    ],
)
```

### Register one

```python
from letta_client import Letta
from letta_ejentum import anti_deception

client = Letta(api_key="...")
tool = client.tools.upsert_from_function(func=anti_deception)
```

### Require approval

```python
tools = register_ejentum_tools(client, default_requires_approval=True)
```

## Tool inventory

### Dynamic (all tiers)

| Function | Mode string (on wire) | Library size |
|---|---|---:|
| `reasoning(query)` | `reasoning` | 311 |
| `code(query)` | `code` | 128 |
| `anti_deception(query)` | `anti-deception` | 139 |
| `memory(query)` | `memory` | 101 |

### Adaptive (Go or Super tier)

| Function | Mode string (on wire) |
|---|---|
| `adaptive_reasoning(query)` | `adaptive-reasoning` |
| `adaptive_code(query)` | `adaptive-code` |
| `adaptive_anti_deception(query)` | `adaptive-anti-deception` |
| `adaptive_memory(query)` | `adaptive-memory` |

Each function takes a single `query: str` argument and returns the injection as a string. For `memory` and `adaptive_memory`, format as `"I noticed X. This might mean Y. Sharpen: Z."`.

Errors return as strings; functions do not raise.

## Why the unusual design

Letta's tool model serializes the function source and executes it in a sandbox. That forces three constraints:

- **Imports inside the function body**, not at module top. Letta's serializer captures what the function needs at execution time.
- **No constructor**, no instance state. Configuration (`EJENTUM_API_KEY`, `api_url`) lives in the Letta server's environment.
- **Google-style docstrings**, which Letta parses into the OpenAI tool schema.

The eight functions are intentionally verbose (some imports and the API URL repeated per function) because each must stand alone for the serializer.

## API reference

```python
from letta_ejentum import (
    reasoning, code, anti_deception, memory,
    adaptive_reasoning, adaptive_code, adaptive_anti_deception, adaptive_memory,
    HARNESS_FUNCTIONS,           # tuple of all eight
    register_ejentum_tools,      # uploads all eight to a Letta server
)

register_ejentum_tools(
    client,                                # letta_client.Letta instance
    default_requires_approval: bool = False,
) -> list[letta_client.types.Tool]
```

## Wire contract

```
POST https://api.ejentum.com/harness/
Headers: Authorization: Bearer <key>, Content-Type: application/json
Body:    { "query": <string>, "mode": <one of 8 mode strings> }
Response (200): [ { "<mode>": "<injection string>" } ]
Response (401|403|429): { "error": "..." }
```

Full wire contract, field structure of an injection, DAG syntax, and a canonical dynamic-vs-adaptive comparison on the same query are documented in the [ejentum-mcp README](https://github.com/ejentum/ejentum-mcp#wire-contract).

## ejentum-mcp alternative

Letta also has an MCP client that can consume the hosted endpoint at `https://api.ejentum.com/mcp` with Bearer auth. The PyPI package skips MCP wiring and reduces tool-attach to one line.

## Compatibility

- Python 3.10+
- `letta-client>=0.1.0`
- `requests>=2.31.0` (the call happens inside the function on the Letta server, which provides its own runtime)

## License

[MIT](./LICENSE)


## Measured effects

The Ejentum harness is benchmarked publicly under CC BY 4.0 at [github.com/ejentum/benchmarks](https://github.com/ejentum/benchmarks):

- **ELEPHANT** sycophancy: 5.8% composite on GPT-4o (40 real Reddit scenarios)
- **LiveCodeBench Hard**: 85.7% to 100% on Claude Opus (28 competitive programming tasks)
- **Memory retention**: 50% fewer stale facts served (20-turn implicit state changes)
- Plus per-harness numbers across BBH/CausalBench/MuSR, ARC-AGI-3, SciCode, and perception tasks

Methodology, scenarios, run scripts, and raw outputs are all in-repo.
