Epic: Interview Blueprint Schema & Storage

[mathaix]

Overview

The Interview Blueprint is the single source of truth that drives all Clara functionality - from agent behavior to synthesis rules to report generation. This epic covers the schema definition, storage, and versioning.

Updated for Adaptive Interview Architect: Blueprints now include a shared rubric across all agents and support multiple agents (1..N) per blueprint.

Business Value

A well-defined, validated blueprint schema ensures:

• Consistent agent behavior across interviews
• Proper entity extraction via shared rubric
• Reliable synthesis across multiple agents
• Version control for iterative improvement

User Stories in this Epic

• Blueprint Core Schema Definition #18 - Blueprint Core Schema Definition (with shared rubric)
• Agent Blueprint Schema #19 - Agent Blueprint Schema (with exit conditions, rubric mapping)
• Shared Rubric Schema (Meta-Schema) #20 - Extraction Schema → Shared Rubric Schema
• Synthesis Rules Schema #21 - Synthesis Rules Schema
• Blueprint Storage & Versioning #22 - Blueprint Storage & Versioning
• Blueprint Validation Service #23 - Blueprint Validation Service
• Agent Factory: Blueprint to Agent Instantiation #24 - Agent Factory: Blueprint to Agent

Key Schema Components

New: Shared Rubric (RubricSpec)

Replaces per-agent ExtractionSpec with project-level shared rubric:

class RubricSpec(BaseModel):
    fields: list[FieldDef]      # Data fields to extract
    scales: list[ScaleDef]      # Measurement scales
    rules: list[RuleDef]        # Business rules and flags
    domain_context: str         # Why this rubric structure
    assumptions: list[str]      # Explicit assumptions

New: Execution Plan

Simple agent-to-interviewee mapping:

class ExecutionPlan(BaseModel):
    mappings: list[AgentIntervieweeMapping]

Updated: InterviewBlueprint

class InterviewBlueprint(BaseModel):
    metadata: BlueprintMetadata
    project: ProjectContext
    shared_rubric: RubricSpec          # NEW: Shared across all agents
    agents: list[AgentBlueprint]       # 1..N agents
    execution_plan: ExecutionPlan      # NEW: Agent-to-interviewee mapping
    synthesis: SynthesisBlueprint
    quality: QualitySpec

Updated: AgentBlueprint

class AgentBlueprint(BaseModel):
    id: str
    name: str
    mission: str                        # NEW: Agent's mission
    target_interviewees: IntervieweeSpec
    persona: PersonaSpec
    goals: list[GoalSpec]
    questions: list[QuestionSpec]
    question_flow: QuestionFlowSpec
    rubric_field_mapping: list[str]    # NEW: Which rubric fields this agent populates
    system_prompt: str                  # Human-readable for debugging
    exit_conditions: ExitConditions     # NEW: When to exit interview
    config: AgentConfig
    design_rationale: DesignRationale

Technical Requirements

• Pydantic models with strict validation
• JSONB storage in PostgreSQL
• Version tracking with change history
• Schema migration from old ExtractionSpec to RubricSpec

Dependencies

• PostgreSQL database setup
• Adaptive Interview Architect (produces blueprints)
• Interview Agent (consumes blueprints)

---

🤖 Generated with Claude Code