Vitruvian 0.1.2

Vitruvian — .NET GOAP Agent Runtime

.NET GOAP agent runtime that decomposes user requests into dependency-aware execution plans, runs independent steps in parallel, and enforces human-in-the-loop approval, caching, and memory — all before any side-effecting action fires.

Vitruvian Agent Runtime — modular, GOAP-driven AI agent orchestration for .NET.

Third-party modules plug in via a single interface (IVitruvianModule). The host handles planning, routing, governance, and security so module authors focus only on capability logic.

Quick Start

Prerequisites

• .NET 8 SDK (8.0.100 or later)
• Git
• An API key for OpenAI, Anthropic, or Google Gemini

Clone, build, and test

git clone https://github.com/mrrasmussendk/Vitruvian.git
cd Vitruvian
dotnet build Vitruvian.sln
dotnet test Vitruvian.sln

Configure a model provider

Create a .env.Vitruvian file in the project root (loaded automatically at startup):

VITRUVIAN_MODEL_PROVIDER=OpenAI
VITRUVIAN_OPENAI_API_KEY=sk-...

Or use the guided installer — see docs/INSTALL.md for all options.

Run the CLI

dotnet run --project src/Vitruvian.Cli

Vitruvian CLI started. Type a request (or 'quit' to exit):
>

Try some requests:

> What is the weather tomorrow?
> Create a file called notes.txt with content "Hello World"
> Read notes.txt then summarize it

Features

Architecture

Every user request passes through three phases:

  User Request
       │
       ▼
  ┌──────────┐
  │   PLAN   │  GoapPlanner builds an ExecutionPlan
  └────┬─────┘  (PlanSteps + dependency edges)
       │
       ▼
  ┌──────────┐  PlanExecutor runs steps in waves:
  │ EXECUTE  │  • Cache check → HITL gate → Context injection
  │          │  • Module.ExecuteAsync → Cache store
  └────┬─────┘  Independent steps run in parallel
       │
       ▼
  ┌──────────┐
  │  MEMORY  │  Store plan result + conversation turn
  └────┬─────┘
       │
       ▼
    Response

The two core abstractions:

• IVitruvianModule — every capability (built-in or third-party) implements this single interface.
• GoapPlanner — takes a request and the list of registered modules, produces an ExecutionPlan with PlanStep nodes and DependsOn edges.

For a deeper dive see docs/ARCHITECTURE.md.

Building a Module

Create a net8.0 class library, reference Vitruvian.Abstractions, and implement IVitruvianModule:

using VitruvianAbstractions.Interfaces;

public sealed class TranslationModule : IVitruvianModule
{
    private readonly IModelClient? _modelClient;

    public string Domain => "translation";
    public string Description => "Translate text between languages using AI";

    public TranslationModule(IModelClient? modelClient = null)
        => _modelClient = modelClient;

    public async Task<string> ExecuteAsync(string request, string? userId, CancellationToken ct)
    {
        if (_modelClient is null) return "No model configured for translation.";
        return await _modelClient.GenerateAsync(
            $"Translate the following as requested: {request}", ct);
    }
}

Register via DI or drop the compiled DLL into plugins/. See docs/EXTENDING.md for the complete guide including SDK attributes, permissions, and API key declarations.

Documentation

All detailed documentation lives in the docs/ folder:

Repository Layout

Vitruvian.sln
├── src/
│   ├── Vitruvian.Abstractions/      ← Core interfaces, enums, facts, planning types
│   ├── Vitruvian.Runtime/           ← GoapPlanner, PlanExecutor, ModuleRouter,
│   │                                   PermissionChecker, CompoundRequestOrchestrator
│   ├── Vitruvian.PluginSdk/         ← SDK attributes for module metadata
│   ├── Vitruvian.PluginHost/        ← Plugin loader (AssemblyLoadContext), sandboxing
│   ├── Vitruvian.Hitl/              ← ConsoleApprovalGate, HITL facts
│   ├── Vitruvian.StandardModules/   ← Built-in modules (File, Conversation, Web, …)
│   ├── Vitruvian.WeatherModule/     ← Example standalone module
│   └── Vitruvian.Cli/               ← CLI entry point, RequestProcessor, ModelClientFactory
├── tests/
│   └── Vitruvian.Tests/             ← xUnit tests
├── docs/                            ← Detailed documentation (see table above)
└── scripts/                         ← Guided setup scripts (install.sh / install.ps1)

Configuration

Create a .env.Vitruvian file in the project root, or export environment variables before running:

See docs/INSTALL.md for the full variable reference and profile-based setup.

Contributing

Contributions welcome! See docs/CONTRIBUTING.md for details.

1. Fork the repository
2. Create a feature branch
3. Make your changes following the existing patterns
4. Write or update tests (target: all tests green)
5. Submit a pull request

License

See LICENSE file for details.

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions