Crucible.Flow 0.0.0-alpha.0.1

Crucible

A clean, multi-package .NET 10 RC1 solution with opinionated extensions for DI/hosting and EF Core.

AI Capabilities

Crucible.AI provides production-ready AI capabilities with tenant-aware features:

Text Generation

• OpenAI Integration: Full OpenAI API support with streaming
• Cost Tracking: Automatic token counting and cost calculation
• Rate Limiting: Per-tenant rate limiting with PartitionedRateLimiter
• Caching: Tenant-prefixed cache keys for response caching
• Usage Metering: Background usage tracking and persistence

FinBERT Sentiment Analysis

• Real ONNX Model: Production FinBERT model (418MB) for financial sentiment
• Tenant-Aware: All sentiment analysis respects tenant boundaries
• Usage Tracking: Token counting and cost tracking
• Error Handling: Graceful fallbacks and proper error responses

Note: FinBERT is trained on financial news and may classify sentiment differently than general sentiment models. This is expected behavior for domain-specific financial sentiment analysis.

Sample Endpoints

• POST /ai/generate - Text generation with OpenAI
• POST /ai/sentiment - Financial sentiment analysis with FinBERT

Packages

• Crucible.Abstractions - Core abstractions and options
• Crucible.Hosting - Opinionated hosting extensions
• Crucible.EF - Entity Framework Core extensions
• Crucible.Flow - Type-safe pipeline composition engine

Flow in 15 seconds

Crucible.Flow provides a type-safe, composable pipeline engine for building complex workflows:

var flow = FlowBuilder<Input, Input>.New("calc", sp)
  .Validate(x => x.Items.Count > 0, "Items required")
  .ThenParallel<Input, Input, int, int, Output>(
    name: "square+sum",
    items: input.Items,
    perItemFactory: () => new Step<(Input,int), int>("square", (ct, t) => Task.FromResult(t.Item2 * t.Item2)),
    reduce: (ctx, squares) => new Output { Sum = squares.Sum(), Count = squares.Count });

var result = await flow.RunAsync(input, ct);

Key Features

• Type Safety: FlowBuilder<TIn, TOut> carries both input and output types
• Parallel Processing: ThenParallel for concurrent execution with optional ordering
• Error Handling: Catch and CatchDefault for graceful error recovery
• Functional Composition: Map, Tap, and Validate for clean pipelines
• Retry Policies: Configurable retry with exponential backoff and jitter
• Telemetry: IFlowTelemetry interface for observability

Parallel Processing

// Order-independent (faster)
.ThenParallel(name: "process-items", items: items, perItemFactory: ..., reduce: ...)

// Order-preserved (deterministic)
.ThenParallelOrdered(name: "process-items", items: items, perItemFactory: ..., reduce: ...)

Error Handling

var flow = FlowBuilder<int, int>.New("robust", sp)
  .Then("risky-step", async (ct, x) => { /* might fail */ })
  .CatchDefault("fallback", -1); // Return -1 on any error

Quick Start

1. Setup: Run ./setup.sh to scaffold the solution
2. Build: dotnet build
3. Run: dotnet run --project samples/Crucible.SampleApi
4. Test: curl -X POST http://localhost:50001/flow/test -H "Content-Type: application/json" -d '{"numbers": [1,2,3,4,5]}'

Sample API

The sample API demonstrates:

• Flow composition with type transitions
• Parallel processing with validation
• Proper HTTP error mapping (400 for validation, 500 for unexpected errors)
• Retry policies and telemetry
• Ambient tenant resolution (no tenant IDs in routes!)
• Tenant-aware EF Core with automatic filtering and stamping

Endpoints:

• GET / - Hello world
• POST /flow/test - Flow processing demo
• GET /tenant/info - Current tenant context
• GET /admin/stats - Admin-only endpoint (requires "admin" role)
• GET /features/premium - Tenant feature flags demo
• GET /config/service - Tenant-scoped configuration demo
• POST /widgets - Create tenant-stamped widget
• GET /widgets - List widgets (tenant-filtered)
• GET /healthz - Health check

Tenant-Aware Features

Crucible provides ambient tenancy - tenant isolation without route parameters:

// Tenant resolution from auth token (transparent)
app.UseCrucibleTenancy();

// EF Core automatically filters by tenant
app.MapGet("/widgets", async (SampleDbContext db) =>
{
    var widgets = await db.Widgets.ToListAsync(); // Only current tenant's widgets
    return Results.Json(widgets);
});

// Automatic tenant stamping on save
app.MapPost("/widgets", async (SampleDbContext db, CreateWidgetRequest request) =>
{
    var widget = new Widget { Name = request.Name };
    db.Widgets.Add(widget);
    await db.SaveChangesAsync(); // Automatically stamped with current tenant
    return Results.Json(widget);
});

Key Benefits:

• No tenant IDs in routes - security through ambient context
• Automatic EF filtering - global query filters prevent cross-tenant data leaks
• Automatic tenant stamping - SaveChanges stamps all ITenantStamped entities
• Tenant-scoped options - configuration per tenant via ITenantOptionsProvider
• Background work support - TenantScopeFactory for jobs without HttpContext

Tenant Authorization & Security

// Role-based authorization
app.MapGet("/admin/stats", async (ITenantAuthorizer authorizer) =>
{
    await authorizer.DemandRoleAsync("admin");
    return Results.Json(new { message = "Admin stats for current tenant" });
});

// Custom authorization predicates
await authorizer.Demand(ctx => ctx.Roles.Contains("premium"), "Premium subscription required");

// Check roles without throwing
var isAdmin = await authorizer.HasRoleAsync("admin");

Tenant Feature Flags & Configuration

// Feature flags per tenant
app.MapGet("/features/premium", async (ITenantFeatureFlags flags) =>
{
    var isEnabled = await flags.IsEnabledAsync("premium-features");
    return Results.Json(new { premiumEnabled = isEnabled });
});

// Tenant-scoped configuration
app.MapGet("/config/service", async (ITenantOptionsMonitor monitor) =>
{
    var config = await monitor.GetAsync<ServiceConfig>();
    return Results.Json(config);
});

Cache Partitioning

// Automatic tenant-prefixed cache keys
services.AddSingleton<IDistributedCache, TenantDistributedCache>();

// Or use ITenantCacheKeys directly
var cacheKey = cacheKeys.Key("user-profile", userId); // "tenant-123:user-profile:456"

Outbound Service Calls

// Automatic tenant propagation via HttpClient
services.AddHttpClient("downstream")
    .AddHttpMessageHandler<TenantPropagationHandler>();

// Headers automatically added: x-tenant-id, Authorization (if available)

Flow Integration

// Ensure tenant context in flows
var flow = FlowBuilder<Input, Output>.New("tenant-aware", sp)
    .RequireTenant() // Throws if no tenant context
    .Then("process", async (ct, input) => { /* tenant context guaranteed */ });

Testing Support

// Create tenant-scoped test contexts
using var scope = serviceProvider.AsTenant("test-tenant", "user", "admin");
var service = scope.ServiceProvider.GetRequiredService<IMyService>();
// Service sees tenant context automatically