192 行
12 KiB
Python
192 行
12 KiB
Python
# -*- coding: utf-8 -*-
|
|
"""P3 versioned, metadata-only request context contract."""
|
|
from __future__ import annotations
|
|
|
|
import hashlib
|
|
import json
|
|
import re
|
|
from copy import deepcopy
|
|
from datetime import datetime, timezone
|
|
from typing import Any
|
|
|
|
CONTRACT_NAME = "ops.context_orchestration.v1"
|
|
CONTRACT_VERSION = "1.0"
|
|
ATTRIBUTE_NAME = "_ops_context_orchestration_v1"
|
|
LAYERS = ("persona", "runtime", "person", "scene", "memory", "safety")
|
|
PHASES = ("initialized", "companion_ready", "memory_ready", "safety_ready", "finalized", "invalid")
|
|
SECURITY_STATUSES = ("allowed", "sanitized", "blocked", "quarantined", "unavailable")
|
|
POLICIES = ("inherit", "allow", "deny", "quarantine")
|
|
TRUST_LEVELS = ("T0", "T1", "T2", "T3", "T4")
|
|
CONTEXT_INIT, COMPANION_CONTEXT, TTS_FALLBACK, MEMORY_CONTEXT = 100, 0, -10, -20
|
|
INCOMPATIBLE_TOOL, SENSITIVE_TOOL, FINALIZE = -20000, -21000, -22000
|
|
MAX_FRAGMENTS, MAX_ERRORS, MAX_REASON_CODES = 64, 16, 16
|
|
_FRAGMENT_FIELDS = ("key", "layer", "source", "trust_level", "content_hash", "chars", "status")
|
|
_CORE = ("persona", "runtime", "person", "scene")
|
|
_STATE_FIELDS = {"contract_name", "contract_version", "contract_fingerprint", "request_id", "session_id", "scope", "created_at", "phase", "completed_layers", "fragments", "security", "errors", "finalized"}
|
|
_SECURITY_FIELDS = {"status", "event_id", "memory_policy", "tool_policy", "response_policy", "reason_codes"}
|
|
_CODE_RE = re.compile(r"^[a-z0-9][a-z0-9_.:-]{0,119}$")
|
|
|
|
|
|
def _json(value: Any) -> str:
|
|
return json.dumps(value, ensure_ascii=False, sort_keys=True, separators=(",", ":"))
|
|
|
|
|
|
def contract_descriptor(*, fixture_version: str = "1") -> dict[str, Any]:
|
|
return {"contract_name": CONTRACT_NAME, "contract_version": CONTRACT_VERSION, "attribute_name": ATTRIBUTE_NAME, "fixture_version": str(fixture_version), "layers": list(LAYERS), "phases": list(PHASES), "security_statuses": list(SECURITY_STATUSES), "policies": list(POLICIES), "trust_levels": list(TRUST_LEVELS), "state_fields": ["contract_name", "contract_version", "contract_fingerprint", "request_id", "session_id", "scope", "created_at", "phase", "completed_layers", "fragments", "security", "errors", "finalized"], "security_fields": ["status", "event_id", "memory_policy", "tool_policy", "response_policy", "reason_codes"], "fragment_fields": list(_FRAGMENT_FIELDS), "limits": {"fragments": MAX_FRAGMENTS, "errors": MAX_ERRORS, "reason_codes": MAX_REASON_CODES}}
|
|
|
|
|
|
def contract_fingerprint(*, fixture_version: str = "1") -> str:
|
|
return hashlib.sha256(_json(contract_descriptor(fixture_version=fixture_version)).encode("utf-8")).hexdigest()
|
|
|
|
|
|
def _text(value: Any, limit: int = 240) -> str:
|
|
return str(value or "").replace("\r", " ").replace("\n", " ").strip()[:limit]
|
|
|
|
|
|
def _utc_timestamp(value: Any = None) -> str:
|
|
if value is None:
|
|
return datetime.now(timezone.utc).isoformat(timespec="milliseconds").replace("+00:00", "Z")
|
|
if not isinstance(value, str) or value != value.strip() or "T" not in value or not value.endswith("Z"):
|
|
return ""
|
|
try:
|
|
datetime.fromisoformat(value[:-1] + "+00:00")
|
|
except ValueError:
|
|
return ""
|
|
return value
|
|
|
|
|
|
def _security() -> dict[str, Any]:
|
|
return {"status": "allowed", "event_id": "", "memory_policy": "inherit", "tool_policy": "inherit", "response_policy": "inherit", "reason_codes": []}
|
|
|
|
|
|
def new_context_state(*, request_id: Any = "", session_id: Any = "", scope: Any = "unknown", created_at: Any = None, fixture_version: str = "1") -> dict[str, Any]:
|
|
return {"contract_name": CONTRACT_NAME, "contract_version": CONTRACT_VERSION, "contract_fingerprint": contract_fingerprint(fixture_version=fixture_version), "request_id": _text(request_id, 180), "session_id": _text(session_id), "scope": _text(scope, 80) or "unknown", "created_at": _utc_timestamp(created_at), "phase": "initialized", "completed_layers": [], "fragments": [], "security": _security(), "errors": [], "finalized": False}
|
|
|
|
|
|
def _error(state: dict[str, Any], code: str) -> None:
|
|
errors = state.setdefault("errors", [])
|
|
if isinstance(errors, list) and code not in errors and len(errors) < MAX_ERRORS:
|
|
errors.append(code)
|
|
|
|
|
|
def _invalid(state: dict[str, Any], code: str) -> dict[str, Any]:
|
|
_error(state, code); state["phase"] = "invalid"; state["finalized"] = False
|
|
return state
|
|
|
|
|
|
def consume_context_state(value: Any, *, fixture_version: str = "1") -> dict[str, Any] | None:
|
|
if not isinstance(value, dict): return None
|
|
state = value
|
|
if state.get("contract_name") != CONTRACT_NAME or state.get("contract_version") != CONTRACT_VERSION: return _invalid(state, "contract_mismatch")
|
|
if state.get("contract_fingerprint") != contract_fingerprint(fixture_version=fixture_version): return _invalid(state, "fingerprint_mismatch")
|
|
if set(state) != _STATE_FIELDS or state.get("phase") not in PHASES or not isinstance(state.get("finalized"), bool): return _invalid(state, "state_invalid")
|
|
if not isinstance(state.get("created_at"), str) or not state["created_at"] or _utc_timestamp(state["created_at"]) != state["created_at"]: return _invalid(state, "created_at_invalid")
|
|
completed = state.get("completed_layers")
|
|
if not isinstance(completed, list): return _invalid(state, "state_invalid")
|
|
if any(layer not in LAYERS for layer in completed) or len(completed) != len(set(completed)) or completed != sorted(completed, key=LAYERS.index): return _invalid(state, "completed_layers_invalid")
|
|
if state["finalized"] != (state["phase"] == "finalized"): return _invalid(state, "finalized_phase_invalid")
|
|
if state["finalized"] and set(completed) != set(LAYERS): return _invalid(state, "finalized_layers_invalid")
|
|
if not isinstance(state.get("fragments"), list) or len(state["fragments"]) > MAX_FRAGMENTS: return _invalid(state, "fragments_invalid")
|
|
for fragment in state["fragments"]:
|
|
if not isinstance(fragment, dict) or set(fragment) != set(_FRAGMENT_FIELDS) or fragment.get("layer") not in LAYERS or fragment.get("trust_level") not in TRUST_LEVELS: return _invalid(state, "fragment_invalid")
|
|
security = state.get("security")
|
|
if not isinstance(security, dict) or set(security) != _SECURITY_FIELDS or security.get("status") not in SECURITY_STATUSES or any(security.get(key) not in POLICIES for key in ("memory_policy", "tool_policy", "response_policy")): return _invalid(state, "security_invalid")
|
|
errors = state.get("errors")
|
|
reason_codes = security.get("reason_codes")
|
|
if not isinstance(reason_codes, list) or len(reason_codes) > MAX_REASON_CODES or not isinstance(errors, list) or len(errors) > MAX_ERRORS: return _invalid(state, "limits_invalid")
|
|
if any(not isinstance(code, str) or _CODE_RE.fullmatch(code) is None for code in [*errors, *reason_codes]): return _invalid(state, "codes_invalid")
|
|
return state
|
|
|
|
|
|
def attach_context_state(state: dict[str, Any], request: Any | None = None, event: Any | None = None) -> dict[str, Any]:
|
|
for carrier in (request, event):
|
|
if carrier is not None:
|
|
try: setattr(carrier, ATTRIBUTE_NAME, state)
|
|
except Exception: pass
|
|
return state
|
|
|
|
|
|
def read_context_state(request: Any | None = None, event: Any | None = None, *, fixture_version: str = "1") -> dict[str, Any] | None:
|
|
for carrier in (request, event):
|
|
state = consume_context_state(getattr(carrier, ATTRIBUTE_NAME, None) if carrier is not None else None, fixture_version=fixture_version)
|
|
if state is not None:
|
|
attach_context_state(state, request, event)
|
|
return state
|
|
return None
|
|
|
|
|
|
def _refresh(state: dict[str, Any]) -> None:
|
|
if state["phase"] == "invalid" or state["finalized"]: return
|
|
completed = set(state["completed_layers"])
|
|
state["phase"] = "safety_ready" if "safety" in completed else "memory_ready" if "memory" in completed else "companion_ready" if set(_CORE).issubset(completed) else "initialized"
|
|
|
|
|
|
def _open(state: dict[str, Any]) -> bool:
|
|
return consume_context_state(state) is not None and state.get("phase") != "invalid" and not state.get("finalized")
|
|
|
|
|
|
def complete_layer(state: dict[str, Any], layer: str) -> dict[str, Any]:
|
|
if not _open(state): return state
|
|
if layer not in LAYERS: return _invalid(state, "layer_invalid")
|
|
if layer not in state["completed_layers"]:
|
|
state["completed_layers"].append(layer)
|
|
state["completed_layers"].sort(key=LAYERS.index)
|
|
_refresh(state); return state
|
|
|
|
|
|
def register_fragment(state: dict[str, Any], *, key: Any, layer: str, source: Any = "", trust_level: str = "T2", content: Any = None, content_hash: Any = "", chars: Any = None, status: Any = "allowed") -> dict[str, Any]:
|
|
if not _open(state): return state
|
|
if layer not in LAYERS or trust_level not in TRUST_LEVELS: return _invalid(state, "fragment_invalid")
|
|
raw = "" if content is None else str(content)
|
|
try: size = max(0, int(len(raw) if chars is None else chars))
|
|
except (TypeError, ValueError): return _invalid(state, "fragment_chars_invalid")
|
|
item = {"key": _text(key, 120) or "fragment", "layer": layer, "source": _text(source, 120), "trust_level": trust_level, "content_hash": _text(content_hash, 128) or hashlib.sha256(raw.encode("utf-8")).hexdigest(), "chars": size, "status": _text(status, 40) or "allowed"}
|
|
for old in state["fragments"]:
|
|
if old == item: return state
|
|
if old.get("key") == item["key"]: return _invalid(state, "fragment_key_conflict")
|
|
if len(state["fragments"]) >= MAX_FRAGMENTS: return _invalid(state, "fragment_limit")
|
|
state["fragments"].append(item); return state
|
|
|
|
|
|
def update_security(state: dict[str, Any], *, status: str | None = None, event_id: Any = None, memory_policy: str | None = None, tool_policy: str | None = None, response_policy: str | None = None, reason_codes: Any = None) -> dict[str, Any]:
|
|
if not _open(state): return state
|
|
security = state["security"]
|
|
if status is not None:
|
|
if status not in SECURITY_STATUSES: return _invalid(state, "security_status_invalid")
|
|
security["status"] = status
|
|
for key, value in (("memory_policy", memory_policy), ("tool_policy", tool_policy), ("response_policy", response_policy)):
|
|
if value is not None:
|
|
if value not in POLICIES: return _invalid(state, "security_policy_invalid")
|
|
security[key] = value
|
|
if event_id is not None: security["event_id"] = _text(event_id, 180)
|
|
codes = [reason_codes] if isinstance(reason_codes, str) else (reason_codes or [])
|
|
if not isinstance(codes, (list, tuple, set)): return _invalid(state, "reason_codes_invalid")
|
|
for code in codes:
|
|
if not isinstance(code, str) or _CODE_RE.fullmatch(code) is None: return _invalid(state, "reason_code_invalid")
|
|
if code not in security["reason_codes"] and len(security["reason_codes"]) < MAX_REASON_CODES: security["reason_codes"].append(code)
|
|
return state
|
|
|
|
|
|
def finalize_state(state: dict[str, Any]) -> dict[str, Any]:
|
|
if not _open(state): return state
|
|
if set(LAYERS).issubset(set(state["completed_layers"])):
|
|
state["phase"], state["finalized"] = "finalized", True
|
|
else:
|
|
_error(state, "finalize_pending_layers")
|
|
return state
|
|
|
|
|
|
def project_context_state(state: dict[str, Any] | None) -> dict[str, Any] | None:
|
|
state = consume_context_state(state)
|
|
if state is None: return None
|
|
return deepcopy({key: state[key] for key in ("contract_name", "contract_version", "contract_fingerprint", "request_id", "session_id", "scope", "created_at", "phase", "completed_layers", "fragments", "security", "errors", "finalized")})
|
|
|
|
|
|
def infer_context_layer(key: Any = "", source: Any = "") -> str:
|
|
text = f"{key or ''} {source or ''}".lower()
|
|
if any(token in text for token in ("memory", "recall")): return "memory"
|
|
if any(token in text for token in ("safety", "guard", "tool", "tts", "privacy", "sanitize")): return "safety"
|
|
if any(token in text for token in ("persona", "reply.style", "identity", "character")): return "persona"
|
|
if any(token in text for token in ("private.context", "preferred_address", "preferred address", "relationship", "nickname", "person", "user.")): return "person"
|
|
if any(token in text for token in ("runtime", "state", "schedule", "temporal", "weather", "food", "agenda", "time")): return "runtime"
|
|
return "scene"
|