Quatzal.Client 0.1.0-alpha.1

Quatzal.Client (C#)

Dependency-free .NET client for Quatzal — a local-first vector + graph database that records who vouched for every fact and when it stopped being true. Talks to a Quatzal server over the MCP Streamable-HTTP transport using only System.Text.Json; no third-party packages.

dotnet add package Quatzal.Client

using var client = new UaceClient(new Uri("https://quatzal.example.com:8443"), token,
    new UaceClientOptions { CaCertificatePem = File.ReadAllText("dev-root.pem") });

// Bulk ingest — one WAL fsync per batch, ~500 rows is the sweet spot
var n = await client.InsertRowsAsync(rows);

// Search with the evidence contract
var resp = await client.SearchVectorsAsync(new SearchParams { K = 10, QueryVector = q, MaxDistance = 0.5 });
if (resp.SufficientEvidence == false)
    Console.WriteLine(resp.Message); // honest "no relevant rows" instead of junk hits

// Graph — search hits feed expansion directly
await client.AddEdgeAsync("doc-1", "doc-2", "cites", 1.0);
var neighbors = await client.ExpandGraphAsync(seeds, hops: 2, k: 10);

Notes that matter

• Vectors go over the wire as vector_b64 (base64 little-endian f32) automatically.
• Score polarity flips: squared-Euclidean distance (lower is better) for vector queries, BM25/RRF (higher is better) once QueryText is involved. The payload carries no discriminator, so the caller must know which query shape it sent.
• hit.Stale == null means the row never declared an expiry — that is not the same as false.
• Tool refusals throw UaceToolException; bad credentials UaceAuthException; unknown tools UaceRpcException.
• Connection reuse is off by default (safe for bulk ingest); opt in with KeepAlive = true.
• Self-signed deployments: pin the root via CaCertificatePem; the validation callback uses CustomRootTrust.

The type names keep the Uace prefix — that is the project's original internal name, and renaming the public API would break every existing caller for no functional gain.

Status

Pre-release (0.1.0-alpha.1), tracking Quatzal 0.1.0. Quatzal's data formats are not yet stable; treat a store as reproducible from its source data rather than as an archive.

Links

• Documentation: https://www.quatzal.com/docs/index.html
• Source: https://github.com/logixrcorp/quatzal (clients/csharp/)
• Tests: dotnet test Uace.Client.Tests

License

Apache-2.0. Quatzal is open core — the separately licensed commercial modules are not part of this package, and nothing in the client depends on them.