eidolon-framework 0.4.1

EIDOLON behavioral control plane for language models

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:

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

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:

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).

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 for full version history.

---

License

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