Formbase.Client 0.22.0

Formbase C# SDK

C# client library for Formbase — M3L-driven database engine with automatic ontology generation.

Installation

dotnet add package Formbase.Client

Quick Start

using Formbase.Client;

using var client = new FormbaseClient("http://localhost:8080", apiKey: "your-key");

// Apply M3L schema
var result = await client.Schemas.ApplyAsync(@"
# Namespace: store

## Product : Timestampable
- id: identifier @primary @generated
- name: string @required
- price: decimal @min(0)
");
Console.WriteLine($"Tables created: {result.Tables.Count}");

// Seed data
var seed = await client.Data.SeedAsync("Product", [
    new() { ["name"] = "Widget", ["price"] = 29.99 }
]);

// Generate ontology
var onto = await client.Ontology.GenerateAsync(m3l);
Console.WriteLine($"Concepts: {onto.Concepts}, Relations: {onto.Relations}");

// Search
var search = await client.Ontology.SearchAsync("product");
foreach (var hit in search.Hits)
    Console.WriteLine($"  {hit.ConceptName} (score: {hit.Score:F2})");

Dependency Injection

using Formbase.Client;

builder.Services.AddFormbaseClient(options =>
{
    options.BaseUrl = "http://localhost:8080";
    options.ApiKey = builder.Configuration["Formbase:ApiKey"];
    options.Timeout = TimeSpan.FromSeconds(60);
});

Then inject FormbaseClient into your services:

public class MyService(FormbaseClient formbase)
{
    public async Task DoWorkAsync()
    {
        var concepts = await formbase.Ontology.GetConceptsAsync(status: "auto");
    }
}

Error Handling

The SDK throws typed exceptions for different error conditions:

using Formbase.Client.Errors;

try
{
    await client.Schemas.ApplyAsync(invalidM3l);
}
catch (FormbaseValidationException ex)
{
    Console.WriteLine($"[{ex.Code}] {ex.ErrorMessage}: {ex.Detail}");
}
catch (FormbaseNotFoundException ex)
{
    Console.WriteLine($"Not found: {ex.ErrorMessage}");
}
catch (FormbaseServiceException ex)
{
    Console.WriteLine($"Server error ({ex.StatusCode}): {ex.ErrorMessage}");
}
catch (FormbaseRateLimitException)
{
    Console.WriteLine("Too many requests — retry later");
}
catch (FormbaseAuthenticationException)
{
    Console.WriteLine("Invalid API key");
}

Exception hierarchy:

API Reference

Schemas

// Apply M3L schema (creates/updates tables)
var result = await client.Schemas.ApplyAsync(m3l);
var diffResult = await client.Schemas.ApplyAsync(m3l, mode: "diff"); // Incremental

// Calculate diff without applying
var diff = await client.Schemas.DiffAsync(m3l);

// List tables
var tables = await client.Schemas.ListAsync();

Data

// Query with filtering and pagination
var page = await client.Data.QueryAsync("Product",
    filter: "price:gt:10",
    orderBy: "name asc",
    page: 1,
    pageSize: 50);

// Get by ID
var record = await client.Data.GetByIdAsync("Product", id);

// Seed records
var result = await client.Data.SeedAsync("Product", records);

Ontology

// Generate from M3L
var result = await client.Ontology.GenerateAsync(m3l);

// Browse concepts & relations
var concepts = await client.Ontology.GetConceptsAsync(status: "auto", minConfidence: 0.8);
var concept = await client.Ontology.GetConceptAsync("concept:Product");
var relations = await client.Ontology.GetRelationsAsync(conceptId: "concept:Product");
var graph = await client.Ontology.GetGraphAsync();
var summary = await client.Ontology.GetSummaryAsync();

// Search (keyword or natural language)
var results = await client.Ontology.SearchAsync("product", limit: 20);
var nlq = await client.Ontology.SearchAsync("what relates to Product?", mode: "natural");

// Quality assessment
var quality = await client.Ontology.GetQualityAsync();

// Export (json-ld, cypher, turtle, rdf-xml)
var jsonLd = await client.Ontology.ExportAsync("json-ld");

// Data pattern analysis
var analysis = await client.Ontology.AnalyzeAsync(apply: true);

// LLM enhancement
var enhanced = await client.Ontology.EnhanceAsync();

// Reconcile with schema
var reconciled = await client.Ontology.ReconcileAsync(apply: true);

Versions

var versions = await client.Versions.ListAsync();
var snapshot = await client.Versions.SnapshotAsync(source: "deploy", description: "v1.0 release");
var diff = await client.Versions.DiffAsync(from: 1, to: 2);
var rollback = await client.Versions.RollbackAsync(version: 1);

Usage

var events = await client.Usage.GetEventsAsync(layer: "data", pageSize: 100);
var summary = await client.Usage.GetSummaryAsync(top: 10);
var patterns = await client.Usage.GetCoOccurrenceAsync(minStrength: 0.5);
var analysis = await client.Usage.AnalyzeAsync();

Feedback

var suggestions = await client.Feedback.GetSuggestionsAsync();
await client.Feedback.ApproveAsync("suggestion-id", reason: "Correct relation");
await client.Feedback.RejectAsync("suggestion-id", reason: "False positive");
var history = await client.Feedback.GetHistoryAsync();

Alignment

var report = await client.Alignment.GetReportAsync();
var detail = await client.Alignment.GetConceptAlignmentAsync("concept:Product");

Changes

var detection = await client.Changes.DetectAsync();
var history = await client.Changes.GetHistoryAsync(limit: 100);
await client.Changes.ResetAsync();

Health

var healthy = await client.IsHealthyAsync();

Configuration

Requirements

• .NET 8.0 or later

License

MIT