Victor AI Framework — Documentation
Repository map and module owners · Completed and superseded work
Start here
Victor is a contract-first agent framework for tool use, compiled workflows and
multi-agent coordination across local and cloud providers.
Published baseline: Victor AI 0.12.0 (2026-10-04). Development line: post-release changes.
Version: 0.14.0 | License: Apache-2.0 | Python: 3.12+
Quick Start
pip install victor-ai
export ANTHROPIC_API_KEY=...
victor chat "Explain this codebase"
Architecture at a Glance
---
title: Victor system overview
---
%%{init: {"theme":"base","themeVariables":{"primaryColor":"#E8EFF7","primaryTextColor":"#17324D","primaryBorderColor":"#456987","lineColor":"#456987","fontFamily":"Arial"}}}%%
flowchart TB
subgraph C["Clients"]
CS["CLI · TUI · HTTP · MCP · VS Code"]
end
subgraph F["Framework · public API"]
VC["VictorClient<br/>application/session API"]
AG["Agent · AgentFactory<br/>agent lifecycle"]
WF["WorkflowEngine · StateGraph<br/>workflow authoring"]
end
subgraph R["Runtime · internal"]
OR["AgentOrchestrator<br/>composition facade"]
SV["Chat · tool · session services<br/>owned behavior"]
WR["Workflow runtime<br/>compiler · executor · CompiledGraph"]
end
subgraph I["Infrastructure"]
IN["providers · tools · storage · core"]
end
V["External vertical definitions"]
S["victor_contracts<br/>portable definitions"]
CS -->|"call"| VC
CS -->|"create or embed"| AG
CS -->|"submit workflows"| WF
VC -->|"delegate"| OR
AG -->|"construct and delegate"| OR
WF -->|"compile and execute"| WR
OR -->|"delegate behavior"| SV
SV -->|"use"| IN
WR -->|"use"| IN
V -->|"import only"| S
AG -.->|"consume contracts"| S
WF -.->|"consume contracts"| S
Start here → System Architecture for the full picture.
Delivery State
| Surface |
Published 0.12.0 |
Remaining work |
| Tool supply and teams |
Unified turn pipeline, expanded formations, isolation and usage guards |
Acceptance gaps remain tracked; release does not certify every live formation. |
| Chat ownership |
Service-owned turn frame and partial runtime inversion |
Retry ownership moves to a lifecycle capability; broader inversion remains open. |
| API / gateway |
Classify API, gateway policy, result withholding and Sandhi 0.10.1 accounting |
General client routing and retained safety gaps remain open. |
| Installation |
Node 24 minimum; Python 3.12/3.13 CI; optional NumPy and Linux binaries |
Later develop changes move Textual into the TUI extra; see the installation guide. |
Note
Pages deploys from main. Pull requests build a preview; the current develop
documentation publishes with the next main promotion.
Documentation Map
Core Documents (Start Here)
| Document |
Description |
| System Architecture |
Single source of truth — layers, services, providers, tools, state, extensions, diagrams |
| Features |
Complete feature catalog grounded in implementation |
| Roadmap |
Current release and Stage C priorities, complete debt register |
| Tech Stack |
Technology choices and dependency requirements |
Architecture Deep-Dives
User Guides
Developer Guides
API Reference
Configuration Reference
Verticals
| Document |
Description |
| Coding |
Code review, editing, test generation |
| DevOps |
Infrastructure, CI/CD, containers |
| RAG |
Retrieval, ingestion, search |
| Data Analysis |
Dataframes, statistics, visualization |
| Research |
Source research, synthesis |
| API Reference |
Vertical API reference |
Tutorials
Guides
Document Governance
| Priority |
Document |
Role |
| Canonical |
docs/architecture.md |
System architecture (single source of truth) |
| Canonical |
docs/features.md |
Feature catalog |
| Canonical |
docs/roadmap.md |
Roadmap and tech debt |
| Canonical |
docs/tech-stack.md |
Technology stack |
| Canonical |
VISION.md |
Product vision |
| Reference |
docs/diagrams/ |
Editable .mmd sources; canonical diagrams live inline in the master docs |
Contributing
See Development Setup and PR Workflow.
Contributions use conventional commits and the checks documented in the PR workflow.
Current work and historical evidence
The roadmap and Stage C reassessment
distinguish published 0.12.0 from subsequent changes and unfinished structural work.
The September co-design review preserves dated findings;
merged design documents do not imply their implementation has shipped. See the
documentation source index for canonical ownership and historical-record conventions.