Victor gives you a typed Python framework, a service-first agent runtime, and a contract-first plugin ecosystem for building agents that can reason, call tools, run workflows, coordinate teams, and operate against project-local code intelligence.

It is designed for teams that need agent systems to be testable, extensible, observable, and portable across Anthropic, OpenAI-compatible providers, Gemini, Bedrock, local models, and air-gapped environments.

Why Victor

Quick Start

Give Your Agent Durable Memory

Victor supports ProximaDB as an optional backend for durable code memory. Index any repository with the shared victor-codegraph chunker and get semantic recall ("where do we validate JWTs?") plus call-graph queries ("who calls parse_jwt?") that persist across sessions:

Quickstart: Durable Code Memory with ProximaDB — setup, indexing, semantic recall and graph queries.

Victor's embedded ProximaDB backends for project code intelligence are experimental, flag-gated previews — SQLite/LanceDB remain the defaults. The correlated graph+vector code-context backend (one entity = row + graph node + vector, TD-11/12/13) has implemented opt-in correlation and routing; benchmark, service-mode and default-graduation work remains — see the roadmap and ProximaDB as the CCG Backend.

Python API

import asyncio

from victor.framework import Agent, EventType, ToolSet


async def main():
    async with await Agent.create(
        provider="anthropic",
        tools=ToolSet.default(),
    ) as agent:
        result = await agent.run("Explain the architecture of this codebase")
        print(result.content)

        async for event in agent.stream("Review the changed files"):
            if event.type == EventType.CONTENT:
                print(event.content, end="", flush=True)


asyncio.run(main())

StateGraph Workflows

import asyncio
from typing import TypedDict

from victor.framework import END, StateGraph


class ReviewState(TypedDict):
    query: str
    findings: list[str]


async def inspect(state: ReviewState) -> ReviewState:
    return {**state, "findings": ["example finding"]}


graph = StateGraph(ReviewState)
graph.add_node("inspect", inspect)
graph.add_edge("inspect", END)
graph.set_entry_point("inspect")

result = asyncio.run(
    graph.compile().invoke({"query": "review this module", "findings": []})
)
print(result.state["findings"])

Architecture

Each box below owns a different concern. Items inside one box are complementary entry points or services, not competing implementations.

---
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 implementation"]
    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

The canonical architecture guide explains the boundaries and execution paths. Workflow execution and streaming share CompiledGraph; the former BFS walker has been removed. The unified streaming chat loop is implemented. ChatService now owns the turn frame and the streaming cluster consumes typed planning and execution-control capabilities. Broader runtime-state inversion, expanded interrupt/resume semantics and RL relocation remain proposal targets.

The framework/plugin split is:

• victor.framework is the stable public contract for agents, tools, StateGraph, workflows, events, and extension surfaces.
• victor.agent is the internal runtime implementation behind that contract.
• victor.agent.services owns effectful runtime behavior through ChatService, ToolService, SessionService, ContextService, ProviderService, and RecoveryService.
• victor-contracts is the definition-layer contract for external verticals and plugins.
• Sibling victor-* packages own domain behavior such as coding, DevOps, RAG, research, data analysis, and investment workflows.

Read the published documentation for navigation and searchable API references.

Detailed references:

• Architecture overview
• Diagram map and refresh audit
• contracts boundary
• State-passed architecture

Plugin Ecosystem

External and first-party domain packages should use victor-contracts and public framework extension contracts. The root framework stays generic; domain-specific behavior belongs in plugins and vertical packages.

Plugin rules:

• Use the victor.plugins entry point as the canonical discovery seam.
• Register capabilities through VictorPlugin.register(context).
• Import from victor_contracts, victor.framework.extensions, or documented public APIs.
• Do not import victor.agent.* or private root runtime internals from external packages.

Use Cases

• Build local or cloud-backed coding agents that can inspect files, search graphs, run tests, and produce review findings.
• Compose workflow agents with typed StateGraph nodes, deterministic handoffs, and resumable execution.
• Run tool-using assistants through CLI, TUI, HTTP API, MCP, or embedded Python.
• Build domain plugins without copying framework internals into vertical packages.
• Keep project code intelligence local while preserving global preferences, learning, and provider settings separately.

State and Code Intelligence

Victor separates global and project state, with a dedicated database for undo history:

Project code intelligence is derived, rebuildable state. Graph indexes, vector indexes, file watcher state, and .victor/ runtime artifacts should not become source-of-truth release artifacts.

Development

Follow Development Setup for the environment, optional extras, native extension build, and documentation preview. The PR workflow defines verification and branch conventions. Use dependency maintenance to choose deployment extras, refresh resolved requirements, and build the core, MCP, native or full container target.

Documentation

• Documentation map
• Canonical guide index
• Getting Started
• Durable Code Memory with ProximaDB
• Guides
• Reference
• Development
• Architecture
• Roadmap

Contributing

Start with CONTRIBUTING.md and the architecture overview; see the development docs for setup, code style, and the PR workflow. Keep changes scoped, prefer public framework/SDK contracts over internal imports, and update docs/tests when public behavior changes.

License

Apache License 2.0. See LICENSE.