metis-memory 0.1.0__py3-none-any.whl

metis/__init__.py

@@ -0,0 +1,16 @@
+"""Metis, a reference toolkit for governed tacit fragment capture.
+
+Metis captures situated human practice as partial, validated, context-bound fragments
+tied to provenance, consent, authority, review state, and retrieval constraints, and turns
+validated fragments into governed tacit memory objects that AI agents can use alongside
+procedural, semantic, and episodic memory, exposed only through condition-aware governance
+gates. It uses local Ollama/Gemma models for bounded assistance and CHAP as its protocol
+foundation.
+"""
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+from .engine import MetisEngine
+
+__all__ = ["MetisEngine", "__version__"]

metis/api/__init__.py

@@ -0,0 +1,6 @@
+"""Optional local FastAPI server for Metis (install the ``api`` extra)."""
+try:
+    from .server import app, create_app
+    __all__ = ["app", "create_app"]
+except Exception:  # fastapi not installed
+    __all__ = []

metis/api/routes.py

@@ -0,0 +1,167 @@
+"""FastAPI routes over the same engine, models, and evidence logic as the CLI.
+
+Optional component (install with the ``api`` extra). Governance remains deterministic and
+human-reviewed; nothing here lets a model or an agent promote or authorise a fragment.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel
+
+from ..conditions.context import TacitContext
+from ..consent.model import ConsentRecord, ConsentStatus
+from ..consent.revocation import RevocationReason
+from ..engine import MetisEngine
+from ..scenarios import run_manufacturing
+
+router = APIRouter()
+
+# A single in-memory engine, seeded with the manufacturing scenario for immediate data.
+ENGINE = run_manufacturing().engine
+
+
+def reset_engine(engine: MetisEngine | None = None) -> None:
+    global ENGINE
+    ENGINE = engine or run_manufacturing().engine
+
+
+class CaptureRequest(BaseModel):
+    observation_id: str
+    work_as_imagined: str | None = None
+    work_as_done: str | None = None
+    text: str | None = None
+    context: dict[str, Any] = {}
+    category: str | None = None
+    response: str = "confirm"
+    corrected_content: str | None = None
+    title: str | None = None
+
+
+class ReviewRequest(BaseModel):
+    fragment_id: str
+    outcome: str
+    summary: str = ""
+    change_control: dict[str, Any] | None = None
+
+
+class ContextRequest(BaseModel):
+    context: dict[str, Any]
+    role: str | None = None
+    task_id: str = "tsk_api_query"
+
+
+class RevokeRequest(BaseModel):
+    fragment_id: str
+    reason: str = "retired"
+    by: str = "human:reviewer@plant_a"
+
+
+@router.get("/workspace")
+def get_workspace() -> dict[str, Any]:
+    return ENGINE.adapter.descriptor()
+
+
+@router.get("/fragments")
+def list_fragments() -> list[dict[str, Any]]:
+    return [f.model_dump(mode="json") for f in ENGINE.fragments.all()]
+
+
+@router.get("/fragments/{fragment_id}")
+def get_fragment(fragment_id: str) -> dict[str, Any]:
+    frag = ENGINE.fragments.get(fragment_id)
+    if not frag:
+        raise HTTPException(404, "fragment not found")
+    return frag.model_dump(mode="json")
+
+
+@router.get("/memory")
+def list_memory() -> list[dict[str, Any]]:
+    return [m.model_dump(mode="json") for m in ENGINE.tacit_store.all()]
+
+
+@router.get("/memory/{memory_id}")
+def get_memory(memory_id: str) -> dict[str, Any]:
+    m = ENGINE.tacit_store.get(memory_id)
+    if not m:
+        raise HTTPException(404, "memory object not found")
+    return m.model_dump(mode="json")
+
+
+@router.post("/memory/query")
+def memory_query(req: ContextRequest) -> dict[str, Any]:
+    amc = ENGINE.agent_context(req.task_id, TacitContext.model_validate(req.context), role=req.role, emit=True)
+    return amc.model_dump(mode="json")
+
+
+@router.post("/capture")
+def capture(req: CaptureRequest) -> dict[str, Any]:
+    consent = ConsentRecord(consent_status=ConsentStatus.granted)
+    result = ENGINE.capture_observation(
+        dict(observation_id=req.observation_id, work_as_imagined=req.work_as_imagined,
+             work_as_done=req.work_as_done, text=req.text,
+             context=TacitContext.model_validate(req.context), source="api"),
+        consent=consent, response=req.response, corrected_content=req.corrected_content,
+        category=req.category, title=req.title,
+        conditions=TacitContext.model_validate(req.context))
+    return {"fragment": result.fragment.model_dump(mode="json") if result.fragment else None,
+            "task_id": result.task_id,
+            "model_assist_records": [a.assist_id for a in result.model_assist_records]}
+
+
+@router.post("/confirm")
+def confirm(req: CaptureRequest) -> dict[str, Any]:
+    """Confirmation is captured as part of the loop; this is an alias for /capture."""
+    return capture(req)
+
+
+@router.post("/review")
+def review(req: ReviewRequest) -> dict[str, Any]:
+    out = ENGINE.tier2_review(req.fragment_id, req.outcome, summary=req.summary,
+                              change_control=req.change_control)
+    return {"outcome": req.outcome, "memory_id": out.get("memory").memory_id if out.get("memory") else None}
+
+
+@router.post("/promote")
+def promote(req: ReviewRequest) -> dict[str, Any]:
+    if req.outcome not in ("promoted_to_advisory", "promoted_to_controlled"):
+        req.outcome = "promoted_to_advisory"
+    return review(req)
+
+
+@router.post("/retrieve")
+def retrieve(req: ContextRequest) -> dict[str, Any]:
+    decision = ENGINE.retrieve(TacitContext.model_validate(req.context), role=req.role)
+    return decision.model_dump(mode="json")
+
+
+@router.post("/revoke")
+def revoke(req: RevokeRequest) -> dict[str, Any]:
+    art = ENGINE.governance.revoke(req.fragment_id, reason=RevocationReason(req.reason), by=req.by)
+    return {"revocation_record_artefact": art}
+
+
+@router.get("/audit")
+def audit() -> list[dict[str, Any]]:
+    return ENGINE.adapter.evidence_records()
+
+
+@router.post("/audit/export")
+def audit_export(out: str = "evidence.jsonl") -> dict[str, Any]:
+    n = ENGINE.export_audit(out)
+    return {"exported": n, "path": out, "verified": ENGINE.verify().ok}
+
+
+@router.get("/model/status")
+def model_status() -> dict[str, Any]:
+    c = ENGINE.model_client
+    return {"provider": c.config.provider, "model": c.config.name, "url": c.config.url,
+            "available": c.available()}
+
+
+@router.post("/model/run")
+def model_run(prompt: str, purpose: str = "draft_whisper") -> dict[str, Any]:
+    res = ENGINE.model_client.run(purpose, prompt)
+    return {"used_live_model": res.used_live_model, "output": res.json(),
+            "note": "advisory draft only; not a governance decision"}

metis/api/server.py

@@ -0,0 +1,19 @@
+"""Local FastAPI server. Run: ``uvicorn metis.api.server:app``. Optional component."""
+from __future__ import annotations
+
+
+def create_app():
+    from fastapi import FastAPI
+
+    from .routes import router
+
+    application = FastAPI(
+        title="Metis",
+        description="Governed tacit fragment capture, local-first, CHAP-aligned. "
+                    "Tacit memory is exposed only through condition-aware governance gates.",
+        version="0.1.0")
+    application.include_router(router)
+    return application
+
+
+app = create_app()

metis/audit/__init__.py

@@ -0,0 +1,4 @@
+from .export import export_jsonl, export_records
+from .replay import ReplayResult, replay
+
+__all__ = ["export_jsonl", "export_records", "replay", "ReplayResult"]

metis/audit/export.py

@@ -0,0 +1,28 @@
+"""Export the CHAP evidence chain as portable JSONL.
+
+Each line is one audit entry (the dispatched JSON-RPC envelope plus its chain link), so the
+export is both an audit log and a replayable record. The chain is append-only.
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+
+def export_records(source: Any) -> list[dict[str, Any]]:
+    """Return the evidence records from an adapter (or anything with evidence_records())."""
+    if hasattr(source, "evidence_records"):
+        return source.evidence_records()
+    adapter = getattr(source, "adapter", source)
+    return adapter.evidence_records()
+
+
+def export_jsonl(source: Any, path: str | Path) -> int:
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    records = export_records(source)
+    with path.open("w") as fh:
+        for rec in records:
+            fh.write(json.dumps(rec, separators=(",", ":")) + "\n")
+    return len(records)

metis/audit/replay.py

@@ -0,0 +1,40 @@
+"""Replay and verify an exported evidence chain, independent of the live Coordinator.
+
+Reproduces the Coordinator's hash linkage (``prev = sha256( JCS(envelope) || prev )``) over
+the exported JSON-RPC envelopes and confirms prev_hash continuity.
+"""
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from chap_coordinator import ZERO_HASH, canonicalize, sha256_hex
+
+
+@dataclass
+class ReplayResult:
+    ok: bool
+    checked: int
+    errors: list[str] = field(default_factory=list)
+    methods: list[str] = field(default_factory=list)
+
+
+def load_jsonl(path: str | Path) -> list[dict[str, Any]]:
+    return [json.loads(line) for line in Path(path).read_text().splitlines() if line.strip()]
+
+
+def replay(path: str | Path) -> ReplayResult:
+    records = load_jsonl(path)
+    errors: list[str] = []
+    methods: list[str] = []
+    prev = ZERO_HASH
+    for rec in records:
+        env = rec.get("envelope") or {}
+        ph = rec.get("prev_hash")
+        if ph is not None and ph != prev:
+            errors.append(f"seq {rec.get('seq')}: prev_hash break")
+        methods.append(rec.get("method_or_type") or env.get("method", "?"))
+        prev = sha256_hex(canonicalize(env) + prev.encode("utf-8"))
+    return ReplayResult(ok=not errors, checked=len(records), errors=errors, methods=methods)

metis/capture/__init__.py

@@ -0,0 +1,12 @@
+from .confirm import ConfirmationResult, operator_confirm
+from .infer import InferenceCandidate, infer_candidate
+from .loop import CaptureLoop, CaptureResult
+from .observe import Observation, build_observation
+from .remember import build_fragment
+from .whisper import WhisperPrompt, build_whisper
+
+__all__ = [
+    "CaptureLoop", "CaptureResult", "Observation", "build_observation",
+    "InferenceCandidate", "infer_candidate", "WhisperPrompt", "build_whisper",
+    "ConfirmationResult", "operator_confirm", "build_fragment",
+]

metis/capture/confirm.py

@@ -0,0 +1,46 @@
+"""Confirm, capture the operator's Tier-1 response (descriptive fidelity only).
+
+Allowed responses: confirm / correct / dismiss / defer. A local model may summarise the
+confirmation, but the original response and the human-confirmed summary are both preserved.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict
+
+from ..models.ollama_client import OllamaClient
+from ..models.structured_outputs import AssistPurpose
+from ..validation.tier1 import OperatorResponse
+from .whisper import WhisperPrompt
+
+
+class ConfirmationResult(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    response: OperatorResponse
+    corrected_content: str | None = None
+    free_text: str | None = None
+    summary: str | None = None
+
+
+def operator_confirm(
+    prompt: WhisperPrompt,
+    response: OperatorResponse | str,
+    *,
+    corrected_content: str | None = None,
+    free_text: str | None = None,
+    model_client: OllamaClient | None = None,
+) -> tuple[ConfirmationResult, dict[str, Any] | None]:
+    response = OperatorResponse(response)
+    assist: dict[str, Any] | None = None
+    summary = None
+    if model_client is not None and response in (OperatorResponse.confirm, OperatorResponse.correct):
+        basis = corrected_content or free_text or prompt.question
+        p = f"Summarise this operator confirmation in one sentence. Return JSON {{summary}}. Text: {basis}"
+        res = model_client.run(AssistPurpose.summarise_confirmation, p)
+        summary = res.json().get("summary")
+        assist = {"purpose": AssistPurpose.summarise_confirmation.value, "prompt": p,
+                  "output": res.json(), "used_live_model": res.used_live_model}
+    return ConfirmationResult(response=response, corrected_content=corrected_content,
+                              free_text=free_text, summary=summary), assist

metis/capture/infer.py

@@ -0,0 +1,64 @@
+"""Infer, compare work-as-imagined with work-as-done and form a *candidate hypothesis*.
+
+Deterministic rules come first. A local model may help classify or structure the candidate,
+but the result is only ever a hypothesis (``tacit.inference_candidate``); never trusted
+knowledge. The gap between work-as-imagined and work-as-done is diagnostic, not proof.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from ..models.ollama_client import OllamaClient
+from ..models.structured_outputs import AssistPurpose
+from .observe import Observation
+
+
+class InferenceCandidate(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    candidate_id: str
+    observation_id: str
+    hypothesis: str
+    category: str
+    gap_summary: str
+    conditions: dict[str, Any] = Field(default_factory=dict)
+    confidence: float = 0.3
+    is_hypothesis: bool = True
+
+
+def infer_candidate(
+    observation: Observation,
+    *,
+    candidate_id: str,
+    model_client: OllamaClient | None = None,
+    category: str | None = None,
+) -> tuple[InferenceCandidate, dict[str, Any] | None]:
+    wai, wad = observation.work_as_imagined, observation.work_as_done
+    if wai and wad and wai.strip() != wad.strip():
+        gap = f"Work-as-imagined ('{wai}') diverges from work-as-done ('{wad}')."
+        hypothesis = f"Under the stated conditions, practitioners do: {wad} (rather than: {wai})."
+    else:
+        gap = "No explicit work-as-imagined/work-as-done divergence supplied."
+        hypothesis = observation.text
+
+    assist: dict[str, Any] | None = None
+    if category is None and model_client is not None:
+        prompt = (
+            "Classify the following situated work observation into one K1-K17 tacit category. "
+            "Return JSON {category, rationale}. Observation: " + observation.text)
+        res = model_client.run(AssistPurpose.classify_fragment, prompt)
+        category = res.json().get("category")
+        assist = {"purpose": AssistPurpose.classify_fragment.value, "prompt": prompt,
+                  "output": res.json(), "used_live_model": res.used_live_model}
+    if category is None:
+        # deterministic fallback classification (no model)
+        from ..models.ollama_client import _guess_category
+        category = _guess_category(observation.text)
+
+    candidate = InferenceCandidate(
+        candidate_id=candidate_id, observation_id=observation.observation_id,
+        hypothesis=hypothesis, category=category, gap_summary=gap,
+        conditions=observation.context.model_dump(mode="json", exclude_none=True))
+    return candidate, assist

metis/capture/loop.py

@@ -0,0 +1,191 @@
+"""The Metis operating loop: Observe -> Infer -> Whisper -> Confirm -> Remember.
+
+Each stage is a Metis action emitted as a CHAP event/artefact through the adapter. A
+local model may assist at the Infer/Whisper/Confirm stages; every assisted step is recorded
+as a ModelAssistRecord (provenance, not authority).
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from ..conditions.context import TacitContext
+from ..consent.model import ConsentRecord
+from ..fragment.events import fragment_to_content
+from ..fragment.model import Attribution, FragmentEvidence, TacitFragment
+from ..fragment.store import FragmentStore
+from ..models.ollama_client import OllamaClient
+from ..models.structured_outputs import AssistPurpose, ModelAssistRecord
+from ..taxonomy.categories import SourcePathway
+from ..validation.tier1 import OperatorResponse
+from .confirm import ConfirmationResult, operator_confirm
+from .infer import InferenceCandidate, infer_candidate
+from .observe import Observation, build_observation
+from .remember import build_fragment
+from .whisper import WhisperPrompt, build_whisper
+
+
+@dataclass
+class CaptureResult:
+    observation: Observation
+    candidate: InferenceCandidate
+    whisper: WhisperPrompt
+    confirmation: ConfirmationResult
+    task_id: str
+    fragment: TacitFragment | None = None
+    fragment_artefact: str | None = None
+    model_assist_records: list[ModelAssistRecord] = field(default_factory=list)
+    used_live_model: bool = False
+
+
+class CaptureLoop:
+    def __init__(
+        self,
+        *,
+        adapter,
+        fragment_store: FragmentStore,
+        operator_uri: str,
+        whisperer_uri: str,
+        mission_group_uri: str = "group:mission-group@metis.local",
+        model_client: OllamaClient | None = None,
+        capture_cell: str | None = None,
+        governance=None,
+    ) -> None:
+        self.adapter = adapter
+        self.fragments = fragment_store
+        self.operator_uri = operator_uri
+        self.whisperer_uri = whisperer_uri
+        self.mission_group_uri = mission_group_uri
+        self.model_client = model_client
+        self.capture_cell = capture_cell or adapter.workspace_id
+        self.governance = governance
+        self._frag_seq = 0
+        self._assist_seq = 0
+
+    # ---- model assist recording ------------------------------------------------
+    def _record_assist(self, assist: dict[str, Any], *, task_id: str, produced_by: str,
+                       input_refs: list[str]) -> ModelAssistRecord:
+        self._assist_seq += 1
+        cfg = self.model_client.config if self.model_client else None
+        record = ModelAssistRecord(
+            assist_id=f"MA-{self._assist_seq:04d}",
+            provider=cfg.provider if cfg else "ollama",
+            model_name=cfg.name if cfg else "gemma4",
+            model_url=cfg.url if cfg else "http://localhost:11434",
+            purpose=AssistPurpose(assist["purpose"]),
+            prompt_template=assist["prompt"],
+            input_refs=input_refs,
+            output=assist["output"],
+            used_live_model=assist.get("used_live_model", False),
+            human_review_required=True,
+            human_review_status="pending",
+        )
+        art = self.adapter.append_artefact(
+            "tacit.model_assist_record", produced_by=produced_by,
+            content=record.model_dump(mode="json"), task=task_id)
+        record.chap_artefact_ref = art
+        record.chap_evidence_ref = self.adapter.artefact_evidence.get(art)
+        return record
+
+    # ---- the loop --------------------------------------------------------------
+    def run(
+        self,
+        observation_input: dict[str, Any] | Observation,
+        *,
+        consent: ConsentRecord,
+        response: OperatorResponse | str = OperatorResponse.confirm,
+        corrected_content: str | None = None,
+        free_text: str | None = None,
+        category: str | None = None,
+        conditions: TacitContext | None = None,
+        attribution: Attribution | None = None,
+        evidence: FragmentEvidence | None = None,
+        title: str | None = None,
+        source_pathway: SourcePathway = SourcePathway.exogenous,
+        use_model: bool = True,
+        fragment_id: str | None = None,
+    ) -> CaptureResult:
+        mc = self.model_client if use_model else None
+        assists: list[ModelAssistRecord] = []
+
+        # 1. Observe
+        if isinstance(observation_input, Observation):
+            observation = observation_input
+        else:
+            observation = build_observation(**observation_input)
+        task_id = self.adapter.create_task(
+            "tacit.capture", assignee=self.whisperer_uri, delegator=self.operator_uri,
+            task_input={"observation_id": observation.observation_id})
+        obs_art = self.adapter.append_artefact(
+            "tacit.capture_observation", produced_by=self.operator_uri,
+            content=observation.model_dump(mode="json"), task=task_id)
+
+        # 2. Infer (candidate only)
+        self._frag_seq += 1
+        candidate_id = f"IC-{self._frag_seq:04d}"
+        candidate, infer_assist = infer_candidate(observation, candidate_id=candidate_id,
+                                                  model_client=mc, category=category)
+        cand_art = self.adapter.append_artefact(
+            "tacit.inference_candidate", produced_by=self.whisperer_uri,
+            content=candidate.model_dump(mode="json"), task=task_id, based_on=obs_art)
+        if infer_assist:
+            assists.append(self._record_assist(infer_assist, task_id=task_id,
+                           produced_by=self.whisperer_uri, input_refs=[obs_art]))
+
+        # 3. Whisper (CHAP whisper capability)
+        whisper, whisper_assist = build_whisper(candidate.category, observation, model_client=mc)
+        prompt_art = self.adapter.whisper_ask(
+            sender=self.whisperer_uri, to=self.operator_uri, task_id=task_id,
+            question=whisper.question, options=whisper.options, deadline_ms=60000,
+            default_if_lapsed="defer", urgency="low", category=candidate.category)
+        if whisper_assist:
+            assists.append(self._record_assist(whisper_assist, task_id=task_id,
+                           produced_by=self.whisperer_uri, input_refs=[cand_art]))
+
+        # 4. Confirm (Tier-1, descriptive fidelity)
+        confirmation, confirm_assist = operator_confirm(
+            whisper, response, corrected_content=corrected_content, free_text=free_text, model_client=mc)
+        self.adapter.whisper_answer(
+            sender=self.operator_uri, to=self.whisperer_uri, task_id=task_id,
+            prompt_artefact=prompt_art, response_type=confirmation.response.value,
+            text=confirmation.corrected_content or confirmation.free_text,
+            option_id=confirmation.response.value)
+        self.adapter.append_artefact(
+            "tacit.operator_confirmation", produced_by=self.operator_uri,
+            content=confirmation.model_dump(mode="json"), task=task_id, based_on=prompt_art)
+        if confirm_assist:
+            assists.append(self._record_assist(confirm_assist, task_id=task_id,
+                           produced_by=self.operator_uri, input_refs=[prompt_art]))
+
+        result = CaptureResult(
+            observation=observation, candidate=candidate, whisper=whisper,
+            confirmation=confirmation, task_id=task_id, model_assist_records=assists,
+            used_live_model=any(a.used_live_model for a in assists))
+
+        # 5. Remember (only on confirm/correct)
+        if confirmation.response in (OperatorResponse.confirm, OperatorResponse.correct):
+            fid = fragment_id or f"TF-{self._frag_seq:05d}"
+            fragment = build_fragment(
+                observation, candidate, confirmation, fragment_id=fid,
+                capture_cell=self.capture_cell, operator_uri=self.operator_uri,
+                consent=consent, title=title, conditions=conditions,
+                attribution=attribution, evidence=evidence, source_pathway=source_pathway)
+            # record model-assist provenance (provenance, not authority)
+            if assists:
+                fragment.provenance.model_assist_refs = [a.assist_id for a in assists]
+                fragment.provenance.model_provider = assists[0].provider
+                fragment.provenance.model_name = assists[0].model_name
+                fragment.provenance.model_output_status = "draft_pending_human_review"
+                fragment.provenance.human_review_status = "tier1_confirmed"
+            fragment.provenance.source_artefacts = [obs_art, cand_art, prompt_art]
+            fragment.add_lineage(state=fragment.validation_state.value, by=self.operator_uri,
+                                 note="captured into Evidence layer (Tier-1 confirmed)")
+            frag_art = self.adapter.append_artefact(
+                "tacit.fragment", produced_by=self.operator_uri,
+                content=fragment_to_content(fragment), task=task_id, based_on=cand_art)
+            self.fragments.put(fragment)
+            result.fragment = fragment
+            result.fragment_artefact = frag_art
+            if self.governance is not None:
+                self.governance.register(fid, fragment_artefact=frag_art, task_id=task_id)
+        return result

metis/capture/observe.py

@@ -0,0 +1,43 @@
+"""Observe, accept a structured situated work observation.
+
+Inputs may come from a manual form, a CSV row, a JSON event, or a synthetic example. The
+observation is recorded as a CHAP artefact of kind ``tacit.capture_observation``. Nothing
+here is trusted knowledge; it is raw input to the loop.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from ..conditions.context import TacitContext
+
+
+class Observation(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    observation_id: str
+    text: str
+    work_as_imagined: str | None = None
+    work_as_done: str | None = None
+    context: TacitContext = Field(default_factory=TacitContext)
+    source: str = "manual"  # manual | csv | json | synthetic
+    raw: dict[str, Any] = Field(default_factory=dict)
+
+
+def build_observation(
+    *,
+    observation_id: str,
+    text: str | None = None,
+    work_as_imagined: str | None = None,
+    work_as_done: str | None = None,
+    context: TacitContext | None = None,
+    source: str = "manual",
+    raw: dict[str, Any] | None = None,
+) -> Observation:
+    if text is None:
+        text = work_as_done or work_as_imagined or ""
+    return Observation(
+        observation_id=observation_id, text=text, work_as_imagined=work_as_imagined,
+        work_as_done=work_as_done, context=context or TacitContext(), source=source,
+        raw=raw or {})