Data Model Reference

This reference describes the key domain objects in Raw to Knowledge, their fields, and how they relate to each other. All objects are persisted in PostgreSQL and identified by UUIDs.

Entity relationship overview

erDiagram
    SourceArtifact ||--o{ TranscriptSegment : "contains"
    TranscriptSegment ||--o{ CandidateQuestion : "produces"
    TranscriptSegment ||--o{ CandidateAnswer : "produces"
    CandidateAnswer ||--|| ClassificationRecord : "has one"
    CandidateAnswer ||--o{ ValidationRecord : "has history"
    ValidationRecord ||--o| ValidationRecord : "prior_record_id"
    CandidateAnswer ||--o| ApprovedAnswer : "published as"
    ApprovedAnswer ||--o| ApprovedAnswer : "supersedes"
    CandidateAnswer ||--o| WorkItem : "escalated to"
    WorkItem ||--o{ GeneratedCandidate : "produces"
    GeneratedCandidate ||--o| CandidateAnswer : "submitted as"

SourceArtifact

The top-level ingest object. Represents one source document, transcript, or data file submitted to Raw to Knowledge.

Field	Type	Description
`artifact_id`	UUID	Primary key. Assigned at ingest.
`source_ref`	string	Unique external identifier for the source (e.g., meeting ID, document URL). Duplicate `source_ref` raises `409 Conflict`.
`source_system`	string	System that produced this artifact (e.g., `zoom`, `confluence`, `support_ticket`).
`source_type`	enum	Format of the content: `transcript`, `document`, `issue`, `page`. Determines which extraction parser is applied.
`legal_basis`	enum	GDPR Article 6 legal basis declared at ingest. Must not be `NOT_ASSESSED` for processing to proceed.
`customer_scope`	string	Optional customer or tenant identifier for multi-tenant scoping.
`raw_content`	text	The full source text submitted at ingest.
`status`	enum	Processing state: `PENDING`, `PROCESSING`, `COMPLETE`, `BLOCKED`. `BLOCKED` when `legal_basis = NOT_ASSESSED`.
`created_at`	timestamp	Ingest timestamp.

TranscriptSegment

A parsed segment of a SourceArtifact. Extraction produces one or more segments per artifact.

Field	Type	Description
`segment_id`	UUID	Primary key.
`artifact_id`	UUID	FK to `SourceArtifact`.
`content`	text	The text content of this segment.
`speaker`	string	Speaker label if available from the source (e.g., `Agent`, `Customer`). Null for non-transcript sources.
`start_time`	float	Timestamp offset in seconds from the start of the recording. Null for non-transcript sources.
`flow_type`	enum	`FLOW_A` (question with answer present) or `FLOW_B` (question without answer — triggers generation).
`sequence`	integer	Ordering position within the artifact.

CandidateQuestion

A question extracted from a TranscriptSegment.

Field	Type	Description
`candidate_id`	UUID	Primary key.
`source_segment_id`	UUID	FK to `TranscriptSegment`.
`artifact_id`	UUID	FK to `SourceArtifact` (denormalized for query convenience).
`question_text`	text	The extracted question text.
`confidence`	float	Extraction model confidence (0.0–1.0).
`flow_type`	enum	`FLOW_A` or `FLOW_B`, inherited from the source segment.

CandidateAnswer

A candidate answer extracted from a TranscriptSegment (Flow A) or produced by the generation pipeline (Flow B).

Field	Type	Description
`candidate_id`	UUID	Primary key.
`source_segment_id`	UUID	FK to `TranscriptSegment`. Null for generated candidates.
`artifact_id`	UUID	FK to `SourceArtifact`.
`answer_text`	text	The candidate answer text.
`confidence`	float	Extraction model confidence (0.0–1.0).
`flow_type`	enum	`FLOW_A` or `FLOW_B`.
`validation_state`	enum	Current position in the validation workflow. See States, Statuses, and Queues.
`created_at`	timestamp	When the candidate was created.

ClassificationRecord

The result of automated Horn information type classification for a CandidateAnswer. One record per candidate.

Field	Type	Description
`record_id`	UUID	Primary key.
`candidate_id`	UUID	FK to `CandidateAnswer`.
`primary_horn_type`	enum	Predicted Horn information type: `FACT`, `CONCEPT`, `PROCEDURE`, `PROCESS`, `REFERENCE`, `PRINCIPLE`, `OPEN_ISSUE`.
`primary_confidence`	float	Classification model confidence for `primary_horn_type` (0.0–1.0).
`assertion_subtype`	string	Finer-grained classification within the Horn type (e.g., `definition`, `eligibility_rule`, `step_sequence`).
`assertion_grammar`	object	Structured grammar extraction. Contains `subject`, `predicate`, `object_value`, and `scope` string fields. Fields may be null if NLTK could not parse sufficient structure from the answer text.
`requires_review`	boolean	True when `primary_confidence < CLASSIFICATION_THRESHOLD` (default 0.75). Flags the candidate for human review.
`model_version`	string	Identifier of the classification model version that produced this record.
`classified_at`	timestamp	When classification ran.

ValidationRecord

An immutable record of a single validation decision on a CandidateAnswer. Multiple records may exist per candidate, forming a decision chain via prior_record_id.

Field	Type	Description
`record_id`	UUID	Primary key.
`candidate_id`	UUID	FK to `CandidateAnswer`.
`decision`	enum	The decision made: `APPROVED`, `REVISED`, `REJECTED`, `ESCALATED`.
`actor`	string	Identity of the person or system that made the decision.
`rationale`	text	Required free-text explanation of the decision.
`revised_text`	text	The revised answer text, if `decision = REVISED`. Null otherwise.
`prior_record_id`	UUID	FK to the previous `ValidationRecord` in the chain. Null for the first decision.
`created_at`	timestamp	When the decision was recorded. Immutable after creation.

ApprovedAnswer

A validated, published knowledge asset in the Raw to Knowledge registry. This is the terminal form of a validated candidate answer.

Field	Type	Description
`answer_id`	UUID	Primary key.
`candidate_id`	UUID	FK to `CandidateAnswer` that was validated and published.
`horn_type`	enum	Horn information type as approved. May differ from the automated classification if revised during validation.
`assertion_subtype`	string	Approved subtype.
`answer_text`	text	The approved answer text (may reflect revisions from the `REVISED` decision).
`assertion_grammar`	object	Approved grammar: `subject`, `predicate`, `object_value`, `scope`.
`status`	enum	Lifecycle status: `APPROVED`, `SUPERSEDED`, `DISPUTED`, `RETIRED`.
`version`	integer	Version number within the supersession chain. Starts at 1; increments on supersede.
`owner_role`	string	The role responsible for this answer's accuracy and maintenance. Required for publication.
`evidence_links`	array	List of URLs or source references that support this answer. Required for publication.
`validation_record_id`	UUID	FK to the `ValidationRecord` that authorized publication. Required.
`supersedes_id`	UUID	FK to the `ApprovedAnswer` this answer replaces. Null if this is the first version.
`customer_scope`	string	Customer or tenant scope inherited from the source artifact.
`review_due`	date	Optional date by which this answer should be reviewed for currency.
`created_at`	timestamp	Publication timestamp.

WorkItem

Represents an unanswered question (Flow B or escalation) that requires generated content.

Field	Type	Description
`work_item_id`	UUID	Primary key.
`question_text`	text	The question that needs to be answered.
`source_segment_id`	UUID	FK to the `TranscriptSegment` containing the original question.
`state`	enum	Current pipeline state. Nine states; see States, Statuses, and Queues.
`escalation_reason`	string	The reason for escalation, if the work item reached `ESCALATED` state. Values include `no_content`, `LLM error: ...`, `LLM circuit open`.
`customer_scope`	string	Customer or tenant scope.
`jira_issue_key`	string	Jira issue key if the escalation was written back to Jira. Null otherwise.
`created_at`	timestamp	When the work item was created.
`updated_at`	timestamp	Last state transition timestamp.

GeneratedCandidate

An LLM-generated candidate answer produced for a WorkItem.

Field	Type	Description
`generated_id`	UUID	Primary key.
`work_item_id`	UUID	FK to `WorkItem`.
`generated_text`	text	The generated answer text.
`citations`	array	List of citation objects. Each citation contains `source_url`, `title`, `authority_weight` (float 0.0–1.0), and `excerpt` (relevant text snippet).
`model_version`	string	LLM model identifier used for generation (matches `LLM_MODEL` at generation time).
`origin`	enum	`AUTOMATED` (LLM-generated) or `KNOWN_ANSWER` (returned from Weaviate similarity match without LLM call).
`created_at`	timestamp	When the candidate was generated.