Victor AI Framework — Documentation¶

Contract-first, service-first agentic AI framework for building agents that reason,
call tools, execute DAG workflows, and coordinate multi-agent teams across 24 LLM providers.

Version: 0.9.0 | License: Apache-2.0 | Python: 3.11+

Quick Start¶

pip install victor-ai
export ANTHROPIC_API_KEY=...
victor chat "Explain this codebase"

Architecture at a Glance¶

flowchart TB
    subgraph Clients["CLIENT LAYER"]
        CLI["CLI / TUI"]
        API["HTTP API"]
        MCP["MCP Server"]
        VSC["VS Code"]
    end
    subgraph Framework["FRAMEWORK LAYER"]
        Agent["Agent API"]
        SG["StateGraph"]
        WE["WorkflowEngine"]
        Tools["Tool Registry"]
    end
    subgraph Services["SERVICE LAYER (6 canonical)"]
        CS["ChatService"]
        TS["ToolService"]
        SS["SessionService"]
        CX["ContextService"]
        PS["ProviderService"]
        RS["RecoveryService"]
    end
    subgraph Runtime["RUNTIME"]
        ORC["AgentOrchestrator (Facade)"]
        AL["AgenticLoop"]
        TP["ToolPipeline"]
    end
    subgraph Providers["PROVIDERS (24)"]
        Prov["Anthropic, OpenAI, Gemini, Ollama, Bedrock + 19"]
    end
    subgraph ToolModules["TOOLS (34 modules)"]
        T1["Filesystem, Git, Shell, Web, Docker, Verification"]
    end
    subgraph Storage["STORAGE"]
        GDB["Global DB ~/.victor/victor.db"]
        PDB["Project DB ./.victor/project.db"]
    end
    Clients --> Framework --> Runtime --> Services
    Services --> Providers
    Services --> ToolModules
    Runtime --> Storage

Start here → System Architecture for the full picture.

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	90-day priorities, directional horizons, tech debt register
Tech Stack	Technology choices, dependency map, technical debt

Architecture Deep-Dives¶

Document	Description
Orchestrator Decomposition	Facade pattern, 6 services, 23 coordinators, 10 boundary modules
SDK Boundary	Plugin/vertical/extension contracts and import rules
State-Passed Architecture	Coordinator patterns, ContextSnapshot, CoordinatorResult
Streaming Pipeline	Streaming execution pipeline design
Smart Routing	Provider routing and selection
Edge Provider Strategy	Edge model decisions
ADR Index	Architecture Decision Records

User Guides¶

Document	Description
CLI Reference	All `victor` CLI commands and flags
Workflows	StateGraph and YAML workflow DSL
Providers	Provider configuration and switching
Tools	Built-in tool modules and usage
Session Management	Sessions, context, state scopes
Troubleshooting	Common issues and solutions

Developer Guides¶

Document	Description
Development Setup	Install, venv, pre-commit, editor config
Testing Strategy	Unit/integration/benchmark, autouse fixtures
Code Style	Black, ruff, mypy, line length 100
Service Guide	Service layer development patterns
Deprecation Policy	How deprecations are managed
PR Workflow	Branch hygiene, commit conventions, review process
FEP Process	Framework Enhancement Proposal workflow
Plugin Development	Creating Victor plugins
Vertical Development	Building domain verticals

API Reference¶

Document	Description
Providers API	Provider adapter interface
Tools API	Tool registration and execution
Workflows API	Workflow compiler and executor
Protocols	Core protocols and interfaces

Configuration Reference¶

Document	Description
Settings Reference	All 26+ config groups
Configuration Options	Detailed config options
Environment Variables	All env vars
Provider Comparison	Feature matrix for 24 providers
CLI Commands	CLI command reference
Skills	Skill registry and YAML definitions
Embeddings	Embedding backends and configuration

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¶

Document	Description
Build Custom Tool	Step-by-step tool creation
Create Workflow	Workflow DSL tutorial
Integrate Provider	Provider adapter tutorial

Guides¶

Document	Description
Observability	Monitoring and tracing
MCP Server	Using Victor as MCP server
Task Completion	Task fulfillment detection
Workflows	Workflow scheduler guide

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.
All contributions require conventional commits and pass make lint && make test.