SPDF in C# / .NET

dotnet add package Spdf.Format

using Spdf;

using var file = SpdfFile.Open("quijote.spdf");   // also legacy .spdf (gzip) files

foreach (var hit in file.SearchLexical("«lugar de la Mancha»", limit: 5))
{
    Console.WriteLine($"{hit.FragmentId} {hit.Score:F6} {hit.AnchorUri}");
    Console.WriteLine(file.Cite(hit.Anchor!, hit.AnchorEnd, "es"));
    // (Cervantes Saavedra, 1605, fols. 1r-[1v])
}

// Vector and hybrid search with your own query embedding.
double[] query = new double[8];
var nearest = file.SearchVector(query, space: "toy-embedding@8", target: "fragment", limit: 5);
var pages = file.SearchVector(query, "toy-embedding@8", target: "unit");      // hits carry UnitId
var fused = file.SearchHybrid("hidalgo", query, "toy-embedding@8", limit: 5);

// Typed reading.
Document doc = file.GetDocument();
IReadOnlyList<Unit> pages = file.GetUnits();
IReadOnlyList<Fragment> fragments = file.GetFragments();
Blob? original = file.GetBlob("blob:original.pdf");

Console.Write(file.ExportBibTeX());              // @book{cervantessaavedra1605, …
Console.WriteLine(file.ExportCslJson());         // [{"id":"cervantessaavedra1605", …}]
BibTexEntry entry = file.ExportBibTeXEntry();    // entry type, key and fields

// Several documents at once (keys disambiguated with a, b, c…), and a CSL citation item.
string bib = BibliographyExport.BibTeX([file.GetMetadata(), other.GetMetadata()]);
var cited = BibliographyExport.CslItems([file.GetMetadata()], hit.Anchor, hit.AnchorEnd);  // + label, locator

// Resolving a reference (§5.4): units, fragments, char range and region it designates.
LocateResult where = file.Locate("spdf:sha256-…#p=5&pe=6&char=101,278");
LocateResult byUrl = file.Locate("https://example.org/quijote.spdf#f=1v");

// Structural exports (§19.4): ALTO 4, a minimal TEI and a IIIF Presentation 3 manifest.
// No invented coordinates or dimensions; inferred folios bracketed (TEI, IIIF) or absent (ALTO).
string alto = file.ExportAlto();      // Page per page unit, TextBlock / TextLine / String per word
string tei = file.ExportTei();        // teiHeader, <pb n facs/>, <p>, <lg>/<l n>, <u who>, <note place="foot">
string iiif = file.ExportIiif(new IiifOptions { Base = "https://example.org/quijote" });
var pageSequence = StructureExport.PageSequence(StructureFormat.Tei, tei);   // read back from the XML

ValidationResult result = SpdfValidator.Validate("file.spdf");
Console.WriteLine($"{result.Valid} {string.Join(",", result.ErrorCodes)} {string.Join(",", result.WarningCodes)}");

using var file = SpdfFile.Open("file.spdf");
string dump = file.DumpJson();          // RFC 8785 text
string hash = file.ContentSha256();     // integrity hash of §13

var anchor = Anchor.Page(29, "21", source: "inferred").WithChars(118, 301);
string uri = AnchorUri.Format("sha256-3f2a…", anchor);   // spdf:sha256-3f2a…#p=29&f=21&char=118,301
ParsedAnchorUri parsed = AnchorUri.Parse(uri);           // FormatException if malformed

var metadata = new Dictionary<string, object?>
{
    ["type"] = "book",
    ["title"] = "Arte nuevo de hacer comedias",
    ["author"] = new List<object?> { new Dictionary<string, object?> { ["family"] = "Vega", ["non-dropping-particle"] = "de", ["given"] = "Lope" } },
    ["issued"] = new Dictionary<string, object?> { ["date-parts"] = new List<object?> { new List<object?> { 1609L } } },
};
Console.WriteLine(Citation.Cite(anchor, null, metadata, "es"));   // (de Vega, 1609, p. [21])

using var w = SpdfWriter.Create("out.spdf", new SpdfWriterOptions { Generator = "my-tool/1.0" });
w.SetDocument(new Document
{
    Id = "rimas", Kind = "pdf", Mime = "application/pdf", SourceSha256 = sha, Bytes = size,
    Metadata = new Dictionary<string, object?> { ["type"] = "book", ["title"] = "Rimas" },
});
w.AddUnit(new Unit { Id = "u1", Reader = "pdf-text-layer", Text = "…", Anchor = Anchor.Page(1, "1") });
w.AddFragment(new Fragment { Id = "f1", Unit = "u1", Text = "…", Anchor = Anchor.Page(1, "1").WithChars(0, 120) });
w.AddSpace(new Space { Id = "embeddinggemma-2@768:i8", Provider = "local", Model = "embeddinggemma-2", Dims = 768, DType = "i8" });
w.AddVector("fragment", "f1", "embeddinggemma-2@768:i8", embedding);   // float[] or double[], quantized per §9.2
w.AddBlob("original.pdf", "application/pdf", bytes);
w.Commit();   // document + spdf_meta, FTS rebuild, VACUUM, atomic move into place

byte[] seed = LoadSeedFromYourKeyStore();   // 32 bytes; never commit it to a repository
using var w = SpdfWriter.Create("signed.spdf", new SpdfWriterOptions { SigningKey = seed });
// … rows …
w.Commit();
bool ok = SpdfValidator.Validate("signed.spdf").Valid;   // recomputes the hash, verifies the signature

dotnet run --project src/Spdf.Cli -- validate file.spdf
dotnet run --project src/Spdf.Cli -- dump file.spdf
dotnet run --project src/Spdf.Cli -- search file.spdf "lugar de la Mancha" -n 5
dotnet run --project src/Spdf.Cli -- vsearch file.spdf toy-embedding@8 0.5,0.25,0.5,0.25,0,0.25,0.25,0.5
dotnet run --project src/Spdf.Cli -- cite file.spdf q4 --locale en
dotnet run --project src/Spdf.Cli -- export file.spdf bibtex        # also csl, alto, tei, iiif
dotnet run --project src/Spdf.Cli -- sample demo.spdf --key-file seed.hex   # small signed demo file
dotnet run --project src/Spdf.Cli -- uri parse 'spdf:sha256-…#p=29&f=21'
dotnet run --project src/Spdf.Cli -- build source.json out.spdf
dotnet run --project src/Spdf.Cli -- conformance ../conformance -o conformance.json

cd dotnet
dotnet build
dotnet test                       # unit tests and the whole conformance suite
dotnet run --project src/Spdf.Cli -- conformance ../conformance -o conformance.json
dotnet pack src/Spdf.Format -c Release -o artifacts