Retrieval had to understand paraphrases without missing exact product names, domain terms, or numbers.

Technology

PostgreSQL · pgvector · FTS/RRF

Why this technology

Vector similarity covers meaning while full-text search preserves exact tokens, and both stay inside the same data boundary as team documents.

Implementation evidence

Candidates are bounded by team scope, vector and lexical rankings are fused with RRF, and selected chunks remain attached to the draft as citation evidence.

Tradeoff

Both indexes and fusion weights require tuning, and the retrieval path needs more instrumentation.

Multi-stage AI work had to resume after interruption without making the provider runtime the product source of truth.

Technology

OpenAI Agents SDK · PostgreSQL · Prisma

Why this technology

The Agents SDK handles orchestration while teams, documents, runs, and review state remain durable in the product database.

Implementation evidence

Agent run identifiers and stage state are linked to Prisma records; resumed work still derives permissions and next actions from persisted product state.

Tradeoff

Idempotency, retries, and synchronization between runtime and product state require explicit coordination.

A final output alone cannot reveal where a failure began or reproduce the same run conditions.

Technology

TypeScript · Zod · Prisma · revisioned checkpoints

Why this technology

Explicit state transitions preserve per-stage inputs, outputs, and revisions so a run can be compared or resumed from one checkpoint.

Implementation evidence

Attempt UUIDs, transitions, and checkpoint snapshots are schema-validated and published as immutable presstuner-debug-run/v3 evidence.

Tradeoff

Workflow changes require version compatibility, and both storage volume and transition-management code increase.

A prompt change can look better while deleting useful content or regressing cost and latency.

Technology

Versioned eval sets · baseline/candidate · human gate

Why this technology

The same cases and criteria compare before and after, and automated scores never become the sole release decision.

Implementation evidence

Evaluation cases from real documents, independently calculated quality, cost, and latency results, and per-case regression records are reviewed before human approval.

Tradeoff

Evaluation sets need ongoing maintenance and the review gate slows the path from experiment to release.

Different LangSmith, PostHog, and GA4 identifiers made one AI operation impossible to join to its product outcome.

Technology

service-issued operation ID · versioned workflow contract

Why this technology

A stable product-issued identifier is propagated to every telemetry provider instead of relying on provider-specific IDs.

Implementation evidence

The operation ID is written to LangSmith metadata, PostHog and GA4 events, and brieFFlow checkpoint snapshots, then verified during ingestion.

Tradeoff

Every producer must adopt the contract and version, with explicit handling for missing or outdated producers.

A central console touching several analytics providers could create excessive permissions, privacy exposure, and unbounded retries.

Technology

Read-only connectors · allowlist normalization · bounded collection

Why this technology

Collection is read-only and project-scoped, while only approved fields enter the normalized evidence model.

Implementation evidence

LangSmith, PostHog, and GA4 collectors bound pages, records, and retries; cursors advance only after normalized rows commit, and incomplete runs stay partial.

Tradeoff

Some raw-provider detail is intentionally lost, and each provider still needs an allowlist and adapter.

If dashboards and reports calculate metrics separately, they can show different numbers for the same window.

Technology

PostgreSQL · strict schemas · canonical hash · deterministic aggregation

Why this technology

Normalized evidence and metric calculation share one contract so every surface reuses the same result.

Implementation evidence

Zod schemas reject unknown or unsafe fields, while canonical hashes and a provider-neutral metric engine produce the same aggregate from the same input.

Tradeoff

Contract changes require schema migrations, and each new provider needs an adapter into the canonical model.

A natural-language report must not reinterpret raw logs freely or invent numbers that differ from stored metrics.

Technology

RAG reporting · numeric citation verifier

Why this technology

The LLM explains verified aggregates only, and every numeric claim must trace back to a stored fact and source.

Implementation evidence

Canonical facts are retrieved by project and time window before generation; afterward, any numeric citation that does not match its evidence is rejected.

Tradeoff

Questions without verifiable facts receive a bounded answer, making the system deliberately less free-form.