ATTICUS MPO

ATTICUS is a governed desktop orchestrator for multi-provider AI workflows. It combines a Tkinter operator console with typed provider adapters, structured model catalogs, memory-cell prompt compilation, persistence, and guardrails for safe runtime control.

Current version: v5.0.0b6 — Framework: ATTICUS v6.4.1-HCII — Schema: v8

---

Features

• Multi-provider support: OpenAI, Anthropic, Gemini, and Ollama through polymorphic adapters
• Structured model catalogs with human-readable labels, generation buckets, capability metadata, and a live → cache → fallback resolution chain
• Provider participation control — operators enable or disable providers at runtime
• Memory-cell prompt compilation — 27 builtin cells, 7 packs (including ATTICUS governance/full packs)
• WorkerSession execution model — headless-capable session orchestration with typed turn handling
• Sampling safety envelope — resolver-based parameter enforcement
• Observability spine — ComponentInfo registry, IntrospectionService, debug snapshots, ambient trace context
• Environment diagnostics from Help → Environment… to verify interpreter, venv, pip, and packages
• Governed development process — four-layer multi-model orchestration pipeline with single-writer discipline

---

Install

python -m venv .venv
source .venv/bin/activate         # Linux/macOS
# .venv\Scripts\activate          # Windows PowerShell

pip install -e .
pip install -e '.[dev]'
pip install -e '.[secure]'

Python Compatibility

ATTICUS targets Python 3.11+ as its floor. The codebase, tooling, and type-checking all target py311. Newer Python releases are supported but not required; stable compatibility across provider SDKs (openai, anthropic, google-genai) takes priority over chasing the newest interpreter.

Update the Correct Environment

Use the project update scripts in the repository root (update_atticus_deps.ps1 / update_atticus_deps.bat). After updating, use Help → Environment… to confirm the active interpreter and package state.

---

Run

python main.py
# or, after install:
atticus

---

Provider Support

OpenAI

• Structured catalog with preferred, previous, and legacy buckets
• Preferred defaults favor current GPT-5 family models compatible with the current adapter path
• Some provider-valid models may be hidden or demoted if ATTICUS cannot use them reliably

Anthropic

• Structured catalog with preferred, previous, and legacy buckets
• Current preferred defaults center on Claude 4.6 / Haiku 4.5
• Modern Anthropic families use provider-side sampler guards where needed

Gemini

• Structured catalog with preferred, preview, and previous buckets
• Requires the official google-genai package in the active ATTICUS environment
• Preview entries are clearly labeled when exposed

Ollama

• Local-first inference through the Ollama provider adapter
• Speaker labels, TTS helpers, bridge rotation, and plugin input all include Speaker.OLLAMA

---

How Model Selection Works

For each provider, ATTICUS resolves models using: live discovery → cached catalog → hardcoded fallback.

ATTICUS stores the real provider model ID internally and shows human-readable display names in the UI. A model being valid at the provider does not automatically make it an ATTICUS default — models may be hidden, demoted, or warned on if they are preview/experimental, legacy, incompatible with the current adapter path, or subject to parameter restrictions not yet generalized in the UI.

---

Provider Participation

Operators can enable or disable providers independently. Runtime loops only include providers that are both enabled by the operator and configured with usable credentials. If the selected starter provider is disabled, ATTICUS warns instead of silently rerouting.

---

Memory Cells and Packs

ATTICUS compiles provider prompts from typed memory cells plus operator-entered notes and the current objective. Use Preview prompts to inspect compiled prompt packets.

---

Security Posture

• API keys wrapped in SecretStr; denied-by-default for disk persistence unless keyring or explicit insecure plaintext mode is enabled
• No-secret-leakage policy across repr/str/logging/export surfaces
• Unsafe code execution off by default with dual gate (UI + env var)

Full details in SECURITY.md.

---

Known Limitations

• Some provider-valid models may be excluded from normal catalogs if the current adapter path does not support them cleanly
• Live desktop/provider verification still requires operator-run smoke testing with real keys
• Gemini requires google-genai in the active ATTICUS runtime environment
• 2 pre-existing test failures (non-blocking); 23 pre-existing MyPy errors (documented)
• Settings UI functional but needs reorganization (tracked in ROADMAP.md)

Full details in KNOWN_ISSUES.md.

---

Development Process

ATTICUS uses a four-layer multi-model orchestration pipeline with strict role separation. See:

Document	Purpose
INDEX.md	Start here — master entry point, doc map, role table
DEV_LIFECYCLE.md	Engineering rules, gates, protected surfaces
ORCHESTRATION.md	Multi-model governance, packet schema, review pipeline
ROADMAP.md	Current status, backlog, deferred tracks
KNOWN_ISSUES.md	Open debt, test failures, verification gaps
ARCHITECTURE.md	Code structure, layers, runtime flow
DECISIONS.md	Historical decision log
WORK_LOG.md	Consolidated work history