tracecite 0.1.0__py3-none-any.whl

tracecite/__init__.py

@@ -0,0 +1,137 @@
+"""TraceCite: an extensible evidence runtime for AI agents."""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+from .runtime import (
+    AgentResult,
+    BUDGET_POLICY_SCHEMA_VERSION,
+    BudgetExhausted,
+    BudgetPolicy,
+    BudgetReservation,
+    EvidencePointer,
+    FINDING_OUTCOMES,
+    HYPOTHESIS_STATUSES,
+    INVESTIGATION_SCHEMA_VERSION,
+    INVESTIGATION_STATUSES,
+    STOP_KINDS,
+    InvestigationError,
+    InvestigationCacheStore,
+    InvestigationCompareError,
+    InvestigationCompareLimits,
+    InvestigationState,
+    InvestigationStore,
+    InvestigationSummaryError,
+    RESULT_OUTCOMES,
+    RESULT_SCHEMA_VERSION,
+    SCENARIO_SCHEMA_VERSION,
+    ScenarioDocument,
+    ScenarioError,
+    ScenarioProfile,
+    ScenarioRuntime,
+    SUMMARY_SCHEMA_VERSION,
+    COMPARE_SCHEMA_VERSION,
+    TIMELINE_SCHEMA_VERSION,
+    SummaryLimits,
+    expand,
+    attach_investigation_result,
+    create_investigation,
+    load_investigation,
+    investigation_summary,
+    propose_candidate,
+    propose_knowledge_candidate,
+    peek,
+    probe,
+    run,
+    sample,
+    search,
+    survey,
+    summarize_investigation,
+    compare_investigation,
+    compare_investigations,
+    investigation_timeline,
+    timeline_investigation,
+    verify,
+)
+from .knowledge import (
+    GovernancePolicy,
+    KnowledgeCandidate,
+    KnowledgeGovernanceError,
+    KnowledgeGovernanceStore,
+    KnowledgeValidity,
+    KnowledgeVerification,
+    VALIDITY_STATES,
+)
+from .output_layout import (
+    DEFAULT_OUTPUT_ROOT,
+    OutputLayout,
+    USER_OUTPUT_CONFIG_PATH,
+    deep_merge,
+    load_output_config,
+    write_output_config,
+)
+
+__all__ = [
+    "AgentResult",
+    "BUDGET_POLICY_SCHEMA_VERSION",
+    "BudgetExhausted",
+    "BudgetPolicy",
+    "BudgetReservation",
+    "InvestigationCacheStore",
+    "InvestigationCompareError",
+    "InvestigationCompareLimits",
+    "EvidencePointer",
+    "FINDING_OUTCOMES",
+    "HYPOTHESIS_STATUSES",
+    "INVESTIGATION_SCHEMA_VERSION",
+    "INVESTIGATION_STATUSES",
+    "STOP_KINDS",
+    "InvestigationError",
+    "InvestigationState",
+    "InvestigationStore",
+    "InvestigationSummaryError",
+    "RESULT_OUTCOMES",
+    "RESULT_SCHEMA_VERSION",
+    "SCENARIO_SCHEMA_VERSION",
+    "ScenarioDocument",
+    "ScenarioError",
+    "ScenarioProfile",
+    "ScenarioRuntime",
+    "SUMMARY_SCHEMA_VERSION",
+    "COMPARE_SCHEMA_VERSION",
+    "TIMELINE_SCHEMA_VERSION",
+    "SummaryLimits",
+    "GovernancePolicy",
+    "KnowledgeCandidate",
+    "KnowledgeGovernanceError",
+    "KnowledgeGovernanceStore",
+    "KnowledgeValidity",
+    "KnowledgeVerification",
+    "VALIDITY_STATES",
+    "DEFAULT_OUTPUT_ROOT",
+    "OutputLayout",
+    "USER_OUTPUT_CONFIG_PATH",
+    "deep_merge",
+    "load_output_config",
+    "write_output_config",
+    "probe",
+    "sample",
+    "peek",
+    "search",
+    "survey",
+    "expand",
+    "attach_investigation_result",
+    "create_investigation",
+    "load_investigation",
+    "investigation_summary",
+    "propose_candidate",
+    "propose_knowledge_candidate",
+    "summarize_investigation",
+    "compare_investigation",
+    "compare_investigations",
+    "investigation_timeline",
+    "timeline_investigation",
+    "verify",
+    "run",
+]

tracecite/core/__init__.py

@@ -0,0 +1,7 @@
+"""Public Core compatibility surface under the main :mod:`tracecite` package."""
+
+from tracecite_core import *  # noqa: F401,F403
+from tracecite_core import __version__
+from tracecite_core import __all__ as _CORE_ALL
+
+__all__ = [*_CORE_ALL, "__version__"]

tracecite/extension/__init__.py

@@ -0,0 +1,104 @@
+"""Versioned extension contract for third-party TraceCite capabilities.
+
+Extensions contribute capability registrations and domain semantics. Runtime
+continues to own execution, evidence schemas, verification, budgets, and safety
+gates. Entry-point loading is explicit; importing :mod:`tracecite` never runs
+third-party registration code.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional
+
+from tracecite_core.plugin_sdk import PluginAPI, load_entrypoint_plugins, loaded_plugins
+
+from tracecite.runtime.assertions import register_assertion_type
+from tracecite.runtime.reporting import register_report_outputter
+from tracecite.runtime.runtime import DEFAULT_RUNTIME, ScenarioRuntime
+
+
+EXTENSION_API_VERSION = "1"
+_RUNTIMES: Dict[str, ScenarioRuntime] = {"default": DEFAULT_RUNTIME}
+
+
+class ExtensionError(RuntimeError):
+    """An extension registration or lookup failed."""
+
+
+def register_runtime(
+    name: str,
+    runtime: ScenarioRuntime,
+    *,
+    replace: bool = False,
+) -> None:
+    """Register a named domain runtime without changing TraceCite source."""
+    key = str(name).strip().lower()
+    if not key:
+        raise ExtensionError("runtime 名不能为空")
+    if not isinstance(runtime, ScenarioRuntime):
+        raise ExtensionError("runtime 必须是 ScenarioRuntime")
+    current = _RUNTIMES.get(key)
+    if current is not None and current is not runtime and not replace:
+        raise ExtensionError(f"runtime {key!r} 已注册")
+    _RUNTIMES[key] = runtime
+
+
+def get_runtime(name: str = "default") -> ScenarioRuntime:
+    key = str(name).strip().lower() or "default"
+    try:
+        return _RUNTIMES[key]
+    except KeyError as exc:
+        known = ", ".join(available_runtimes())
+        raise ExtensionError(f"未知 runtime {key!r}（可用: {known}）") from exc
+
+
+def available_runtimes() -> List[str]:
+    return sorted(_RUNTIMES)
+
+
+@dataclass(frozen=True)
+class ExtensionAPI(PluginAPI):
+    """Stable registration surface passed to installed domain extensions."""
+
+    version: str = EXTENSION_API_VERSION
+
+    def register_assertion_type(
+        self, name: str, evaluator: Any, *, replace: bool = False
+    ) -> None:
+        register_assertion_type(name, evaluator, replace=replace)
+
+    def register_report_outputter(
+        self, name: str, outputter: Any, *, replace: bool = False
+    ) -> None:
+        register_report_outputter(name, outputter, replace=replace)
+
+    def register_runtime(
+        self, name: str, runtime: ScenarioRuntime, *, replace: bool = False
+    ) -> None:
+        register_runtime(name, runtime, replace=replace)
+
+
+def load_extensions(*, strict: bool = True) -> List[Dict[str, Optional[str]]]:
+    """Explicitly discover installed Core and Runtime extensions."""
+    return [
+        *load_entrypoint_plugins(group="tracecite.core.plugins", strict=strict),
+        *load_entrypoint_plugins(
+            group="tracecite.extensions",
+            strict=strict,
+            api=ExtensionAPI(),
+            version_attribute="TRACECITE_EXTENSION_API",
+        ),
+    ]
+
+
+__all__ = [
+    "EXTENSION_API_VERSION",
+    "ExtensionAPI",
+    "ExtensionError",
+    "register_runtime",
+    "get_runtime",
+    "available_runtimes",
+    "load_extensions",
+    "loaded_plugins",
+]

tracecite/integrations/__init__.py

@@ -0,0 +1,3 @@
+"""Adapters exposing TraceCite Runtime to external Agent hosts."""
+
+__all__: list[str] = []

tracecite/integrations/agent_profile.py

@@ -0,0 +1,195 @@
+"""Capability-selected, lossless Agent transport profiles.
+
+Profiles are integration-only views over canonical Runtime Results. They never
+change evidence, artifacts, or Runtime schemas; an unsupported capability
+falls back to a portable JSON profile rather than silently dropping evidence.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Literal, Mapping
+
+
+TransportFormat = Literal["canonical-json", "columnar-json", "frame"]
+
+
+@dataclass(frozen=True)
+class AgentCapabilities:
+    """Capabilities declared by one selected Agent host, not a model name."""
+
+    stateful_history: bool = False
+    batch_expand: bool = True
+    text_frame: bool = False
+    strict_json: bool = False
+
+
+@dataclass(frozen=True)
+class AgentProfile:
+    """Token transport policy for one selected analysis Agent."""
+
+    name: str
+    transport: TransportFormat
+    requires_ledger: bool = False
+    compact_history: bool = False
+    requires: AgentCapabilities = AgentCapabilities()
+
+    def supports(self, capabilities: AgentCapabilities) -> bool:
+        return all(
+            not required or available
+            for required, available in (
+                (self.requires.stateful_history, capabilities.stateful_history),
+                (self.requires.batch_expand, capabilities.batch_expand),
+                (self.requires.text_frame, capabilities.text_frame),
+                (self.requires.strict_json, capabilities.strict_json),
+            )
+        )
+
+
+_PROFILES: dict[str, AgentProfile] = {
+    "canonical": AgentProfile("canonical", "canonical-json"),
+    "agent": AgentProfile("agent", "columnar-json"),
+    "portable-json": AgentProfile("portable-json", "columnar-json"),
+    "strict-json": AgentProfile(
+        "strict-json",
+        "columnar-json",
+        requires=AgentCapabilities(strict_json=True),
+    ),
+    "stateful-index": AgentProfile(
+        "stateful-index",
+        "columnar-json",
+        requires_ledger=True,
+        compact_history=True,
+        requires=AgentCapabilities(stateful_history=True, batch_expand=True),
+    ),
+    "frame": AgentProfile(
+        "frame",
+        "frame",
+        requires_ledger=True,
+        compact_history=True,
+        requires=AgentCapabilities(
+            stateful_history=True,
+            batch_expand=True,
+            text_frame=True,
+        ),
+    ),
+}
+
+
+def profile_names() -> tuple[str, ...]:
+    """Return stable built-in profile names for host configuration."""
+
+    return tuple(_PROFILES)
+
+
+def get_agent_profile(name: str) -> AgentProfile:
+    """Return a named built-in profile or fail with valid choices."""
+
+    try:
+        return _PROFILES[name]
+    except KeyError as exc:
+        choices = ", ".join(profile_names())
+        raise ValueError(f"unknown agent profile {name!r}; choose one of: {choices}") from exc
+
+
+def select_agent_profile(
+    name: str,
+    capabilities: AgentCapabilities | None = None,
+) -> AgentProfile:
+    """Resolve ``auto`` safely or validate an explicitly selected profile."""
+
+    available = capabilities or AgentCapabilities()
+    if name == "auto":
+        if _PROFILES["stateful-index"].supports(available):
+            return _PROFILES["stateful-index"]
+        return _PROFILES["agent"]
+    if name == "portable-json":
+        return _PROFILES["portable-json"]
+    if name == "agent":
+        return _PROFILES["agent"]
+    profile = get_agent_profile(name)
+    if not profile.supports(available):
+        raise ValueError(
+            f"agent profile {name!r} requires capabilities not declared by this host"
+        )
+    return profile
+
+
+def _clean_cell(value: Any) -> str:
+    return str(value if value is not None else "").replace("\t", " ").replace("\n", " ")
+
+
+def render_frame(payload: Mapping[str, Any]) -> str:
+    """Render a compact search or expand-many view as a readable TCF frame.
+
+    The frame is a transport encoding, not a new canonical schema. It carries
+    the same columnar rows and Coverage as the JSON view, and can always fall
+    back to JSON for hosts that do not declare ``text_frame`` support.
+    """
+
+    operation = str(payload.get("operation") or "unknown")
+    status = str(payload.get("status") or "error")
+    outcome = str(payload.get("outcome") or "unknown")
+    lines = [f"@TCF 1 {operation} status={status} outcome={outcome}"]
+    result_id = str((payload.get("data") or {}).get("result_id") or payload.get("result_id") or "")
+    if result_id:
+        lines.append(f"@R {result_id}")
+
+    source = (payload.get("data") or {}).get("evidence_source") or {}
+    if isinstance(source, Mapping) and source.get("uri_base"):
+        lines.append(f"@SRC {_clean_cell(source['uri_base'])}")
+
+    coverage = payload.get("coverage") or {}
+    if isinstance(coverage, Mapping):
+        scalar_coverage = [
+            f"{key}={_clean_cell(value)}"
+            for key, value in sorted(coverage.items())
+            if not isinstance(value, (list, dict))
+        ]
+        if scalar_coverage:
+            lines.append("@COV " + " ".join(scalar_coverage))
+
+    evidence = payload.get("evidence") or {}
+    if isinstance(evidence, Mapping):
+        columns = evidence.get("columns") or []
+        rows = evidence.get("rows") or []
+        if columns:
+            lines.append("@E " + "\t".join(_clean_cell(column) for column in columns))
+            for row in rows:
+                if isinstance(row, list):
+                    lines.append("\t".join(_clean_cell(cell) for cell in row))
+
+    contexts = payload.get("contexts") or []
+    if isinstance(contexts, list):
+        for context in contexts:
+            if not isinstance(context, Mapping):
+                continue
+            context_id = _clean_cell(context.get("id"))
+            context_lines = context.get("lines") or []
+            start = _clean_cell(context_lines[0] if len(context_lines) > 0 else "")
+            end = _clean_cell(context_lines[1] if len(context_lines) > 1 else "")
+            truncated = _clean_cell(context.get("truncated", False))
+            lines.append(f"@CTX {context_id} {start}-{end} truncated={truncated}")
+            lines.extend(str(context.get("text") or "").splitlines())
+            lines.append("@ENDCTX")
+
+    warnings = payload.get("warnings") or []
+    for warning in warnings:
+        lines.append("@WARN " + _clean_cell(warning))
+    error = payload.get("error") or {}
+    if isinstance(error, Mapping):
+        message = error.get("message")
+        if message:
+            lines.append("@ERR " + _clean_cell(message))
+    return "\n".join(lines)
+
+
+__all__ = [
+    "AgentCapabilities",
+    "AgentProfile",
+    "TransportFormat",
+    "get_agent_profile",
+    "profile_names",
+    "render_frame",
+    "select_agent_profile",
+]

tracecite/integrations/agent_projection.py

@@ -0,0 +1,173 @@
+"""Shared agent-facing projections over canonical tool results."""
+
+from __future__ import annotations
+
+import copy
+import json
+from typing import Any, Mapping
+
+DEFAULT_AGENT_MAX_OUTPUT_CHARS = 12_000
+DEFAULT_FILTER_MAX_LINE_CHARS = 1024
+DEFAULT_AGENT_MAX_EVIDENCE = 30
+
+
+def encoded_json(payload: Any) -> str:
+    return json.dumps(
+        payload,
+        ensure_ascii=False,
+        sort_keys=True,
+        separators=(",", ":"),
+    )
+
+
+def dedupe_survey_coverage(coverage: Mapping[str, Any]) -> dict[str, Any]:
+    """Collapse synonymous survey coverage keys for agent transport."""
+
+    aliases = {
+        "scanned_lines": "lines_scanned",
+        "scanned_records": "records_scanned",
+        "records_scoped": "scoped_records",
+        "lines_scoped": "scoped_lines",
+    }
+    deduped: dict[str, Any] = {}
+    for key, value in coverage.items():
+        canonical = aliases.get(key, key)
+        if canonical not in deduped:
+            deduped[canonical] = value
+    return deduped
+
+
+def apply_survey_brief(payload: Mapping[str, Any]) -> dict[str, Any]:
+    """Project a canonical survey Result into a token-efficient agent view."""
+
+    result = copy.deepcopy(dict(payload))
+    if result.get("operation") != "survey":
+        return result
+
+    data = dict(result.get("data") or {})
+    data["brief"] = True
+    for template in data.get("top_templates") or []:
+        if not isinstance(template, Mapping):
+            continue
+        for sample in template.get("samples") or []:
+            if isinstance(sample, Mapping):
+                sample.pop("text", None)
+    for key in ("work_input", "snapshot_path"):
+        data.pop(key, None)
+    result["data"] = data
+
+    evidence = []
+    for item in result.get("evidence") or []:
+        if not isinstance(item, Mapping):
+            continue
+        row = dict(item)
+        metadata = dict(row.get("metadata") or {})
+        metadata.pop("text", None)
+        if metadata:
+            row["metadata"] = metadata
+        else:
+            row.pop("metadata", None)
+        label = str(row.get("label") or "")
+        if label:
+            row["label"] = label[:80]
+        evidence.append(row)
+    result["evidence"] = evidence
+    result["coverage"] = dedupe_survey_coverage(result.get("coverage") or {})
+    return result
+
+
+def dedupe_evidence_labels(
+    evidence_rows: list[list[Any]],
+    *,
+    label_index: int,
+    coverage: dict[str, Any],
+) -> None:
+    """Hoist or omit repeated search labels inside compact evidence rows."""
+
+    labels = [
+        str(row[label_index])
+        for row in evidence_rows
+        if label_index < len(row) and row[label_index]
+    ]
+    if not labels:
+        return
+    unique = set(labels)
+    if len(unique) == 1:
+        coverage["shared_label"] = labels[0]
+        for row in evidence_rows:
+            if label_index < len(row):
+                row[label_index] = ""
+        return
+    previous = None
+    for row in evidence_rows:
+        if label_index >= len(row):
+            continue
+        current = row[label_index]
+        if current and current == previous:
+            row[label_index] = ""
+        elif current:
+            previous = current
+
+
+def lightweight_result(payload: Mapping[str, Any]) -> dict[str, Any]:
+    """Drop empty investigation envelope fields from agent transport."""
+
+    result = copy.deepcopy(dict(payload))
+    for key in ("hypotheses", "verification"):
+        if not result.get(key):
+            result.pop(key, None)
+    artifacts = result.get("artifacts") or []
+    if not artifacts:
+        result.pop("artifacts", None)
+    data = dict(result.get("data") or {})
+    for key in ("run_id", "manifest_path", "manifest_sha256", "input_lineage"):
+        data.pop(key, None)
+    if data:
+        result["data"] = data
+    else:
+        result.pop("data", None)
+    return result
+
+
+def compact_filter_payload(payload: Mapping[str, Any]) -> dict[str, Any]:
+    """Return a bounded mobile filter view; full text stays in records_path."""
+
+    source = dict(payload)
+    keep = (
+        "match_records",
+        "match_lines",
+        "scope",
+        "time_from",
+        "time_to",
+        "tag",
+        "pattern",
+        "records_path",
+        "hits_path",
+        "templates_path",
+        "unmatched_summary",
+        "term_usage",
+        "lines_truncated",
+        "max_line_chars",
+    )
+    view = {key: source[key] for key in keep if key in source and source[key] is not None}
+    view["view"] = "agent"
+    view["recovery"] = (
+        "Do not Read output_path directly. Use records_path with "
+        "tracecite-core search --compact or expand for full lines."
+    )
+    if source.get("output_path"):
+        view["output_path"] = source["output_path"]
+    return view
+
+
+__all__ = [
+    "DEFAULT_AGENT_MAX_EVIDENCE",
+    "DEFAULT_AGENT_MAX_OUTPUT_CHARS",
+    "DEFAULT_FILTER_MAX_LINE_CHARS",
+    "apply_survey_brief",
+    "compact_filter_payload",
+    "dedupe_evidence_labels",
+    "dedupe_survey_coverage",
+    "encoded_json",
+    "lightweight_result",
+]