Use Case: CreativeAnswer Knowledge Base Graph Builder

Section 01 -- Overview [M]

Summary [M]

The Source: CA's historical project knowledge -- contracts, client briefs, deliverables, project scopes, pricing structures -- is locked inside an Azure SQL email attachment archive (dbo.AttachmentIndex, "Z1.4"). Each row contains extracted plain text from an email attachment. Unstructured: no schema beyond extracted text and a status flag.

The Target: A typed, structured knowledge graph in the deltaPrism CA tenant containing five object classes (Contract, ClientBrief, Deliverable, ProjectScope, Client) with six relation types, PebbledGlass bins for encrypted access, and versioning. This is the pre-processed, persistent knowledge base that the offer-writing-webdev Relica profile traverses to generate context for offer writing.

The Gap: ca_graph_ingest.py is a prototype script that demonstrates the data flow. It is not a Nexus pipeline node, has no pipeline YAML, no caching contract, and no incremental update logic. This use case specifies the GraphBuildExecutor (new Nexus node type) and two pipeline definitions that replace it entirely.

---

Section 02 -- Actors [M]

---

Section 03 -- User Stories [M/D]

Actor: System (Pipeline)

• P1 [M]: As the Pipeline, I read all qualifying rows from dbo.AttachmentIndex and classify each into one of five object classes (Contract, ClientBrief, Deliverable, ProjectScope, Client) via AI so downstream nodes can extract typed properties
• P1 [M]: As the Pipeline, I extract structured properties from classified text using class-specific prompts injected via prompt_template_fields so the graph contains typed, structured data
• P1 [M]: As the Pipeline, I encrypt sensitive fields with AES-256-GCM and write objects to deltaPrism with PebbledGlass bins so Relica can traverse without exposing raw data
• P1 [M]: As the Pipeline, I check idempotency (source_id + content_hash) before every write so re-runs do not duplicate data
• P1 [M]: As the Pipeline, I upsert a Client object for every extracted client_name so the graph maintains a canonical client registry
• P1 [M]: As the Pipeline, I create relations between objects (ContractParty, ScopeAttachment, BriefSource, BriefOutcome, DeliverableScope, DeliverableContract) so the graph is traversable

Actor: Admin

• P1 [M]: As Admin, I trigger a full rebuild run (UC4-1a) to populate the graph from scratch or sweep for consistency
• P2 [D]: As Admin, I view run logs showing total processed, inserted, updated, skipped, and errored counts per run

Actor: Relica (Consumer)

• P1 [M]: As Relica, I read from the deltaPrism CA tenant graph and raise GraphCacheEmpty if zero objects exist -- I never return placeholder data
• P2 [D]: As Relica, I log WARN: graph_cache_stale if the last pipeline run is older than 48 hours (incremental) or 30 days (full rebuild)

---

Section 04 -- System Flows [M/D]

Flow A: UC4-1a -- Full Rebuild Pipeline (7 Steps) [M]

Trigger [M]: Manual trigger or scheduled (weekly Sunday 02:00). Passes run context: run_id, run_mode=full, started_at.

Result [M]: All qualifying attachment rows classified, extracted, encrypted, and written to deltaPrism CA tenant graph with relations. Source rows watermarked. Relica can read the graph.

Flow B: UC4-1b -- Incremental Update Pipeline [M]

Trigger [M]: Scheduled nightly (or hourly). Identical 7-step node sequence to UC4-1a.

Difference: SourceIngest query predicate reads only:

• New rows: ingestion_status IS NULL AND TextExtractionStatus = 'done' AND LEN(ExtractedText) > 100
• Changed rows: ingestion_status IS NOT NULL AND updated_at > {last_successful_run_at}

Zero-row exit: If no matching rows, pipeline exits with status success and total_processed=0. CacheRefresh still runs to confirm graph health. No error raised.

GraphBuildExecutor Idempotency Contract [D]

Every object written carries mandatory system properties:

• source_id -- primary key from dbo.AttachmentIndex (idempotency key)
• content_hash -- SHA-256 of raw_text at ingestion time (change detection)
• gl_version -- integer starting at 1, incremented on each content change (plaintext PebbledGlass bin)
• gl_ingested_at -- ISO 8601 timestamp of last successful write (plaintext)
• gl_status -- one of: ingested / updated / skipped / error (plaintext)

---

Section 05 -- Data Model [M/D]

Object Classes (5) [M]

Relations (6) [M]

System Properties (per object) [D]

---

Section 06 -- Screens [D]

Note: This is a backend data pipeline with no end-user forms. All screens are operational monitoring views within the Nexus admin interface.

---

Section 07 -- Integrations [M]

---

Section 08 -- Infrastructure [D]

Required Source Schema Changes [D]

---

Section 09 -- Critical Path [D]

---

Section 10 -- What Is Needed [M]

---

Section 11 -- Acceptance Criteria [M/D]

Definition of Done [D]

Caching Contract [M]

---

Section 12 -- Risks [D]

Open Questions [D]

---

Section 13 -- Cooperator Brief [D]

---

Implementation Requirements (Executor Spec)

Related Artefacts [D]