LLM Generation

Implement business-facing LLM calls as explicit, independently observable workflows. Keep prompt identity, model policy, structured output, and tracing responsibilities separate.

Locate the Existing Boundary

Before editing a call, inspect:

• packages/prompts for reusable application prompts;
• apps/server/src/services/aiGeneration for the server-side structured generation wrapper;
• packages/const/src/llmGenerationTracing.ts for scenario names;
• packages/llm-generation-tracing for tracing option and registry behavior;
• the owning service for model configuration and business-specific schemas.

Use agent-tracing for execution-snapshot diagnosis and agent-runtime-hooks for lifecycle hook behavior. Neither owns application LLM generation conventions.

Prompt Ownership and Versioning

• Put a reusable generation contract in packages/prompts/src/chains: the message builder, JSON schema, schema name, and prompt version should be exported together. Do not leave substantial system prompts or model-facing input serialization embedded in a service.
• Keep execution concerns in the owning server service: model configuration, AiGenerationService, tracing entity IDs, Zod validation, persistence, and business error handling do not belong in the prompt chain.
• Keep each *_PROMPT_VERSION beside the prompt it versions and export both from the same module.
• Format versions as v<major> or v<major>.<minor>, for example v1 or v1.2.
• Store only the version in promptVersion. Do not include a feature or scenario prefix such as expertise-ingestion-v1; scenario carries workflow identity.
• Bump the version whenever a prompt or output contract changes in a way that should create a separate evaluation or tracing cohort.

export const EXAMPLE_PROMPT_VERSION = 'v1';

export const EXAMPLE_SYSTEM_PROMPT = `...`;

Scenario Semantics