CanDoItAll.AgentFramework.SemanticCompletion.Driver 0.1.18

CanDoItAll Agent Framework Semantic Completion — Driver

Provider-independent semantic text ranking and guarded agent-completion classification for .NET 10.

This package contains no ONNX Runtime or remote inference dependency. It includes a deterministic local hashing provider so the supported APIs work without model downloads or native binaries.

Install

dotnet add package CanDoItAll.AgentFramework.SemanticCompletion.Driver

Agent-completion API

Register the default singleton driver:

using CanDoItAll.AgentFramework.SemanticCompletion.Driver;
using CanDoItAll.AgentFramework.SemanticCompletion.Driver.DependencyInjection;
using Microsoft.Extensions.DependencyInjection;

services.AddAgentSemanticCompletionDriver();

var driver = serviceProvider.GetRequiredService<IAgentSemanticCompletionDriver>();
var result = await driver.ClassifyAsync(
    new AgentSemanticCompletionRequest("The requested work is complete."));

AgentSemanticCompletionStatus can be Completed, Failed, Blocked, NeedsHumanInput, InProgress, Refused, or Unknown. AgentSemanticCompletionDecision is Accepted, WeakMatch, or Rejected. Inspect the score, margin, matched intent and phrase, alternative matches, and guard hits rather than treating the status alone as an authorization signal.

Classification precedence is conservative:

1. ordered hard-negative and completion guard rules;
2. a valid, explicitly supported named status in a JSON object;
3. generic semantic ranking with intent thresholds and minimum margin.

Guard rules therefore override contradictory structured text. Malformed JSON, numeric statuses, Unknown, and undefined status names are not accepted as structured classifications.

Generic semantic API

The Semantics namespace supports any enum-backed label catalog:

using CanDoItAll.AgentFramework.SemanticCompletion.Driver.Embeddings;
using CanDoItAll.AgentFramework.SemanticCompletion.Driver.Semantics;

var catalog = new SemanticIntentRegistry<MyIntent>
{
    DefaultAcceptThreshold = 0.75f,
    DefaultWeakThreshold = 0.60f,
    DefaultMinimumMargin = 0.04f,
    Intents =
    [
        new SemanticIntent<MyIntent>
        {
            IntentKey = "approval",
            Label = MyIntent.Approval,
            CanonicalPhrases = ["approval required", "waiting for approval"],
            PositiveTerms = ["approval", "confirm"],
        },
    ],
};

var classifier = await SemanticClassifier<MyIntent>.CreateAsync(
    catalog,
    new LocalHashingAgentTextEmbeddingGenerator());
var result = await classifier.ClassifyAsync(
    new SemanticClassificationRequest("approval required"));

Registry DTOs are copied into a compiled catalog during construction. Later mutation of the caller-owned lists does not change a constructed classifier.

Embedding providers and profiles

The default local hashing provider is deterministic and dependency-light; it is a baseline and fallback, not a claim of general language understanding. For local neural embeddings, install CanDoItAll.AgentFramework.SemanticCompletion.Onnx.

Register a custom provider before the driver extension; default registration uses TryAdd and preserves the consumer service:

services.AddSingleton<IAgentTextEmbeddingGenerator, MyEmbeddingGenerator>();
services.AddAgentSemanticCompletionDriver();

The same pattern applies to IAgentSemanticCompletionGuardDetector. Custom embedding generators must be safe for concurrent calls. All candidate and query embeddings in one compiled ranker must have the same profile ID and dimension; a mismatch fails with a clear exception. Similarity always uses bounded full cosine, regardless of the profile's IsNormalized value.

Lifetime and concurrency

The DI extension registers an internal asynchronous-lazy singleton. Resolving IAgentSemanticCompletionDriver performs no embedding work. The first ClassifyAsync builds one classifier, and concurrent first callers await the same initialization task. After initialization, concurrent classifications can invoke the registered embedding provider concurrently.

The Driver does not take ownership of manually constructed providers. Follow normal Microsoft.Extensions.DependencyInjection ownership rules: the container disposes disposable services it creates; callers dispose instances they construct and own. The built-in local hashing provider holds no native session.

Safety boundary

Semantic classification is fallback evidence, telemetry, or a recovery aid. It is not authoritative proof that an agent completed work and must not replace a typed finalizer/DTO, execution evidence, authorization, tenant policy, or human approval. Treat weak/rejected results and profile failures as Unknown/manual-review signals.

Project links

• Repository
• Architecture and publishing boundaries
• License
• Support and issues
• Security policy
• CanDoItAll