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

The core rule is simple: interfaces compose framework APIs, framework APIs delegate to the service-first runtime, and domain packages plug in through SDK/public extension contracts.

---
title: Victor system overview
---
%%{init: {"theme":"base","themeVariables":{"primaryColor":"#E8EFF7","primaryTextColor":"#17324D","primaryBorderColor":"#456987","lineColor":"#456987","fontFamily":"Arial"}}}%%
flowchart TB
  C["Clients<br/>CLI · TUI · HTTP · MCP · VS Code"]
  F["Framework<br/>VictorClient · AgentFactory<br/>Agent · WorkflowEngine · StateGraph"]
  R["Runtime<br/>AgentOrchestrator facade<br/>chat, tool and session services"]
  I["Infrastructure<br/>providers · tools · storage · core"]
  V["External vertical definitions"]
  S["victor_contracts"]
  C -->|"call public APIs"| F
  F -->|"construct and delegate"| R
  R -->|"perform effectful operations"| I
  V -->|"declare capabilities"| S
  F -.->|"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. Further chat ownership inversion, expanded interrupt/resume semantics and RL package relocation remain explicitly labelled 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.