Package Ecosystem

Strategos is distributed as multiple NuGet packages, allowing you to include only what you need.

Package Overview

Package	Purpose	Required
Strategos	Core fluent DSL, abstractions, and type definitions	Yes
Strategos.Generators	Roslyn source generators for compile-time code generation	Yes
Strategos.Infrastructure	Production implementations (Thompson Sampling, loop detection, budgets)	Recommended
Strategos.Agents	Microsoft.Extensions.AI integration for LLM-powered steps	For AI workflows
Strategos.Rag	Vector store adapters for RAG patterns	For RAG workflows

---

Strategos

The core package containing the fluent DSL for defining workflows and all foundational abstractions.

Key Types

Type	Purpose
Workflow<TState>	Entry point for fluent workflow definitions
IWorkflowStep<TState>	Interface for implementing workflow steps
IWorkflowDefinition<TState>	Interface for workflow definition classes
StepResult<TState>	Result type returned from step execution
StepContext	Execution context passed to steps (correlation ID, timestamp, metadata)

Thompson Sampling Types

Type	Purpose
AgentBelief	Beta(alpha, beta) distribution representing agent performance belief
TaskCategory	Enumeration of task categories (Analysis, Coding, Research, etc.)
TaskFeatures	Extracted features from task descriptions
IAgentSelector	Interface for agent selection strategies
IBeliefStore	Interface for persisting agent beliefs

State Attributes

Attribute	Purpose
[Append]	Merge lists by appending new items to existing
[Merge]	Merge dictionaries, new values overwrite existing keys
[WorkflowState]	Marks a record as workflow state (enables source generation)

Installation

dotnet add package LevelUp.Strategos

---

Strategos.Generators

Roslyn source generators that transform fluent DSL definitions into type-safe artifacts at compile time.

Generated Artifacts

Artifact	Description
Phase Enum	Type-safe enumeration of workflow phases
Commands	Wolverine message types for step transitions
Events	Marten event types for audit trail
Saga Class	Complete Wolverine saga with handlers
State Reducers	Property merge logic based on [Append]/[Merge] attributes
DI Extensions	Service registration helpers

Compiler Diagnostics

The generator reports errors and warnings at compile time. See Diagnostics Reference for the complete list.

Code	Severity	Description
AGWF001	Error	Workflow name cannot be empty
AGWF002	Warning	No steps found in workflow
AGWF003	Error	Duplicate step name (use instance names)
AGWF009	Error	Workflow must begin with StartWith<T>()
AGWF010	Warning	Workflow should end with Finally<T>()
AGWF012	Error	Every Fork must be followed by Join<T>()

Installation

dotnet add package LevelUp.Strategos.Generators

Development Dependency

This is a compile-time dependency. It runs during build and produces no runtime overhead.

---

Strategos.Infrastructure

Production-ready implementations of core abstractions including Thompson Sampling, loop detection, and budget enforcement.

Thompson Sampling

Type	Purpose
ContextualAgentSelector	Selects agents using Thompson Sampling with contextual bandits
InMemoryBeliefStore	In-memory persistence for agent beliefs (dev/testing)
KeywordTaskFeatureExtractor	Extracts task features for category classification

Loop Detection

Detects stuck workflows using four strategies:

Detector	Description
ExactRepetitionDetector	Identical action sequences
SemanticRepetitionDetector	Similar outputs (cosine similarity > threshold)
OscillationDetector	A-B-A-B patterns
NoProgressDetector	Activity without state change

Budget Guard

Type	Purpose
BudgetGuard	Enforces resource limits (steps, tokens, wall time)
ScarcityLevel	Abundant, Normal, Scarce, Critical
BudgetOptions	Configuration for budget thresholds

Installation

dotnet add package LevelUp.Strategos.Infrastructure

Usage

services.AddStrategos()
    .AddThompsonSampling(options => options
        .WithPrior(alpha: 2, beta: 2))
    .AddLoopDetection()
    .AddBudgetGuard(options => options
        .WithMaxSteps(100)
        .WithMaxTokens(50_000));

---

Strategos.Agents

Integration with Microsoft.Extensions.AI for LLM-powered workflow steps.

Key Types

Type	Purpose
IAgentStep<TState>	Base interface for LLM-powered steps
AgentStepContext	Extended context with conversation thread access
IConversationalState	Interface for state that includes conversation history
IStreamingCallback	Callback for real-time token streaming

Dependencies

• Microsoft.Extensions.AI (10.0.1)
• Microsoft.Extensions.AI.Abstractions (10.0.1)

Installation

dotnet add package LevelUp.Strategos.Agents

Usage

public class AnalyzeDocumentStep : IAgentStep<DocumentState>
{
    private readonly IChatClient _chatClient;

    public AnalyzeDocumentStep(IChatClient chatClient)
    {
        _chatClient = chatClient;
    }

    public async Task<StepResult<DocumentState>> ExecuteAsync(
        DocumentState state,
        AgentStepContext context,
        CancellationToken ct)
    {
        var response = await _chatClient.GetResponseAsync(
            $"Analyze this document: {state.Content}",
            ct);

        return state
            .With(s => s.Analysis, response)
            .AsResult();
    }
}

---

Strategos.Rag

Vector store adapters for Retrieval-Augmented Generation (RAG) patterns.

Implemented Adapters

Adapter	Status	Use Case
InMemoryVectorSearchAdapter	Available	Development and testing

Planned Adapters

Adapter	Status	Use Case
PgVectorAdapter	Planned	PostgreSQL with pgvector extension
AzureAISearchAdapter	Planned	Azure AI Search

Key Interfaces

Type	Purpose
IVectorSearchAdapter	Interface for vector similarity search
SearchResult	Result containing content, score, and metadata

Installation

dotnet add package LevelUp.Strategos.Rag

Usage

public class RetrieveContextStep : IWorkflowStep<QueryState>
{
    private readonly IVectorSearchAdapter _vectorSearch;

    public async Task<StepResult<QueryState>> ExecuteAsync(
        QueryState state,
        StepContext context,
        CancellationToken ct)
    {
        var results = await _vectorSearch.SearchAsync(
            state.Query,
            topK: 10,
            minRelevance: 0.7);

        return state
            .With(s => s.RetrievedContext, results)
            .AsResult();
    }
}

---

Installation Scenarios

Minimal (Non-AI Workflows)

For workflows that don't involve LLM agents:

dotnet add package LevelUp.Strategos
dotnet add package LevelUp.Strategos.Generators

Standard (LLM-Powered Workflows)

Most common setup for AI agent workflows:

dotnet add package LevelUp.Strategos
dotnet add package LevelUp.Strategos.Generators
dotnet add package LevelUp.Strategos.Agents
dotnet add package LevelUp.Strategos.Infrastructure

Full (With RAG)

For workflows that include retrieval-augmented generation:

dotnet add package LevelUp.Strategos
dotnet add package LevelUp.Strategos.Generators
dotnet add package LevelUp.Strategos.Agents
dotnet add package LevelUp.Strategos.Infrastructure
dotnet add package LevelUp.Strategos.Rag

---

Package Dependencies

Strategos (core)
+-- No external dependencies

Strategos.Generators
+-- Microsoft.CodeAnalysis.CSharp
+-- [Compile-time only]

Strategos.Infrastructure
+-- Strategos
+-- Microsoft.Extensions.Caching.Memory
+-- Microsoft.Extensions.DependencyInjection.Abstractions

Strategos.Agents
+-- Strategos
+-- Microsoft.Extensions.AI
+-- Microsoft.Extensions.AI.Abstractions
+-- Microsoft.Extensions.DependencyInjection.Abstractions

Strategos.Rag
+-- Strategos.Agents