wisent-ground-truth-api

Private ground-truth Q&A API and indexer for Wisent AI repositories.

The service intentionally does not hardcode repository lists, trust weights, glob rules, asset paths, model names, or chunk sizes. It reads those from environment variables and from registries in wisent-ai/wisent-ground-truth-docs.

Durable platform documentation is published at wisent.com/docs/ground-truth. This README remains the repository-local contract for running and configuring the service.

What it does

• Loads a source registry from GitHub.
• Ingests configured repository documentation and selected config files.
• Stores source chunks with repo/path/commit/line citations.
• Exposes search and question-answering endpoints.
• Answers with citations. If no LLM endpoint is configured, /ask returns extractive cited snippets instead of inventing an answer.
• Resolves canonical brand assets such as logos, favicons, app icons, fonts, and store badges from brand-assets.yml.

Run locally

cp .env.example .env
npm install
docker compose up -d postgres
npm run build
npm run dev

Endpoints

GET  /health
GET  /repos
GET  /assets
GET  /assets?product=weles-web&kind=logo
GET  /assets/products
GET  /assets/kinds
GET  /assets/:product/:kind
GET  /assets/:product/:kind/:assetIndex/content
GET  /search?q=...&repo=optional
POST /ingest/repo   { "repo": "optional", "ref": "optional" }
POST /ask           { "question": "...", "scope": { "repos": ["optional"] } }

Source registry

The registry lives in wisent-ground-truth-docs/sources.yml. Add repos, include/exclude globs, owners, and trust tiers there. The API picks them up on the next ingest without a code change.

Brand asset registry

The brand asset registry lives in wisent-ground-truth-docs/brand-assets.yml. It is explicit by design: the resolver returns canonical repo/path/ref/blob URLs plus API-proxied contentUrl links for private assets, and does not infer random .png, .svg, or .woff2 files as brand assets.

Resolver examples:

curl "$GROUND_TRUTH_API/assets/weles-web/logo"
curl "$GROUND_TRUTH_API/assets?product=wisent-landing&kind=font"
curl "$GROUND_TRUTH_API/assets?q=HubotSansExpanded"
curl "$GROUND_TRUTH_API/assets/turbot-web/logo/0/content" > turbot-logo.svg

Answering contract

• Every answer returns citations.
• If sources are missing, the API says so.
• Raw transcripts are disabled by default in the registry and should not be treated as canonical ground truth.
• Detailed implementation facts stay in the owning repo; this API indexes them, it does not become the source itself.