Metadata-Version: 2.4
Name: eidolon-framework
Version: 0.4.1
Summary: EIDOLON behavioral control plane for language models
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# EIDOLON

**Behavioral control plane for large language models.**

EIDOLON is a runtime governance framework that sits between user input and LLM output generation. It enforces behavioral policy, maintains cryptographically chained provenance records of every turn, and provides deterministic interpretation of user intent before any generative model is invoked.

Current version: **0.4.0**

---

## What It Does

Most AI governance approaches try to train behavioral problems away or post-process outputs after the fact. EIDOLON operates at runtime — before and after every turn — and produces a tamper-evident audit trail that proves what the model said, in what state, under what routing conditions, and with what epistemic basis.

**Core capabilities:**

- **State machine enforcement** — discrete runtime states (LOCKED, READY, MEMNO, FOUNDER, ERROR) with policy-gated transitions. No output reaches the user outside a valid state path.
- **Frontdoor interpretation** — upstream deterministic classification of user input by concept family and discourse role before routing to the generative pipeline. Nine concept families handled deterministically: handshake, protected mode, focus restoration, coherence loop, memory snapshot, memory load, integrity check, help, and command explanation.
- **APDAT provenance logging** — every turn produces a cryptographically chained event record. Each record embeds runtime state, routing rationale (including whether output was deterministic or model-generated), epistemic contract, and audit result. Records are chained via SHA-512 with per-event RNG tokens and variable-length output, providing a minimum 2^128 quantum collision resistance floor.
- **Memory management** — durable memory with sandboxed inspection mode (MEMNO). Load snapshots into a protected sandbox, inspect drift, commit or discard without risk to the baseline.
- **Epistemic posture enforcement** — every model-generated response carries a structured contract: basis type (memory / deduction / assumption / uncertain / mixed), chain status, and missing variables. Responses that cannot meet the contract do not pass audit.
- **Middleware API** — embeddable as a drop-in governance layer for any system driving an LLM backend.

---

## Architecture

```
User Input
    │
    ▼
RuntimeFrontDoorInterpreter        ← deterministic interpretation, 9 concept families
    │ (if deterministic match)
    ▼
_route_runtime_interpretation()    ← routes to direct execution, no model invocation
    │
    │ (if no frontdoor match)
    ▼
PolicyEngine                       ← state-gated behavioral constraints
    │
    ▼
EidolonPipeline                    ← memory retrieval → framing → generation → audit
    │
    ▼
APDATLogger                        ← cryptographically chained provenance record
    │
    ▼
SessionResponse → caller
```

---

## Middleware Integration

The fastest path to wiring EIDOLON into an existing system:

```bash
git clone https://github.com/DToxxiccity/EIDOLON.git
cd EIDOLON
pip install -e .
```

```python
from eidolon import EidolonMiddleware, MiddlewareConfig, LLMClient

class YourBackend(LLMClient):
    def generate(self, system_prompt: str, user_prompt: str,
                 temperature: float, max_tokens: int, stop=None) -> str:
        # Call your model — return a plain string
        return your_model.complete(system_prompt, user_prompt)

middleware = EidolonMiddleware(
    YourBackend(),
    config=MiddlewareConfig(session_id="user-123")
)

while True:
    user_text = get_input()
    turn = middleware.process(user_text)
    send_output(turn.output_text)
    if turn.should_exit:
        break
```

**`MiddlewareTurn` fields:**

| Field | Type | Description |
|---|---|---|
| `output_text` | `str` | Response to deliver to the user |
| `runtime_state` | `RuntimeState` | Current state after this turn |
| `should_exit` | `bool` | Clean session end signal |
| `audit_passed` | `bool \| None` | APDAT audit result for this turn |
| `session_turn` | `SessionTurn \| None` | Full provenance record |

**Optional hook** — receive every turn for external observability:

```python
def my_hook(turn: MiddlewareTurn) -> None:
    if not turn.audit_passed:
        forward_to_security_log(turn.session_turn)

config = MiddlewareConfig(session_id="user-123", on_turn=my_hook)
```

---

## Running Locally

Requires Python 3.11+. Connects to an OpenAI-compatible local endpoint (LM Studio by default).

```powershell
python .\run_local.py --model local-model --base-url http://127.0.0.1:1234/v1
```

To begin a session, type: `I am the bridge`

---

## APDAT Provenance

Every turn is logged to `logs/apdat_log.ndjson` as an append-only NDJSON record. Each event contains:

- Input hash, draft hash, final output hash (SHA-512, variable-length, 96–128 hex chars)
- Per-event RNG token mixed into hash input before hashing
- Previous event hash — chains the entire log cryptographically
- Runtime state, route frame, routing rationale
- Epistemic contract (basis type, chain status, missing variables)
- Audit result with validator flags
- Framework version embedded in every record

The routing rationale field distinguishes deterministic interpretation from model-generated output. A record showing `frontdoor:fcl:delegate_existing_command` proves the governance layer was operative for that turn. A record showing a pipeline frame proves the generative path was taken. This distinction is non-repudiable.

---

## Project Structure

```
src/eidolon/
├── middleware.py          # Primary integration surface — start here
├── types.py               # All domain types and enums
├── version.py             # Single source of truth for framework version
├── config.py              # Configuration loading
├── runtime/
│   ├── session.py         # SessionRuntime — full turn processing
│   ├── frontdoor.py       # RuntimeFrontDoorInterpreter — 9 concept families
│   ├── discourse.py       # DiscourseTracker — referent store with candidate scoring
│   └── cli.py             # Local interactive CLI
├── apdat/
│   ├── logger.py          # APDATLogger — provenance event builder and writer
│   ├── chain.py           # APDATChain — hash chain, RNG token, variable-length output
│   └── schema.py          # APDATEvent schema
├── kernel/
│   ├── state_machine.py   # RuntimeStateMachine
│   ├── policies.py        # PolicyEngine
│   ├── commands.py        # CommandRegistry
│   ├── handshake.py       # Handshake constants and validation
│   ├── persanity.py       # PersanityInspector — integrity check
│   └── risk.py            # RiskAssessor
├── orchestrator/
│   ├── pipeline.py        # EidolonPipeline — full generative turn pipeline
│   ├── framing.py         # Output frame mode selection
│   ├── adjudication.py    # Epistemic contract adjudication
│   ├── validators.py      # Audit validators
│   └── ...
├── memory/
│   ├── store.py           # FileMemoryStore
│   ├── sandbox.py         # MemorySandbox — sandboxed MEMNO inspection
│   ├── snapshots.py       # SnapshotStore
│   ├── diff.py            # MemoryDiffer — drift detection
│   └── ...
└── llm/
    ├── base.py            # LLMClient abstract base — implement this for your backend
    ├── lmstudio.py        # LM Studio adapter
    └── openai_compat.py   # OpenAI-compatible adapter
```

---

## Changelog

See [CHANGELOG.md](CHANGELOG.md) for full version history.

---

## License

Proprietary. All rights reserved. © Anthony C. Polk III.
Contact before use, integration, or distribution.
