LLM System: Prompting (Starter Template)

Phase: Phase 0 (Planning)
Status: Draft — finalize in Phase 1
Owner: AI/LLM Lead
References:

/docs/archetypes.md
/docs/llm/safety.md
/docs/llm/evals.md

This document defines how prompts are designed, versioned, and executed.
It is archetype‑agnostic: adapt the “interaction surface” (chat, workflow generation, pipeline classification, agentic tasks) to your product.

1. Goals

Produce consistent, auditable outputs across models/providers.
Make prompt changes safe and reversible (versioning + evals).
Keep sensitive data out of prompts unless strictly required (see safety).

2. Single LLM Entry Point

All LLM calls go through one abstraction (e.g., callLLM() / “LLM Gateway”):

Centralizes model selection, temperature/top_p defaults, retries, timeouts.
Applies redaction and policy checks before sending prompts.
Emits structured logs + trace IDs to EventLog.
Enforces output schema validation.

Lock the exact interface and defaults in Phase 1.

3. Prompt Types

Define prompt families that match your archetype:

Chat‑first: system prompt + conversation memory + optional retrieval context.
Generation/workflow: task prompt + constraints + examples + output schema.
Classification/pipeline: short instruction + label set + few‑shot examples + JSON output.
Agentic automation: planner prompt + tool policy + step budget + “stop/ask‑human” rules.

4. Prompt Structure (recommended)

Use a predictable layout for every prompt:

System / role: who the model is, high‑level mission.
Safety & constraints: what not to do, privacy rules, refusal triggers.
Task spec: exact objective and success criteria.
Context: domain data, retrieved snippets, tool outputs (clearly delimited).
Few‑shot examples: 1–3 archetype‑relevant pairs.
Output schema: strict JSON/XML/markdown template.

Example skeleton

[SYSTEM]
You are ...

[CONSTRAINTS]
- Never ...
- If unsure, respond with ...

[TASK]
Given input X, produce Y.

[CONTEXT]
<untrusted_input>
...
</untrusted_input>

[EXAMPLES]
Input: ...
Output: ...

[OUTPUT_SCHEMA]
{ "label": "...", "confidence": 0..1, "reasoning_trace": {...} }

5. Prompt Versioning

Store prompts in a dedicated location (e.g., prompts/ folder or DB table).
Semantic versioning: prompt_name@major.minor.patch.
- major: behavior change or schema change.
- minor: quality improvement (new examples, clearer instruction).
- patch: typos / no behavior change.
Every version is linked to:
- model/provider version,
- eval suite run,
- changelog entry.

6. Output Schemas & Validation

Prefer strict JSON for machine‑consumed outputs.
Validate outputs server‑side:
- required fields present,
- types/enum values correct,
- confidence in range,
- no disallowed keys (PII, secrets).
If validation fails: retry with “fix‑format” prompt or fallback to safe default.

7. Context Management

Separate trusted vs untrusted context:
- Untrusted: user input, webhook payloads, retrieved docs.
- Trusted: system instructions, tool policies, fixed label sets.
Delimit untrusted context explicitly to reduce prompt injection risk.
Keep context minimal; avoid leaking irrelevant tenant/user data.

8. Memory (if applicable)

For chat/agentic archetypes:

Short‑term memory: last N turns.
Long‑term memory: curated summaries or embeddings with strict privacy rules.
Never store raw PII in memory unless required and approved.

9. Open Questions to Lock in Phase 1

Which models/providers are supported at launch?
Default parameters and retry/backoff policy?
Where prompts live (repo vs DB) and who can change them?
How schema validation + fallback works per archetype?

3.8 KiB Raw Blame History Unescape Escape