Houndex TypeScript

Houndex is a last-mile knowledge framework for building source-backed AI systems.

Most RAG tools help you retrieve context. Houndex focuses on what happens after retrieval: turning sources, claims, evidence, citations, verification results, and provenance into typed artifacts your application can trust, inspect, store, and test.

Houndex is designed for teams building AI products where answers need receipts.

This repository contains the TypeScript implementation. A companion Python implementation tracks the same contracts, and shared cross-language parity fixtures keep the two cores aligned on their core primitives.

What Houndex does

Houndex gives applications a small set of durable primitives:

• Sources — documents, pages, messages, files, APIs, or tool results.
• Claims — structured statements extracted from source material.
• Evidence — source-backed excerpts or records that support claims.
• Edges — relationships between claims, sources, evidence, contradictions, and outputs.
• Output envelopes — typed, versioned responses with citations and provenance.
• Storage adapters — pluggable persistence for claims, evidence, traces, and outputs.
• Provider ports — interfaces for search, scraping, embedding, reranking, and model calls.
• Evals — regression checks for citation quality, envelope validity, and unsupported claims.

The goal is not to replace your app, model provider, vector database, or RAG framework.

The goal is to make generated knowledge traceable, reviewable, portable, and testable.

Why this exists

RAG demos are easy. Production knowledge systems are harder.

Common problems:

• Answers cite sources that do not actually support them.
• Claims are mixed with raw chunks and become hard to inspect.
• Retrieval traces disappear into logs.
• Human review is bolted on later.
• Outputs are plain text instead of typed application data.
• Storage choices are coupled to framework choices.
• Prompt, model, and retriever changes cause silent regressions.

Houndex treats knowledge as a set of source-backed artifacts rather than a one-shot chat response.

More importantly, modern AI workflows increasingly rely on agents moving information between systems. A sales operations agent may pull customer data from Salesforce, retrieve contract terms from Google Drive, check support history in Zendesk, and push recommendations into Jira or Slack. Each step creates new claims that influence downstream decisions.

Without a structured knowledge layer, teams are left asking:

• Which source produced this recommendation?
• Was the contract clause actually cited?
• Did the agent use the latest customer record?
• What changed when we updated the retrieval pipeline?

Houndex provides the connective tissue between retrieval and action. Instead of passing around opaque text, agents exchange source-backed claims, evidence, citations, and provenance that can be inspected, verified, stored, and reused across workflows.

For example, imagine a customer renewal workflow. An agent gathers account activity from a CRM, support escalations from a ticketing system, product usage metrics from an analytics platform, and contract obligations from a document repository. It then generates a renewal risk assessment and creates tasks for account managers. With Houndex, every recommendation can be traced back to the underlying records, reviewed by humans, validated against evidence, and audited later if questions arise. The result is not just better answers—it is higher confidence, faster reviews, reduced operational risk, and AI workflows that teams can trust in production.

Pipeline

Houndex models the last-mile knowledge flow as:

Ingest → Extract → Link → Curate → Answer → Verify → Evaluate

In plain English:

1. Collect source material from files, web pages, docs, APIs, or tools.
2. Extract claims and evidence from that material.
3. Link related knowledge through support, contradiction, citation, and provenance edges.
4. Curate what is trusted through human or application workflows.
5. Generate typed outputs for your application.
6. Verify citations and claims against evidence.
7. Evaluate regressions as prompts, models, storage, and retrieval change.

Example use cases

Houndex can be used anywhere generated knowledge needs to show its work:

• Product documentation assistants.
• Compliance and policy assistants.
• Customer support knowledge systems.
• Research workbenches.
• Engineering decision record search.
• Source-backed analysis products.
• Internal tools that need citations, provenance, and review.
• Domain-specific AI products that need trusted output envelopes.

What Houndex is not

Houndex is not:

• A chatbot.
• A model provider.
• A vector database.
• A hosted enterprise search product.
• A replacement for every RAG framework.
• A guarantee that generated text is true.

Verification in Houndex is evidence-relative. It can tell you whether an answer is supported by the available evidence, but it does not magically make weak sources correct.

Package status

| Entry point | Status | Purpose | |---|---|---| | houndex/core | Active | Schemas, output envelopes, claims, evidence, traces, provider ports, storage contracts | | houndex/pipeline | Active | Deterministic ingestion/enrichment: chunking, dedupe, source tiering, claim assembly | | houndex/storage/local | Active | Zero-service in-memory reference adapter | | houndex/storage/supabase | Active | Postgres + pgvector adapter (HNSW cosine search, RLS) | | houndex/storage/convex | Active | Convex adapter (vector index + tenant-scoped search action) | | houndex/evals | Active | Regression harness: fixture schema, envelope rubric scoring, reports | | houndex/cli | Active | init, doctor, ingest, ask, verify, eval over a configured adapter | | houndex/connectors | Active | Deterministic source connectors for files, explicit web URLs, GitHub repositories, and documentation sites | | packages/surface-next | Repo app | Optional Next.js curation, provenance, and citation review UI |

The core framework packages are implemented in both TypeScript and Python. Shared parity fixtures keep claim identity, canonical JSON, and the synthetic embedder byte-for-byte identical across the two languages. Surface packages are language-specific. The npm package is published as one package, houndex, with subpath exports for the modules above.

Quickstart

Install the framework with your package manager:

npm install houndex
pnpm add houndex
bun add houndex

The local adapter and core evaluation path need no external service. Storage providers are npm optional-peer style: install houndex plus the SDK for the provider you use.

npm install houndex @supabase/supabase-js
npm install houndex convex convex-helpers

Verify a model answer against an evidence store with the CLI. The CLI reads houndex.config.json and defaults to an in-memory store, so it needs no services:

npx houndex init
npx houndex verify answer.json

verify checks that the answer envelope is schema-valid and that every cited claim resolves to a stored claim. It exits 0 when the answer is grounded, 1 when a citation does not resolve or the envelope is invalid, and 2 on an operational error such as a missing file. Use the exit code as a CI gate.

In application code, import only the surface you need:

import { computeClaimId } from 'houndex/core';
import { scoreEnvelope } from 'houndex/evals';
import { LocalStorageAdapter } from 'houndex/storage/local';

Call the same engine in-process on each answer through houndex/evals (scoreEnvelope). The CLI and the library share one engine, so their verdicts are identical.

Design principles

Storage-decoupled

Houndex defines storage contracts instead of forcing one database. Use local storage for development, Supabase/Postgres for production, Convex for reactive apps, or implement your own adapter.

Source-agnostic

Houndex does not care whether knowledge comes from PDFs, Markdown files, Slack, Notion, GitHub, MCP tools, or custom APIs. Connectors normalize source material into common primitives.

Typed by default

Outputs are wrapped in versioned envelopes so downstream applications can validate, render, store, and audit them.

Provenance-first

Claims, citations, evidence, traces, and outputs should be inspectable. The system should be able to answer: “Where did this come from?”

Human-review friendly

Houndex is designed for workflows where humans may approve, reject, edit, or override knowledge before it becomes trusted.

Eval-ready

Every serious knowledge system needs regression tests. Houndex treats evals as part of the framework, not an afterthought.

Roadmap

Houndex is early and under active development. The contracts are stable enough to build on; the surface area is still growing.

Shipped, in both TypeScript and Python:

• core contracts, the deterministic pipeline, three storage adapters (storage-local, storage-supabase, storage-convex), the evals harness, the cli, and connectors for files, explicit web URLs, GitHub repositories, and documentation sites.

Planned, in roughly this order:

1. Release automation for npm to match the PyPI trusted-publisher flow.

Development

Requires Node 24 (pinned in .nvmrc) and pnpm 9.

pnpm install
pnpm verify
pnpm build

pnpm verify runs the full local gate: pnpm check (Biome lint and format), pnpm typecheck (tsc --noEmit, strict), and pnpm test (Vitest). Run node scripts/cleanroom-guard.mjs to confirm no origin-specific terms appear in tracked files. pnpm build emits compiled JavaScript, declaration files, source maps, and the houndex CLI executable into dist/; npm pack and npm publish run this build before packaging.

The Supabase and Convex adapters carry live integration tests that are skipped unless their environment is configured:

• Supabase: run supabase start && supabase db reset, then set SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY.
• Convex: run pnpm exec convex dev --once inside packages/storage-convex, then set CONVEX_URL.

License

MIT