ELCIA System

ELCIA System stands for External Local Core Integration Agent System. This repository is a research-heavy agent runtime that combines:

• goal-direction auditing (D_cos, D_info, D_total)
• runtime recovery and planning
• world/self model updates
• long-horizon evaluation
• formal verification with Lean
• autonomous research loops

The repository is broad. Start with the guided documents below instead of reading dated memos first.

What ELCIA Is For

ELCIA is an agent runtime built to stay honest about its own state — designed for researchers and developers who need an agent that does not silently drift, collapse, or succeed-on-paper while failing in practice.

Concretely, it exists to do three things:

1. Run real tasks autonomously — execute experiments, commit results, write files, and report what actually happened, using a ReAct-style tool loop (run_until_done).
2. Quantify each turn — every response is scored on goal alignment, directional distance (D_total), structural integrity (Omega/S), and temporal consistency, with Lean-backed proofs covering the monotonicity conditions that make those scores meaningful.
3. Not fool itself — the architecture is designed so that the loop cannot exit by claiming success; it requires measurable side effects and consecutive stable scores, not just an LLM saying "done".

If you want an agent you can point at a research task and trust the output log, this is the runtime for that. The formal verification surface (proofs/lean/) and the empirical validation layer (research/experiments/) exist to make that trust legible rather than assumed.

Read This First

If you only read three files, read these first:

1. Getting Started
2. Documentation Index
3. API Reference

The root README is only a portal. The canonical documentation surface lives under docs/. Current package surface version: 0.2.0.

Start Here

• Getting Started
• Environment Setup
• API Reference
• Project Paper Status
• Contributing
• Governance
• Roadmap And Milestones
• Documentation Index
• Testing And CI
• Repo Structure

Choose Your Lane

• New user: Getting Started
• Environment and test setup: Environment Setup, Testing And CI
• Runtime and core code surface: Repo Structure, API Reference
• Theory and proof maturity: Documentation Index, Theory Maturity And Formal Gap
• Project direction and contribution: Contributing, Roadmap And Milestones
• Governance and release policy: Governance
• Paper track: Project Paper Status

What Is Stable

The most stable surfaces for new contributors are:

• core/
• engine/
• utils/
• tools/
• tests/
• proofs/

Research artifacts and generated outputs also exist under research/, but not all of them are intended as first-entry documents.

Quick Start

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements-dev.txt
make test
make smoke-turn

This is the standard CLI / headless path and does not require macOS desktop bindings.

Optional macOS desktop UI:

python -m pip install -r requirements-macos-desktop.txt
make install-desktop-macos

requirements-dev.txt is a compatibility shim. The canonical dev dependency list lives in pyproject.toml.

If you only want the standard local regression path, make test is the default entrypoint.

Current Verification Highlights

• CI path exists through .github/workflows/ci.yml
• coverage output is generated by make coverage
• latest retained baseline coverage is 80.85% line / 68.84% branch: coverage_summary_latest.md
• Lean proof targets build through proofs/lean/lakefile.lean
• retained external and long-horizon experiment artifacts live under research/experiments/results/

Project Status

• Proof maturity and formal gaps: THEORY_MATURITY_AND_FORMAL_GAP_2026-04-03.md
• Autonomy vs safety gate classes: AUTONOMY_SAFETY_GATING_2026-04-03.md
• Current paper track status: PROJECT_PAPER_STATUS.md

External Read-Only Loop

The repository now includes a read-only external API loop for:

• GitHub repository metadata
• GitHub repository contents
• Crossref works search
• arXiv search

See:

• external_read_only_task_set_v1.json
• external_api_long_horizon_suite_v1.json

Where To Go Next

• For first setup: Getting Started
• For environment variants: Environment Setup
• For callable surfaces and signatures: API Reference
• For external contributors: Contributing
• For project direction: Roadmap And Milestones
• For current paper state: Project Paper Status
• For running tests and coverage: Testing And CI
• For proof and metric docs: Documentation Index
• For day-to-day repository boundaries: Repo Structure