Skip to content

agent.md

Latest commit

 

History

History
112 lines (82 loc) · 3.1 KB

agent.md

File metadata and controls

112 lines (82 loc) · 3.1 KB
Raw

dpg-scoring agent notes

Purpose

This repository contains the dpg-scoring microservice.

Current focus:

  • Fastify + TypeScript service
  • HMAC-authenticated internal APIs
  • AI-backed match-score compatibility scoring
  • Gemini-first provider setup with future OpenAI support
  • OpenAPI docs via Swagger UI
  • Redis-backed nonce storage and match-score caching

Current API shape

  • public routes:
    • GET /
    • GET /health
    • GET /ready
  • protected routes:
    • POST /api/v1/scores/match

All /api/v1 routes are protected through the shared auth hook.

API docs

  • OpenAPI docs are served from /docs
  • raw OpenAPI JSON is served from /docs/json
  • keep route schema metadata accurate because docs are generated from route definitions
  • prefer OpenAPI as the source of truth even if the UI layer changes later

Match-score architecture

match-score is no longer rule-based.

Use this flow:

  1. validate raw DPG items
  2. normalize and redact sensitive fields from item_state
  3. resolve prompt version
  4. resolve provider
  5. call AI provider
  6. validate structured AI response
  7. return stable API response

Versioning rules

  • API version and prompt version are separate
  • request version defaults to v1
  • request promptVersion is optional
  • API v1 can later run with newer prompt versions
  • always preserve backward compatibility of the API response when changing prompts only

Provider rules

  • keep provider-specific logic inside src/modules/match-score/providers/
  • keep prompt-specific logic inside src/modules/match-score/prompts/
  • do not mix Gemini/OpenAI request formatting into route or service files
  • prefer provider abstraction over branching in route/controller code

Prompt rules

  • prompts must be versioned
  • prompts should return JSON only
  • prompts should score compatibility from 0 to 10
  • prompts should avoid hallucination and use only provided fields
  • prompt changes should be additive and traceable

Secret handling

  • auth secrets are file-based under config/auth.keys.json
  • AI provider secrets are file-based under config/ai.providers.json
  • do not commit real secret values
  • keep example files updated when secret file shapes change

Redis

  • Redis is the shared store for auth nonce replay protection
  • Redis is also used for match-score response caching
  • prefer Redis-backed behavior when REDIS_ENABLED=true
  • in local fallback mode, auth can use in-memory nonce storage and cache can be skipped
  • local Redis is started with docker compose up -d redis

Editing guidance

  • prefer small focused changes
  • keep route handlers thin
  • keep route summaries, descriptions, tags, and security metadata accurate for docs
  • keep orchestration in services
  • validate AI input/output with Zod
  • cache only validated final match-score responses
  • avoid hardcoding domain-specific matching logic into v1
  • preserve the generic compatibility prompt approach unless requirements change

Verification

After non-trivial changes, run:

pnpm check
pnpm build

Useful helpers:

docker compose up -d redis
pnpm call:match-score
pnpm auth:headers -- --format curl