vault-graph 0.1.0__py3-none-any.whl

vault_graph/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

vault_graph/answer/__init__.py

@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+from typing import Any
+
+__all__ = [
+    "AnswerClaim",
+    "AnswerDraft",
+    "AnswerEvidence",
+    "AnswerPlan",
+    "AnswerReasoningStep",
+    "AnswerRequest",
+    "AnswerResponse",
+    "AnswerSignal",
+    "AnswerStoreRevision",
+    "AnswerWarning",
+    "CitationGuard",
+    "DefaultAnswerRenderer",
+    "EvidencePlanner",
+    "EvidencePlanStep",
+    "ExtractiveAnswerComposer",
+    "PlannedEvidence",
+    "answer_id_for",
+]
+
+
+def __getattr__(name: str) -> Any:
+    if name in {
+        "AnswerClaim",
+        "AnswerDraft",
+        "AnswerEvidence",
+        "AnswerReasoningStep",
+        "AnswerResponse",
+        "AnswerSignal",
+        "AnswerStoreRevision",
+        "AnswerWarning",
+    }:
+        from vault_graph.answer.answer_response import (
+            AnswerClaim,
+            AnswerDraft,
+            AnswerEvidence,
+            AnswerReasoningStep,
+            AnswerResponse,
+            AnswerSignal,
+            AnswerStoreRevision,
+            AnswerWarning,
+        )
+
+        return {
+            "AnswerClaim": AnswerClaim,
+            "AnswerDraft": AnswerDraft,
+            "AnswerEvidence": AnswerEvidence,
+            "AnswerReasoningStep": AnswerReasoningStep,
+            "AnswerResponse": AnswerResponse,
+            "AnswerSignal": AnswerSignal,
+            "AnswerStoreRevision": AnswerStoreRevision,
+            "AnswerWarning": AnswerWarning,
+        }[name]
+    if name in {"AnswerPlan", "AnswerRequest", "EvidencePlanStep", "PlannedEvidence", "answer_id_for"}:
+        from vault_graph.answer.answer_plan import (
+            AnswerPlan,
+            AnswerRequest,
+            EvidencePlanStep,
+            PlannedEvidence,
+            answer_id_for,
+        )
+
+        return {
+            "AnswerPlan": AnswerPlan,
+            "AnswerRequest": AnswerRequest,
+            "EvidencePlanStep": EvidencePlanStep,
+            "PlannedEvidence": PlannedEvidence,
+            "answer_id_for": answer_id_for,
+        }[name]
+    if name == "CitationGuard":
+        from vault_graph.answer.citation_guard import CitationGuard
+
+        return CitationGuard
+    if name == "DefaultAnswerRenderer":
+        from vault_graph.answer.answer_renderer import DefaultAnswerRenderer
+
+        return DefaultAnswerRenderer
+    if name == "EvidencePlanner":
+        from vault_graph.answer.evidence_planner import EvidencePlanner
+
+        return EvidencePlanner
+    if name == "ExtractiveAnswerComposer":
+        from vault_graph.answer.answer_composer import ExtractiveAnswerComposer
+
+        return ExtractiveAnswerComposer
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

vault_graph/answer/answer_composer.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+from typing import Protocol
+
+from vault_graph.answer.answer_plan import AnswerRequest, PlannedEvidence
+from vault_graph.answer.answer_response import AnswerClaim, AnswerClaimStatus, AnswerDraft, AnswerStatus
+
+
+class AnswerComposer(Protocol):
+    def compose(self, request: AnswerRequest, evidence: PlannedEvidence) -> AnswerDraft: ...
+
+
+class ExtractiveAnswerComposer:
+    def compose(self, request: AnswerRequest, evidence: PlannedEvidence) -> AnswerDraft:
+        if not evidence.evidence:
+            return AnswerDraft(
+                answer="Vault Graph does not have enough indexed evidence to answer this question.",
+                answer_status="insufficient_evidence",
+                claims=(
+                    AnswerClaim(
+                        claim_id="claim-1",
+                        text=f"No indexed evidence directly answers: {request.question.strip()}",
+                        status="missing",
+                        evidence_ids=(),
+                        warnings=(),
+                    ),
+                ),
+                warnings=evidence.warnings,
+                suggested_follow_up="Run vg index for the selected Vault, then retry the question.",
+            )
+
+        claims: list[AnswerClaim] = []
+        for index, item in enumerate(evidence.evidence[:5], start=1):
+            status = _claim_status_for_evidence(item.relationship_status)
+            prefix = "Evidence" if status == "supported" else "Vault Graph found partial evidence"
+            claims.append(
+                AnswerClaim(
+                    claim_id=f"claim-{index}",
+                    text=f"{prefix} from {item.path} indicates: {item.excerpt}",
+                    status=status,
+                    evidence_ids=(item.evidence_id,),
+                    warnings=(),
+                )
+            )
+
+        if any(warning.severity in {"warning", "error"} for warning in evidence.warnings):
+            answer_status: AnswerStatus = "partial"
+            answer = "Vault Graph found partial evidence; review the labeled claims and warnings."
+        elif any(claim.status == "supported" for claim in claims):
+            answer_status = "supported"
+            answer = "Vault Graph found indexed evidence that answers the question."
+        else:
+            answer_status = "partial"
+            answer = "Vault Graph found partial evidence; review the labeled claims and warnings."
+
+        return AnswerDraft(
+            answer=answer,
+            answer_status=answer_status,
+            claims=tuple(claims),
+            warnings=evidence.warnings,
+            suggested_follow_up=(
+                "Review the cited Vault evidence and update durable knowledge through the Vault workflow if needed."
+                if answer_status == "partial"
+                else None
+            ),
+        )
+
+
+def _claim_status_for_evidence(relationship_status: str | None) -> AnswerClaimStatus:
+    if relationship_status == "contested":
+        return "contested"
+    if relationship_status == "deprecated":
+        return "deprecated"
+    if relationship_status == "inferred":
+        return "inferred"
+    return "supported"

vault_graph/answer/answer_plan.py

@@ -0,0 +1,113 @@
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass
+
+from vault_graph.answer.answer_response import (
+    AnswerEvidence,
+    AnswerMode,
+    AnswerReasoningStep,
+    AnswerWarning,
+)
+from vault_graph.errors import AnswerError
+from vault_graph.ingestion.vault_catalog import QueryScope
+
+
+@dataclass(frozen=True)
+class AnswerRequest:
+    question: str
+    requested_scope: QueryScope
+    mode: AnswerMode = "evidence-first"
+    include_graph: bool = False
+    include_cross_vault: bool = False
+    retrieval_limit: int = 10
+    max_evidence_tokens: int = 8000
+
+    def __post_init__(self) -> None:
+        if not self.question.strip():
+            raise AnswerError("question is required")
+        if self.mode != "evidence-first":
+            raise AnswerError(f"unsupported answer mode: {self.mode}")
+        if not 1 <= self.retrieval_limit <= 50:
+            raise AnswerError("retrieval_limit must be between 1 and 50")
+        if not 1000 <= self.max_evidence_tokens <= 24000:
+            raise AnswerError("max_evidence_tokens must be between 1000 and 24000")
+        if self.include_cross_vault and not self.include_graph:
+            raise AnswerError("include_cross_vault requires include_graph")
+        if self.include_cross_vault and len(self.requested_scope.vault_ids) <= 1:
+            raise AnswerError("include_cross_vault requires more than one vault_id")
+        if self.include_cross_vault != self.requested_scope.include_cross_vault:
+            raise AnswerError("requested_scope.include_cross_vault must match include_cross_vault")
+
+
+@dataclass(frozen=True)
+class EvidencePlanStep:
+    step_id: str
+    kind: str
+    query: str
+    required: bool
+    include_graph: bool = False
+    include_cross_vault: bool = False
+    limit: int = 10
+
+    def __post_init__(self) -> None:
+        for field_name in ("step_id", "kind", "query"):
+            if not str(getattr(self, field_name)).strip():
+                raise AnswerError(f"{field_name} is required")
+        if self.limit <= 0:
+            raise AnswerError("plan step limit must be positive")
+
+
+@dataclass(frozen=True)
+class AnswerPlan:
+    request: AnswerRequest
+    steps: tuple[EvidencePlanStep, ...]
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.steps, tuple):
+            raise AnswerError("steps must be an immutable tuple")
+        if not self.steps:
+            raise AnswerError("answer plan requires at least one step")
+
+
+@dataclass(frozen=True)
+class PlannedEvidence:
+    plan: AnswerPlan
+    actual_scopes: tuple[QueryScope, ...]
+    evidence: tuple[AnswerEvidence, ...]
+    reasoning_trace: tuple[AnswerReasoningStep, ...]
+    warnings: tuple[AnswerWarning, ...]
+    dropped_evidence_count: int = 0
+
+    def __post_init__(self) -> None:
+        for field_name in ("actual_scopes", "evidence", "reasoning_trace", "warnings"):
+            if not isinstance(getattr(self, field_name), tuple):
+                raise AnswerError(f"{field_name} must be an immutable tuple")
+        if not self.actual_scopes:
+            raise AnswerError("actual_scopes is required")
+        if self.dropped_evidence_count < 0:
+            raise AnswerError("dropped_evidence_count must not be negative")
+
+
+def answer_id_for(
+    *,
+    question: str,
+    mode: AnswerMode,
+    requested_scope: QueryScope,
+    evidence_ids: tuple[str, ...],
+    generated_at: str,
+) -> str:
+    payload = {
+        "question": " ".join(question.casefold().split()),
+        "mode": mode,
+        "requested_scope": {
+            "vault_ids": list(requested_scope.vault_ids),
+            "content_scopes": list(requested_scope.content_scopes),
+            "include_cross_vault": requested_scope.include_cross_vault,
+        },
+        "evidence_ids": list(evidence_ids),
+        "generated_at": generated_at,
+    }
+    digest = hashlib.sha256(json.dumps(payload, sort_keys=True, separators=(",", ":")).encode("utf-8")).hexdigest()
+    return f"answer:{digest[:24]}"

vault_graph/answer/answer_renderer.py

@@ -0,0 +1,106 @@
+from __future__ import annotations
+
+import dataclasses
+import json
+import math
+from pathlib import Path
+from typing import Protocol
+
+from vault_graph.answer.answer_response import (
+    AnswerClaim,
+    AnswerDraft,
+    AnswerEvidence,
+    AnswerReasoningStep,
+    AnswerResponse,
+    AnswerSignal,
+    AnswerStoreRevision,
+    AnswerWarning,
+)
+from vault_graph.errors import AnswerError
+from vault_graph.ingestion.vault_catalog import QueryScope
+
+_DTO_TYPES = {
+    AnswerClaim,
+    AnswerDraft,
+    AnswerEvidence,
+    AnswerReasoningStep,
+    AnswerResponse,
+    AnswerSignal,
+    AnswerStoreRevision,
+    AnswerWarning,
+}
+
+
+class AnswerRenderer(Protocol):
+    def render_text(self, response: AnswerResponse) -> str: ...
+    def render_json(self, response: AnswerResponse) -> str: ...
+
+
+class DefaultAnswerRenderer:
+    def render_text(self, response: AnswerResponse) -> str:
+        lines = [
+            f"status: {response.answer_status}",
+            "answer:",
+            response.answer,
+            "claims:",
+        ]
+        for claim in response.claims:
+            claim_evidence_ids = ",".join(claim.evidence_ids) if claim.evidence_ids else "none"
+            lines.append(f"- {claim.claim_id} [{claim.status}] {claim.text} (evidence: {claim_evidence_ids})")
+        lines.append("evidence:")
+        for evidence in response.evidence:
+            suffix = evidence.anchor or evidence.section
+            path = f"{evidence.path}#{suffix}" if suffix else evidence.path
+            lines.append(f"- {evidence.evidence_id} [{evidence.vault_id}] {path}")
+        lines.append("warnings:")
+        if response.warnings:
+            for warning in response.warnings:
+                lines.append(f"- {warning.code} [{warning.severity}] {warning.message}")
+        else:
+            lines.append("- none")
+        lines.append("reasoning:")
+        for step in response.reasoning_trace:
+            kept_count = len(step.kept_evidence_ids)
+            lines.append(f"- {step.step_id} {step.service} results={step.result_count} kept={kept_count}")
+        if response.suggested_follow_up:
+            lines.append("follow_up:")
+            lines.append(response.suggested_follow_up)
+        return "\n".join(lines) + "\n"
+
+    def render_json(self, response: AnswerResponse) -> str:
+        return (
+            json.dumps(answer_response_to_dict(response), ensure_ascii=False, sort_keys=True, indent=2, allow_nan=False)
+            + "\n"
+        )
+
+
+def answer_response_to_dict(response: AnswerResponse) -> dict[str, object]:
+    converted = _to_json_value(response)
+    if not isinstance(converted, dict):
+        raise AnswerError("answer response serialization produced a non-object")
+    return converted
+
+
+def _to_json_value(value: object) -> object:
+    if isinstance(value, QueryScope):
+        return {
+            "vault_ids": list(value.vault_ids),
+            "content_scopes": list(value.content_scopes),
+            "include_cross_vault": value.include_cross_vault,
+        }
+    if dataclasses.is_dataclass(value):
+        value_type = type(value)
+        if value_type not in _DTO_TYPES:
+            raise AnswerError(f"unsupported dataclass in answer serialization: {value_type.__name__}")
+        return {field.name: _to_json_value(getattr(value, field.name)) for field in dataclasses.fields(value)}
+    if isinstance(value, tuple):
+        return [_to_json_value(item) for item in value]
+    if isinstance(value, float):
+        if not math.isfinite(value):
+            raise AnswerError("non-finite float values are not supported in answer JSON")
+        return value
+    if isinstance(value, str | int | bool) or value is None:
+        return value
+    if isinstance(value, Path | bytes | bytearray | list | dict | set):
+        raise AnswerError(f"unsupported value in answer serialization: {type(value).__name__}")
+    raise AnswerError(f"unsupported value in answer serialization: {type(value).__name__}")

vault_graph/answer/answer_response.py

@@ -0,0 +1,237 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+from vault_graph.errors import AnswerError
+from vault_graph.ingestion.vault_catalog import QueryScope
+
+AnswerMode = Literal["evidence-first"]
+AnswerStatus = Literal["supported", "partial", "insufficient_evidence"]
+AnswerClaimStatus = Literal[
+    "supported",
+    "inferred",
+    "partial",
+    "unsupported",
+    "missing",
+    "contested",
+    "stale",
+    "deprecated",
+]
+AnswerWarningSeverity = Literal["info", "warning", "error"]
+AnswerEvidenceSourceKind = Literal[
+    "search_result",
+    "graph_related",
+    "decision_trace",
+    "context_pack",
+    "project_memory",
+    "open_question",
+    "recent_change",
+]
+
+_EVIDENCE_REQUIRED_CLAIM_STATUSES = {
+    "supported",
+    "inferred",
+    "partial",
+    "contested",
+    "stale",
+    "deprecated",
+}
+_USABLE_CLAIM_STATUSES = _EVIDENCE_REQUIRED_CLAIM_STATUSES
+
+
+@dataclass(frozen=True)
+class AnswerSignal:
+    kind: str
+    rank: int
+    score: float
+    backend: str
+    index_revision: str
+    explanation: str = ""
+
+    def __post_init__(self) -> None:
+        _require_non_empty(self.kind, "signal kind")
+        _require_non_empty(self.backend, "signal backend")
+        _require_non_empty(self.index_revision, "signal index_revision")
+        if self.rank <= 0:
+            raise AnswerError("signal rank must be positive")
+
+
+@dataclass(frozen=True)
+class AnswerStoreRevision:
+    kind: str
+    revision: str
+    scope_key: str
+    vault_id: str | None = None
+
+    def __post_init__(self) -> None:
+        _require_non_empty(self.kind, "store revision kind")
+        _require_non_empty(self.revision, "store revision")
+        _require_non_empty(self.scope_key, "store revision scope_key")
+
+
+@dataclass(frozen=True)
+class AnswerEvidence:
+    evidence_id: str
+    source_kind: AnswerEvidenceSourceKind
+    result_id: str
+    vault_id: str
+    document_id: str
+    chunk_id: str
+    path: str
+    section: str | None
+    anchor: str | None
+    content_hash: str
+    raw_sha256: str | None
+    metadata_index_revision: str | None
+    vault_revision: str | None
+    excerpt: str
+    retrieval_reason: str
+    relationship_status: str | None
+    signals: tuple[AnswerSignal, ...]
+    store_revisions: tuple[AnswerStoreRevision, ...]
+
+    def __post_init__(self) -> None:
+        for field_name in (
+            "evidence_id",
+            "result_id",
+            "vault_id",
+            "document_id",
+            "chunk_id",
+            "path",
+            "content_hash",
+            "retrieval_reason",
+        ):
+            _require_non_empty(getattr(self, field_name), field_name)
+        _require_tuple(self.signals, "signals")
+        _require_tuple(self.store_revisions, "store_revisions")
+
+
+@dataclass(frozen=True)
+class AnswerWarning:
+    code: str
+    message: str
+    severity: AnswerWarningSeverity
+    affected_vault_ids: tuple[str, ...]
+    recovery_hint: str | None = None
+    evidence_ids: tuple[str, ...] = ()
+
+    def __post_init__(self) -> None:
+        _require_non_empty(self.code, "warning code")
+        _require_non_empty(self.message, "warning message")
+        _require_tuple(self.affected_vault_ids, "affected_vault_ids")
+        if not self.affected_vault_ids:
+            raise AnswerError("affected_vault_ids is required")
+        _require_tuple(self.evidence_ids, "warning evidence_ids")
+
+
+@dataclass(frozen=True)
+class AnswerClaim:
+    claim_id: str
+    text: str
+    status: AnswerClaimStatus
+    evidence_ids: tuple[str, ...]
+    warnings: tuple[AnswerWarning, ...]
+
+    def __post_init__(self) -> None:
+        _require_non_empty(self.claim_id, "claim_id")
+        _require_non_empty(self.text, "claim text")
+        _require_tuple(self.evidence_ids, "claim evidence_ids")
+        _require_tuple(self.warnings, "claim warnings")
+        if self.status in _EVIDENCE_REQUIRED_CLAIM_STATUSES and not self.evidence_ids:
+            raise AnswerError("claim evidence is required for cited claim statuses")
+
+
+@dataclass(frozen=True)
+class AnswerReasoningStep:
+    step_id: str
+    kind: str
+    service: str
+    status: str
+    query: str
+    result_count: int
+    kept_evidence_ids: tuple[str, ...]
+    dropped_count: int
+    warning_codes: tuple[str, ...]
+
+    def __post_init__(self) -> None:
+        for field_name in ("step_id", "kind", "service", "status", "query"):
+            _require_non_empty(getattr(self, field_name), field_name)
+        if self.result_count < 0:
+            raise AnswerError("result_count must not be negative")
+        if self.dropped_count < 0:
+            raise AnswerError("dropped_count must not be negative")
+        _require_tuple(self.kept_evidence_ids, "kept_evidence_ids")
+        _require_tuple(self.warning_codes, "warning_codes")
+
+
+@dataclass(frozen=True)
+class AnswerDraft:
+    answer: str
+    answer_status: AnswerStatus
+    claims: tuple[AnswerClaim, ...]
+    warnings: tuple[AnswerWarning, ...]
+    suggested_follow_up: str | None
+
+    def __post_init__(self) -> None:
+        _require_non_empty(self.answer, "answer")
+        _require_tuple(self.claims, "claims")
+        _require_tuple(self.warnings, "warnings")
+
+
+@dataclass(frozen=True)
+class AnswerResponse:
+    answer_id: str
+    question: str
+    requested_scope: QueryScope
+    actual_scopes: tuple[QueryScope, ...]
+    answer: str
+    answer_status: AnswerStatus
+    claims: tuple[AnswerClaim, ...]
+    evidence: tuple[AnswerEvidence, ...]
+    reasoning_trace: tuple[AnswerReasoningStep, ...]
+    warnings: tuple[AnswerWarning, ...]
+    suggested_follow_up: str | None
+    generated_at: str
+
+    def __post_init__(self) -> None:
+        _require_non_empty(self.answer_id, "answer_id")
+        _require_non_empty(self.question, "question")
+        _require_non_empty(self.answer, "answer")
+        _require_non_empty(self.generated_at, "generated_at")
+        _require_tuple(self.actual_scopes, "actual_scopes")
+        if not self.actual_scopes:
+            raise AnswerError("actual_scopes is required")
+        _require_tuple(self.claims, "claims")
+        _require_tuple(self.evidence, "evidence")
+        _require_tuple(self.reasoning_trace, "reasoning_trace")
+        _require_tuple(self.warnings, "warnings")
+        evidence_ids = _unique_ids(tuple(item.evidence_id for item in self.evidence), "evidence_id")
+        _unique_ids(tuple(claim.claim_id for claim in self.claims), "claim_id")
+        for claim in self.claims:
+            for evidence_id in claim.evidence_ids:
+                if evidence_id not in evidence_ids:
+                    raise AnswerError(f"unknown evidence_id for claim: {evidence_id}")
+        if self.answer_status == "supported":
+            if not any(claim.status == "supported" for claim in self.claims):
+                raise AnswerError("supported answer requires at least one supported claim")
+
+
+def _require_non_empty(value: str, field_name: str) -> None:
+    if not value.strip():
+        raise AnswerError(f"{field_name} is required")
+
+
+def _require_tuple(value: object, field_name: str) -> None:
+    if not isinstance(value, tuple):
+        raise AnswerError(f"{field_name} must be an immutable tuple")
+
+
+def _unique_ids(values: tuple[str, ...], field_name: str) -> set[str]:
+    seen: set[str] = set()
+    for value in values:
+        _require_non_empty(value, field_name)
+        if value in seen:
+            raise AnswerError(f"duplicate {field_name}: {value}")
+        seen.add(value)
+    return seen

vault_graph/answer/citation_guard.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+from dataclasses import replace
+
+from vault_graph.answer.answer_response import AnswerResponse
+from vault_graph.errors import AnswerError
+
+_USABLE_STATUSES = {"supported", "inferred", "partial", "contested", "stale", "deprecated"}
+
+
+class CitationGuard:
+    def validate(self, response: AnswerResponse) -> AnswerResponse:
+        evidence_ids = _unique(tuple(evidence.evidence_id for evidence in response.evidence), "evidence_id")
+        _unique(tuple(claim.claim_id for claim in response.claims), "claim_id")
+        for claim in response.claims:
+            if claim.status in _USABLE_STATUSES and not claim.evidence_ids:
+                raise AnswerError("claim evidence is required for cited claim statuses")
+            for evidence_id in claim.evidence_ids:
+                if evidence_id not in evidence_ids:
+                    raise AnswerError(f"unknown evidence_id for claim: {evidence_id}")
+
+        usable_claims = tuple(claim for claim in response.claims if claim.status in _USABLE_STATUSES)
+        if not usable_claims:
+            return replace(response, answer_status="insufficient_evidence")
+        if response.answer_status == "supported" and any(warning.severity == "error" for warning in response.warnings):
+            return replace(response, answer_status="partial")
+        return response
+
+
+def _unique(values: tuple[str, ...], field_name: str) -> set[str]:
+    seen: set[str] = set()
+    for value in values:
+        if value in seen:
+            raise AnswerError(f"duplicate {field_name}: {value}")
+        seen.add(value)
+    return seen