tryvira-sdk 0.1.1__tar.gz

tryvira_sdk-0.1.1/PKG-INFO

@@ -0,0 +1,66 @@
+Metadata-Version: 2.4
+Name: tryvira-sdk
+Version: 0.1.1
+Summary: Typed Python client for the Vira authority boundary
+Author: Vira
+License-Expression: Apache-2.0
+Project-URL: Repository, https://github.com/hrpering/vira_beh_redesign
+Project-URL: Documentation, https://github.com/hrpering/vira_beh_redesign/tree/main/sdks/python
+Keywords: ai-governance,observability,agent-runtime
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# Vira Python SDK
+
+Package name: `tryvira-sdk`.
+
+## Install
+
+```bash
+python -m pip install tryvira-sdk
+```
+
+For a repository checkout use `python -m pip install ./sdks/python`. The client is a thin
+HTTP client of Vira's authority boundary; it does not execute tools locally.
+
+For maintainers, build with `python -m build sdks/python`. Public CI uses PyPI Trusted
+Publishing; do not put a token in this repository or in an example.
+
+The SDK is a thin client of the Vira authority boundary. It does not execute
+tools or actions locally, invent stable semantic keys, or create a second
+telemetry store. Runtime requests are fail-closed; observation telemetry can be
+configured fail-open with `failure_mode="open"`.
+
+```python
+import os
+from vira import ViraClient
+
+with ViraClient(
+    "http://127.0.0.1:4185",
+    api_key=os.environ.get("VIRA_API_KEY"),
+) as vira:
+    connected = vira.connect_once(
+        "my-agent", "custom-agent",
+        {"organizationId": "org", "projectId": "project", "environmentId": "local"},
+        "custom-python", "1",
+        idempotency_key="connect-001",
+    )
+    system = connected.body["system"]
+    connection = connected.body["connection"]
+    vira.observe({
+        "eventId": "evt-1", "eventType": "model.response",
+        "aiSystemId": system["id"], "connectionId": connection["id"],
+        "payload": {"message": "A model response was produced."},
+    }, idempotency_key="evt-1")
+    semantic = vira.resolve_semantic({"input": "answer a customer billing question"})
+    print(semantic.body)
+```
+
+Runtime execution requires a released revision, a valid scope and an idempotency key;
+semantic resolution is not authorization. See [`docs/SDK_GUIDE.md`](../../docs/SDK_GUIDE.md)
+for the shared JS/Python lifecycle.
+
+The package metadata is intentionally dependency-free.
+

tryvira_sdk-0.1.1/README.md

@@ -0,0 +1,52 @@
+# Vira Python SDK
+
+Package name: `tryvira-sdk`.
+
+## Install
+
+```bash
+python -m pip install tryvira-sdk
+```
+
+For a repository checkout use `python -m pip install ./sdks/python`. The client is a thin
+HTTP client of Vira's authority boundary; it does not execute tools locally.
+
+For maintainers, build with `python -m build sdks/python`. Public CI uses PyPI Trusted
+Publishing; do not put a token in this repository or in an example.
+
+The SDK is a thin client of the Vira authority boundary. It does not execute
+tools or actions locally, invent stable semantic keys, or create a second
+telemetry store. Runtime requests are fail-closed; observation telemetry can be
+configured fail-open with `failure_mode="open"`.
+
+```python
+import os
+from vira import ViraClient
+
+with ViraClient(
+    "http://127.0.0.1:4185",
+    api_key=os.environ.get("VIRA_API_KEY"),
+) as vira:
+    connected = vira.connect_once(
+        "my-agent", "custom-agent",
+        {"organizationId": "org", "projectId": "project", "environmentId": "local"},
+        "custom-python", "1",
+        idempotency_key="connect-001",
+    )
+    system = connected.body["system"]
+    connection = connected.body["connection"]
+    vira.observe({
+        "eventId": "evt-1", "eventType": "model.response",
+        "aiSystemId": system["id"], "connectionId": connection["id"],
+        "payload": {"message": "A model response was produced."},
+    }, idempotency_key="evt-1")
+    semantic = vira.resolve_semantic({"input": "answer a customer billing question"})
+    print(semantic.body)
+```
+
+Runtime execution requires a released revision, a valid scope and an idempotency key;
+semantic resolution is not authorization. See [`docs/SDK_GUIDE.md`](../../docs/SDK_GUIDE.md)
+for the shared JS/Python lifecycle.
+
+The package metadata is intentionally dependency-free.
+

tryvira_sdk-0.1.1/agent_native.py

@@ -0,0 +1,63 @@
+"""Authority-free agent-native observation intents for the Python SDK."""
+from __future__ import annotations
+import hashlib, json
+from typing import Any, Mapping
+
+_FORBIDDEN = {'projectId','applicationId','integrationId','userRef','subjectRef','privacyClass','retentionClass','residencyClass','authorityLane','scopeKeys','integrityAttestation'}
+_LIFECYCLE = {'workflow.started','workflow.step','workflow.completed','action.proposed','action.completed','checkpoint.created','compensation.completed'}
+def _canonical(value: Any) -> bytes: return json.dumps(value, sort_keys=True, separators=(',',':'), ensure_ascii=False).encode()
+def _digest(value: Any) -> str: return hashlib.sha256(_canonical(value)).hexdigest()
+def _verify_payload(payload: Mapping[str, Any]) -> None:
+    injected=sorted(_FORBIDDEN.intersection(payload.keys()))
+    if injected: raise ValueError(f"AGENT_NATIVE_AUTHORITY_FIELD_FORBIDDEN:{','.join(injected)}")
+def build_observation_intent(payload: Mapping[str, Any]) -> dict[str, Any]:
+    _verify_payload(payload)
+    value={'schemaVersion':2,**dict(payload)}
+    for key in ('eventId','kind','occurredAt'):
+        if not str(value.get(key,'')).strip(): raise ValueError(f"AGENT_NATIVE_{key.upper()}_REQUIRED")
+    if not isinstance(value.get('payload',{}),dict): raise ValueError('AGENT_NATIVE_PAYLOAD_OBJECT_REQUIRED')
+    return {**value,'intentDigest':_digest(value)}
+def build_agent_native_observation_intent(payload: Mapping[str, Any]) -> dict[str, Any]: return build_observation_intent(payload)
+def verify_observation_intent(intent: Mapping[str, Any]) -> dict[str, Any]:
+    value=dict(intent); _verify_payload(value); received=value.pop('intentDigest',None)
+    if not received or _digest(value) != received: raise ValueError('AGENT_NATIVE_OBSERVATION_INTENT_DIGEST_MISMATCH')
+    return {**value,'intentDigest':received}
+def verify_agent_native_observation_intent(intent: Mapping[str, Any]) -> dict[str, Any]: return verify_observation_intent(intent)
+def build_lifecycle_intent(kind: str, payload: Mapping[str, Any]) -> dict[str, Any]:
+    if kind not in _LIFECYCLE: raise ValueError('BEHAVIOR_LIFECYCLE_KIND_INVALID')
+    return build_observation_intent({**dict(payload),'kind':kind})
+def build_behavior_lifecycle_observation_intent(kind: str, payload: Mapping[str, Any]) -> dict[str, Any]: return build_lifecycle_intent(kind, payload)
+def build_workflow_start_intent(payload: Mapping[str, Any]) -> dict[str, Any]: return build_lifecycle_intent('workflow.started', payload)
+def build_workflow_step_intent(payload: Mapping[str, Any]) -> dict[str, Any]: return build_lifecycle_intent('workflow.step', payload)
+def build_workflow_complete_intent(payload: Mapping[str, Any]) -> dict[str, Any]: return build_lifecycle_intent('workflow.completed', payload)
+def build_action_proposed_intent(payload: Mapping[str, Any]) -> dict[str, Any]: return build_lifecycle_intent('action.proposed', payload)
+def build_action_completed_intent(payload: Mapping[str, Any]) -> dict[str, Any]: return build_lifecycle_intent('action.completed', payload)
+def build_checkpoint_created_intent(payload: Mapping[str, Any]) -> dict[str, Any]: return build_lifecycle_intent('checkpoint.created', payload)
+def build_compensation_completed_intent(payload: Mapping[str, Any]) -> dict[str, Any]: return build_lifecycle_intent('compensation.completed', payload)
+def build_preference_intent(payload: Mapping[str, Any]) -> dict[str, Any]: return build_observation_intent({**dict(payload),'kind':'human.preference'})
+def build_handoff_intent(payload: Mapping[str, Any]) -> dict[str, Any]:
+    value=dict(payload); parent=value.pop('parentEventId',None); source=value.pop('fromAgentRef',None); target=value.pop('toAgentRef',None)
+    if not parent: raise ValueError('AGENT_NATIVE_HANDOFF_PARENT_EVENT_REQUIRED')
+    if not source or not target or source == target: raise ValueError('AGENT_NATIVE_HANDOFF_AGENT_IDENTITY_INVALID')
+    nested=value.pop('payload',{}); 
+    if not isinstance(nested,dict): raise ValueError('AGENT_NATIVE_PAYLOAD_OBJECT_REQUIRED')
+    handoff={'fromAgentRef':source,'toAgentRef':target}
+    for key in ('delegationRef','decisionOwnerAgentRef','toolOwnerAgentRef','toolRef'):
+        if key in value: handoff[key]=value.pop(key)
+    return build_observation_intent({**value,'kind':'agent.handoff','parentEventId':parent,'agentRef':source,'payload':{**nested,'viraTrajectoryV2':{'schemaVersion':2,'handoff':handoff}}})
+def create_online_delivery(*, client_instance_id: str, client_sequence: int, intent: Mapping[str, Any]) -> dict[str, Any]:
+    if client_sequence < 0: raise ValueError('AGENT_NATIVE_CLIENT_SEQUENCE_INVALID')
+    return {'schemaVersion':2,'clientInstanceId':client_instance_id,'clientSequence':client_sequence,'mode':'online','intent':verify_observation_intent(intent)}
+def offline_signing_digest(*, client_instance_id: str, client_sequence: int, queued_at: str, intent: Mapping[str, Any], key_ref: str, signed_at: str) -> str:
+    if client_sequence < 0: raise ValueError('AGENT_NATIVE_CLIENT_SEQUENCE_INVALID')
+    verified=verify_observation_intent(intent)
+    return _digest({'schemaVersion':2,'clientInstanceId':client_instance_id,'clientSequence':client_sequence,'queuedAt':queued_at,'intentDigest':verified['intentDigest'],'keyRef':key_ref,'signedAt':signed_at})
+def create_offline_delivery(*, client_instance_id: str, client_sequence: int, queued_at: str, intent: Mapping[str, Any], key_ref: str, signed_at: str, signature: str) -> dict[str, Any]:
+    if client_sequence < 0: raise ValueError('AGENT_NATIVE_CLIENT_SEQUENCE_INVALID')
+    if not key_ref.strip() or not signature.strip(): raise ValueError('AGENT_NATIVE_OFFLINE_PROOF_REQUIRED')
+    return {'schemaVersion':2,'clientInstanceId':client_instance_id,'clientSequence':client_sequence,'mode':'offline','queuedAt':queued_at,'intent':verify_observation_intent(intent),'offlineProof':{'scheme':'ed25519','keyRef':key_ref,'signature':signature,'signedAt':signed_at}}
+def create_online_observation_delivery(**kwargs: Any) -> dict[str, Any]: return create_online_delivery(**kwargs)
+def create_offline_observation_delivery(**kwargs: Any) -> dict[str, Any]: return create_offline_delivery(**kwargs)
+def utc_now_iso() -> str:
+    from datetime import datetime, timezone
+    return datetime.now(timezone.utc).isoformat(timespec='milliseconds').replace('+00:00','Z')

tryvira_sdk-0.1.1/digest.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+import hashlib
+import json
+from typing import Any
+
+def canonical_json(value: Any) -> str:
+    return json.dumps(value, sort_keys=True, separators=(",", ":"), ensure_ascii=False, allow_nan=False)
+
+def sha256_canonical(value: Any) -> str:
+    return hashlib.sha256(canonical_json(value).encode("utf-8")).hexdigest()

tryvira_sdk-0.1.1/execution_boundary_v2.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+from dataclasses import dataclass
+from typing import Any, Literal
+from digest import sha256_canonical
+
+BoundaryFamily = Literal['agent', 'model-step', 'tool', 'action', 'workflow', 'retrieval']
+IdentityStrength = Literal['server-derived', 'adapter-attested', 'registered', 'host-asserted', 'observed-only']
+
+@dataclass(frozen=True)
+class ExecutionBoundaryIdentityV2:
+    project_id: str
+    application_id: str
+    environment: Literal['dev', 'staging', 'production']
+    integration_id: str
+    framework: str
+    adapter_id: str
+    adapter_version: str
+    family: BoundaryFamily
+    operation: str
+    execution_id: str
+    stable_ref: str
+    component_type: str
+    identity_strength: IdentityStrength
+    registration_version: int = 1
+    resource: dict[str, str] | None = None
+    trajectory_id: str | None = None
+    parent_execution_id: str | None = None
+
+    def __post_init__(self) -> None:
+        for field in ('project_id', 'application_id', 'integration_id', 'framework', 'adapter_id', 'adapter_version', 'operation', 'execution_id', 'stable_ref', 'component_type'):
+            if not getattr(self, field).strip():
+                raise ValueError(f'{field.upper()}_REQUIRED')
+        if self.family == 'action' and self.identity_strength == 'observed-only':
+            raise ValueError('RUNTIME_IDENTITY_TOO_WEAK_FOR_EFFECT')
+        if self.registration_version < 1:
+            raise ValueError('REGISTRATION_VERSION_INVALID')
+
+    def to_dict_without_digest(self) -> dict[str, Any]:
+        value: dict[str, Any] = {'projectId': self.project_id, 'applicationId': self.application_id, 'environment': self.environment, 'integration': {'integrationId': self.integration_id, 'framework': self.framework, 'adapterId': self.adapter_id, 'adapterVersion': self.adapter_version}, 'execution': {'family': self.family, 'operation': self.operation, 'executionId': self.execution_id}, 'component': {'stableRef': self.stable_ref, 'componentType': self.component_type, 'identityStrength': self.identity_strength, 'registrationVersion': self.registration_version}}
+        if self.resource is not None: value['resource'] = dict(self.resource)
+        if self.trajectory_id is not None: value['execution']['trajectoryId'] = self.trajectory_id
+        if self.parent_execution_id is not None: value['execution']['parentExecutionId'] = self.parent_execution_id
+        return value
+
+    def to_dict(self) -> dict[str, Any]:
+        value = self.to_dict_without_digest()
+        value['boundaryDigest'] = sha256_canonical(value)
+        return value

tryvira_sdk-0.1.1/integration.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+from dataclasses import dataclass, field
+from typing import Any, Callable, Literal, Mapping
+from runtime import BehaviorExecutionContext, LifecycleCallback, RuntimeLifecycle
+
+PythonFramework = Literal['crewai','pydantic-ai','autogen','semantic-kernel','custom']
+IntegrationMode = Literal['observe','guide','rerank','repair','escalate','strict']
+IntegrationOperation = Literal['generate','stream','tool','action']
+@dataclass(frozen=True)
+class RuntimeIntegrationManifest:
+    framework: PythonFramework; adapter_version: str='2'; generate: bool=False; stream: bool=False; tool: bool=False; action: bool=False; stream_enforcement: Literal['unsupported','pass-through','buffer-until-verified']='unsupported'; post_model_finalization: bool=False; tool_interception: bool=False; action_interception: bool=False; signal_attestation: Literal['none','host-asserted','external-verified','server-derived']='none'; trace_provenance: bool=True; model_target: bool=True; projection_artifact: bool=False; unsupported: tuple[str,...]=field(default_factory=tuple)
+    def to_dict(self) -> dict[str,object]: return {'schemaVersion':2,'integrationId':f'vira.{self.framework}','framework':self.framework,'adapterVersion':self.adapter_version,'operations':{'generate':self.generate,'stream':self.stream,'tool':self.tool,'action':self.action},'streamEnforcement':self.stream_enforcement,'postModelFinalization':self.post_model_finalization,'toolInterception':self.tool_interception,'actionInterception':self.action_interception,'signalAttestation':self.signal_attestation,'traceProvenance':self.trace_provenance,'modelTarget':self.model_target,'projectionArtifact':self.projection_artifact,'knownUnsupportedGuarantees':list(self.unsupported)}
+    def operation_supported(self, operation: IntegrationOperation) -> bool: return {'generate': self.generate, 'stream': self.stream, 'tool': self.tool, 'action': self.action}[operation]
+def assess_runtime_integration_manifest(manifest: Mapping[str,object], *, mode: IntegrationMode, operation: IntegrationOperation, requires_trusted_signals: bool=False) -> dict[str,object]:
+    value=dict(manifest); operations=value.get('operations') if isinstance(value.get('operations'),Mapping) else {}; reasons=[]
+    if operations.get(operation) is not True: reasons.append(f'operation:{operation}:unsupported')
+    if value.get('traceProvenance') is not True: reasons.append('trace-provenance:missing')
+    if value.get('modelTarget') is not True: reasons.append('model-target:missing')
+    if requires_trusted_signals and value.get('signalAttestation') == 'none': reasons.append('signal-attestation:missing')
+    enforcing=mode != 'observe'
+    if enforcing and operation not in ('tool','action') and value.get('postModelFinalization') is not True: reasons.append('post-model-finalization:missing')
+    if operation == 'stream' and enforcing and value.get('streamEnforcement') != 'buffer-until-verified': reasons.append('stream-buffer-until-verified:missing')
+    if operation == 'tool' and enforcing and value.get('toolInterception') is not True: reasons.append('tool-interception:missing')
+    if operation == 'action' and enforcing and value.get('actionInterception') is not True: reasons.append('action-interception:missing')
+    if mode != 'observe' and value.get('projectionArtifact') is not True: reasons.append('projection-artifact:missing')
+    reasons.extend(f'declared-unsupported:{item}' for item in value.get('knownUnsupportedGuarantees',[]) if isinstance(item,str))
+    hard=any(reason.startswith(('operation:','trace-provenance:','model-target:','signal-attestation:','post-model-finalization:','stream-buffer-until-verified:','tool-interception:','action-interception:','projection-artifact:')) for reason in reasons)
+    status='unsupported' if not operations.get(operation) else 'partial' if hard or (mode != 'observe' and reasons) else 'supported'
+    return {'status':status,'enforcementGuaranteed':status == 'supported' and enforcing,'reasons':reasons}
+def assess_runtime_integration(manifest: RuntimeIntegrationManifest|Mapping[str,object], *, mode: IntegrationMode, operation: IntegrationOperation, requires_trusted_signals: bool=False) -> dict[str,object]:
+    value = manifest.to_dict() if hasattr(manifest, 'to_dict') else manifest
+    return assess_runtime_integration_manifest(value, mode=mode, operation=operation, requires_trusted_signals=requires_trusted_signals)
+
+class PythonFrameworkBridge:
+    def __init__(self, context: BehaviorExecutionContext, manifest: RuntimeIntegrationManifest, callback: LifecycleCallback | None = None):
+        self.context, self.manifest, self.lifecycle = context, manifest, RuntimeLifecycle(context, callback)
+    def before_execution(self, payload: dict[str, object]) -> dict[str, object]: self.lifecycle.emit('execution:start', eventType='model.response', framework=self.manifest.framework); return self.lifecycle.resolve_payload(payload)
+    def after_execution(self, output: object) -> dict[str, object]: return self.lifecycle.emit('execution:complete', eventType='model.response', framework=self.manifest.framework, output=output)
+    def before_tool(self, tool_name: str) -> dict[str, object]: return self.lifecycle.emit('tool:start', eventType='tool.started', framework=self.manifest.framework, toolName=tool_name)
+    def after_tool(self, tool_name: str) -> dict[str, object]: return self.lifecycle.emit('tool:complete', eventType='tool.completed', framework=self.manifest.framework, toolName=tool_name)
+    def before_action(self, action_name: str) -> dict[str, object]: return self.lifecycle.emit('action:start', eventType='action.proposed', framework=self.manifest.framework, actionName=action_name)
+    def after_action(self, action_name: str) -> dict[str, object]: return self.lifecycle.emit('action:complete', eventType='action.executed', framework=self.manifest.framework, actionName=action_name)
+
+def create_framework_bridge(framework: PythonFramework, context: BehaviorExecutionContext, *, callback: LifecycleCallback | None = None, manifest: RuntimeIntegrationManifest | None = None) -> PythonFrameworkBridge:
+    declared = manifest or RuntimeIntegrationManifest(framework=framework, generate=True, unsupported=('no effect-boundary enforcement is implied until native framework hooks are wired',))
+    if declared.framework != framework: raise ValueError('RUNTIME_INTEGRATION_FRAMEWORK_MISMATCH')
+    return PythonFrameworkBridge(context, declared, callback)
+def create_crewai_bridge(context: BehaviorExecutionContext, **kwargs: object) -> PythonFrameworkBridge: return create_framework_bridge('crewai', context, **kwargs)
+def create_pydantic_ai_bridge(context: BehaviorExecutionContext, **kwargs: object) -> PythonFrameworkBridge: return create_framework_bridge('pydantic-ai', context, **kwargs)
+def create_autogen_bridge(context: BehaviorExecutionContext, **kwargs: object) -> PythonFrameworkBridge: return create_framework_bridge('autogen', context, **kwargs)
+def create_semantic_kernel_bridge(context: BehaviorExecutionContext, **kwargs: object) -> PythonFrameworkBridge: return create_framework_bridge('semantic-kernel', context, **kwargs)

tryvira_sdk-0.1.1/observation_v2.py

@@ -0,0 +1,26 @@
+from agent_native import (
+    build_action_completed_intent, build_action_proposed_intent,
+    build_agent_native_observation_intent, build_behavior_lifecycle_observation_intent,
+    build_checkpoint_created_intent, build_compensation_completed_intent,
+    build_handoff_intent, build_preference_intent, build_workflow_complete_intent,
+    build_workflow_start_intent, build_workflow_step_intent,
+    create_offline_observation_delivery, create_online_observation_delivery,
+    offline_signing_digest, utc_now_iso, verify_agent_native_observation_intent,
+)
+
+def build_action_completed_intent(payload): return __import__('agent_native').build_action_completed_intent(payload)
+def build_action_proposed_intent(payload): return __import__('agent_native').build_action_proposed_intent(payload)
+def build_agent_native_observation_intent(payload): return __import__('agent_native').build_agent_native_observation_intent(payload)
+def build_behavior_lifecycle_observation_intent(kind, payload): return __import__('agent_native').build_behavior_lifecycle_observation_intent(kind, payload)
+def build_checkpoint_created_intent(payload): return __import__('agent_native').build_checkpoint_created_intent(payload)
+def build_compensation_completed_intent(payload): return __import__('agent_native').build_compensation_completed_intent(payload)
+def build_handoff_intent(payload): return __import__('agent_native').build_handoff_intent(payload)
+def build_preference_intent(payload): return __import__('agent_native').build_preference_intent(payload)
+def build_workflow_complete_intent(payload): return __import__('agent_native').build_workflow_complete_intent(payload)
+def build_workflow_start_intent(payload): return __import__('agent_native').build_workflow_start_intent(payload)
+def build_workflow_step_intent(payload): return __import__('agent_native').build_workflow_step_intent(payload)
+def create_offline_observation_delivery(**kwargs): return __import__('agent_native').create_offline_observation_delivery(**kwargs)
+def create_online_observation_delivery(**kwargs): return __import__('agent_native').create_online_observation_delivery(**kwargs)
+def offline_signing_digest(**kwargs): return __import__('agent_native').offline_signing_digest(**kwargs)
+def utc_now_iso(): return __import__('agent_native').utc_now_iso()
+def verify_agent_native_observation_intent(intent): return __import__('agent_native').verify_agent_native_observation_intent(intent)

tryvira_sdk-0.1.1/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tryvira-sdk"
+version = "0.1.1"
+description = "Typed Python client for the Vira authority boundary"
+requires-python = ">=3.10"
+readme = "README.md"
+license = "Apache-2.0"
+authors = [{ name = "Vira" }]
+keywords = ["ai-governance", "observability", "agent-runtime"]
+classifiers = ["Programming Language :: Python :: 3", "Programming Language :: Python :: 3 :: Only"]
+
+[project.urls]
+Repository = "https://github.com/hrpering/vira_beh_redesign"
+Documentation = "https://github.com/hrpering/vira_beh_redesign/tree/main/sdks/python"
+
+[tool.setuptools]
+packages = ["vira"]
+include-package-data = true
+py-modules = ["vira_client", "agent_native", "digest", "observation_v2", "execution_boundary_v2", "runtime", "runtime_v2", "integration"]
+
+[tool.setuptools.package-data]
+vira = ["py.typed"]
+

tryvira_sdk-0.1.1/runtime.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Any, Callable, Literal
+
+BehaviorExecutionKind = Literal['chat', 'agent', 'copilot', 'workflow']
+BehaviorExecutionOperation = Literal['generate', 'stream', 'tool', 'action']
+ModelProtocol = Literal['openai-chat', 'anthropic-messages', 'generic-chat', 'custom']
+
+def _required(value: str, field: str) -> str:
+    if not isinstance(value, str) or not value.strip(): raise ValueError(f'{field.upper()}_REQUIRED')
+    return value
+
+@dataclass(frozen=True)
+class ModelTarget:
+    provider: str
+    model: str | None = None
+    model_id: str | None = None
+    model_family: str | None = None
+    protocol: ModelProtocol | None = None
+    capabilities: dict[str, bool] | None = None
+    def __post_init__(self) -> None:
+        _required(self.provider, 'model_target_provider')
+        identities = [value for value in (self.model, self.model_id, self.model_family) if value is not None]
+        if not identities or any(not isinstance(value, str) or not value.strip() for value in identities): raise ValueError('MODEL_TARGET_IDENTITY_REQUIRED')
+        if self.model is not None and self.model_id is not None and self.model != self.model_id: raise ValueError('MODEL_TARGET_IDENTITY_CONFLICT')
+        if self.protocol is not None and self.protocol not in ('openai-chat', 'anthropic-messages', 'generic-chat', 'custom'): raise ValueError('MODEL_TARGET_PROTOCOL_INVALID')
+        if self.capabilities is not None and (set(self.capabilities) - {'tools', 'structuredOutput', 'reasoning', 'streaming'} or any(not isinstance(value, bool) for value in self.capabilities.values())): raise ValueError('MODEL_TARGET_CAPABILITY_INVALID')
+    def to_dict(self) -> dict[str, Any]:
+        return {key: value for key, value in {'provider': self.provider, 'model': self.model, 'modelId': self.model_id, 'modelFamily': self.model_family, 'protocol': self.protocol, 'capabilities': dict(self.capabilities) if self.capabilities is not None else None}.items() if value is not None}
+
+@dataclass(frozen=True)
+class RuntimeHost:
+    name: str
+    version: str | None = None
+    runtime: str | None = None
+    def __post_init__(self) -> None: _required(self.name, 'runtime_host_name')
+    def to_dict(self) -> dict[str, str]: return {key: value for key, value in {'name': self.name, 'version': self.version, 'runtime': self.runtime}.items() if value is not None}
+
+@dataclass(frozen=True)
+class BehaviorExecutionContext:
+    kind: BehaviorExecutionKind
+    operation: BehaviorExecutionOperation
+    host: RuntimeHost
+    model_target: ModelTarget
+    execution_id: str | None = None
+    def __post_init__(self) -> None:
+        if self.kind not in ('chat', 'agent', 'copilot', 'workflow'): raise ValueError('BEHAVIOR_EXECUTION_KIND_INVALID')
+        if self.operation not in ('generate', 'stream', 'tool', 'action'): raise ValueError('BEHAVIOR_EXECUTION_OPERATION_INVALID')
+    def to_dict(self) -> dict[str, Any]:
+        return {**{'kind': self.kind, 'operation': self.operation, 'host': self.host.to_dict(), 'modelTarget': self.model_target.to_dict()}, **({'executionId': self.execution_id} if self.execution_id is not None else {})}
+
+LifecycleCallback = Callable[[dict[str, Any]], None]
+class RuntimeLifecycle:
+    def __init__(self, context: BehaviorExecutionContext, callback: LifecycleCallback | None = None): self.context, self.callback = context, callback
+    def emit(self, stage: str, **provenance: Any) -> dict[str, Any]:
+        event = {'stage': stage, 'context': self.context.to_dict(), **provenance, 'at': datetime.now(timezone.utc).isoformat().replace('+00:00', 'Z')}
+        if self.callback: self.callback(event)
+        return event
+    def resolve_payload(self, payload: dict[str, Any]) -> dict[str, Any]: return {**payload, 'executionContext': self.context.to_dict()}

tryvira_sdk-0.1.1/runtime_v2.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+import re
+from typing import Any, Mapping
+
+_DIGEST = re.compile(r'^[0-9a-f]{64}$')
+_REQUIRED_PLAN = {'schemaVersion', 'traceId', 'revisions', 'effectiveProgramDigest', 'artifactDigests', 'capsuleDigest', 'matchedModuleKeys', 'preModel', 'toolPolicy', 'postModel', 'execution', 'provenance'}
+_REQUIRED_ENVELOPE = {'schemaVersion', 'legacyProjection', 'executionPlanV2', 'modelTarget', 'projectionArtifact', 'integration'}
+
+class ViraRuntimeCompatibilityError(ValueError):
+    def __init__(self, code: str, message: str, details: Mapping[str, Any] | None = None):
+        super().__init__(message); self.code, self.details = code, dict(details or {})
+
+def _invalid(message: str, field: str) -> ViraRuntimeCompatibilityError:
+    return ViraRuntimeCompatibilityError('VIRA_RUNTIME_V2_ENVELOPE_INVALID', message, {'field': field})
+def _object(value: Any, field: str) -> Mapping[str, Any]:
+    if not isinstance(value, Mapping): raise _invalid(f'{field} must be an object', field)
+    return value
+def _required_string(value: Any, field: str) -> str:
+    if not isinstance(value, str) or not value.strip(): raise _invalid(f'{field} is required', field)
+    return value
+def _digest(value: Any, field: str) -> str:
+    result = _required_string(value, field)
+    if not _DIGEST.fullmatch(result): raise _invalid(f'{field} must be a lowercase sha256 digest', field)
+    return result
+
+def parse_runtime_v2_compatibility_envelope(input: Any) -> dict[str, Any]:
+    envelope = _object(input, 'envelope')
+    missing = sorted(_REQUIRED_ENVELOPE - set(envelope))
+    if missing: raise _invalid(f'envelope is missing required fields: {", ".join(missing)}', 'envelope')
+    if envelope['schemaVersion'] != 2: raise _invalid('schemaVersion must be 2', 'schemaVersion')
+    _required_string(envelope['legacyProjection'], 'legacyProjection')
+    plan = _object(envelope['executionPlanV2'], 'executionPlanV2')
+    plan_missing = sorted(_REQUIRED_PLAN - set(plan))
+    if plan_missing: raise _invalid(f'executionPlanV2 is missing required fields: {", ".join(plan_missing)}', 'executionPlanV2')
+    if plan['schemaVersion'] != 2: raise _invalid('executionPlanV2.schemaVersion must be 2', 'executionPlanV2.schemaVersion')
+    _required_string(plan['traceId'], 'executionPlanV2.traceId')
+    _digest(plan['effectiveProgramDigest'], 'executionPlanV2.effectiveProgramDigest')
+    _digest(plan['capsuleDigest'], 'executionPlanV2.capsuleDigest')
+    for key in ('artifactDigests', 'matchedModuleKeys'):
+        if not isinstance(plan[key], list): raise _invalid(f'executionPlanV2.{key} must be a list', f'executionPlanV2.{key}')
+    _object(plan['preModel'], 'executionPlanV2.preModel'); _object(plan['toolPolicy'], 'executionPlanV2.toolPolicy'); _object(plan['postModel'], 'executionPlanV2.postModel'); _object(plan['execution'], 'executionPlanV2.execution'); _object(plan['provenance'], 'executionPlanV2.provenance')
+    _object(envelope['modelTarget'], 'modelTarget'); integration = _object(envelope['integration'], 'integration')
+    if 'manifest' in integration:
+        manifest = _object(integration['manifest'], 'integration.manifest')
+        for key in ('operations', 'traceProvenance', 'modelTarget', 'postModelFinalization', 'knownUnsupportedGuarantees'):
+            if key not in manifest: raise _invalid(f'integration.manifest is missing {key}', f'integration.manifest.{key}')
+        if not isinstance(manifest['operations'], Mapping) or not isinstance(manifest['knownUnsupportedGuarantees'], list): raise _invalid('integration.manifest capability shape is invalid', 'integration.manifest')
+        assessment = _object(integration.get('assessment'), 'integration.assessment')
+        if assessment.get('enforcementGuaranteed') is True and manifest.get('postModelFinalization') is not True: raise _invalid('integration assessment is forged', 'integration.assessment')
+        interoperability = integration.get('interoperability') or manifest.get('interoperability')
+        if isinstance(interoperability, Mapping) and interoperability.get('mode') == 'lossy' and not any(isinstance(item, str) and 'lossy' in item for item in manifest['knownUnsupportedGuarantees']): raise _invalid('lossy interoperability requires an explicit unsupported guarantee', 'integration.manifest.knownUnsupportedGuarantees')
+    if envelope['projectionArtifact'] is not None: _object(envelope['projectionArtifact'], 'projectionArtifact')
+    return dict(envelope)
+
+def require_runtime_v2_enforcement(input: Any) -> dict[str, Any]:
+    envelope = parse_runtime_v2_compatibility_envelope(input)
+    integration = envelope['integration']; assessment = integration.get('assessment') if isinstance(integration, Mapping) else None
+    guaranteed = assessment.get('enforcementGuaranteed') if isinstance(assessment, Mapping) else integration.get('enforcementGuaranteed')
+    if guaranteed is not True: raise ViraRuntimeCompatibilityError('VIRA_RUNTIME_V2_ENFORCEMENT_UNAVAILABLE', 'Runtime V2 enforcement was not negotiated', {'status': assessment.get('status') if isinstance(assessment, Mapping) else 'partial'})
+    return envelope

tryvira_sdk-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tryvira_sdk-0.1.1/tryvira_sdk.egg-info/PKG-INFO

@@ -0,0 +1,66 @@
+Metadata-Version: 2.4
+Name: tryvira-sdk
+Version: 0.1.1
+Summary: Typed Python client for the Vira authority boundary
+Author: Vira
+License-Expression: Apache-2.0
+Project-URL: Repository, https://github.com/hrpering/vira_beh_redesign
+Project-URL: Documentation, https://github.com/hrpering/vira_beh_redesign/tree/main/sdks/python
+Keywords: ai-governance,observability,agent-runtime
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# Vira Python SDK
+
+Package name: `tryvira-sdk`.
+
+## Install
+
+```bash
+python -m pip install tryvira-sdk
+```
+
+For a repository checkout use `python -m pip install ./sdks/python`. The client is a thin
+HTTP client of Vira's authority boundary; it does not execute tools locally.
+
+For maintainers, build with `python -m build sdks/python`. Public CI uses PyPI Trusted
+Publishing; do not put a token in this repository or in an example.
+
+The SDK is a thin client of the Vira authority boundary. It does not execute
+tools or actions locally, invent stable semantic keys, or create a second
+telemetry store. Runtime requests are fail-closed; observation telemetry can be
+configured fail-open with `failure_mode="open"`.
+
+```python
+import os
+from vira import ViraClient
+
+with ViraClient(
+    "http://127.0.0.1:4185",
+    api_key=os.environ.get("VIRA_API_KEY"),
+) as vira:
+    connected = vira.connect_once(
+        "my-agent", "custom-agent",
+        {"organizationId": "org", "projectId": "project", "environmentId": "local"},
+        "custom-python", "1",
+        idempotency_key="connect-001",
+    )
+    system = connected.body["system"]
+    connection = connected.body["connection"]
+    vira.observe({
+        "eventId": "evt-1", "eventType": "model.response",
+        "aiSystemId": system["id"], "connectionId": connection["id"],
+        "payload": {"message": "A model response was produced."},
+    }, idempotency_key="evt-1")
+    semantic = vira.resolve_semantic({"input": "answer a customer billing question"})
+    print(semantic.body)
+```
+
+Runtime execution requires a released revision, a valid scope and an idempotency key;
+semantic resolution is not authorization. See [`docs/SDK_GUIDE.md`](../../docs/SDK_GUIDE.md)
+for the shared JS/Python lifecycle.
+
+The package metadata is intentionally dependency-free.
+

tryvira_sdk-0.1.1/tryvira_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+README.md
+agent_native.py
+digest.py
+execution_boundary_v2.py
+integration.py
+observation_v2.py
+pyproject.toml
+runtime.py
+runtime_v2.py
+vira_client.py
+tryvira_sdk.egg-info/PKG-INFO
+tryvira_sdk.egg-info/SOURCES.txt
+tryvira_sdk.egg-info/dependency_links.txt
+tryvira_sdk.egg-info/top_level.txt
+vira/__init__.py
+vira/py.typed

tryvira_sdk-0.1.1/tryvira_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

tryvira_sdk-0.1.1/tryvira_sdk.egg-info/top_level.txt

@@ -0,0 +1,9 @@
+agent_native
+digest
+execution_boundary_v2
+integration
+observation_v2
+runtime
+runtime_v2
+vira
+vira_client

tryvira_sdk-0.1.1/vira/__init__.py

@@ -0,0 +1,32 @@
+"""Packaged Python SDK facade for Vira."""
+
+from vira_client import ViraApiError, ViraClient, ViraResponse
+from agent_native import (
+    build_observation_intent,
+    build_lifecycle_intent,
+    build_handoff_intent,
+    create_online_delivery,
+    create_offline_delivery,
+    verify_observation_intent,
+    build_agent_native_observation_intent, build_behavior_lifecycle_observation_intent,
+    build_preference_intent, build_workflow_start_intent, build_workflow_step_intent,
+    build_workflow_complete_intent, build_action_proposed_intent, build_action_completed_intent,
+    build_checkpoint_created_intent, build_compensation_completed_intent,
+    create_online_observation_delivery, create_offline_observation_delivery,
+    offline_signing_digest, utc_now_iso, verify_agent_native_observation_intent,
+)
+from digest import canonical_json, sha256_canonical
+from runtime import BehaviorExecutionContext, ModelTarget, RuntimeHost, RuntimeLifecycle
+from integration import PythonFrameworkBridge, RuntimeIntegrationManifest, create_framework_bridge
+from execution_boundary_v2 import ExecutionBoundaryIdentityV2
+from runtime_v2 import ViraRuntimeCompatibilityError, parse_runtime_v2_compatibility_envelope, require_runtime_v2_enforcement
+
+__all__ = [
+    "ViraApiError", "ViraClient", "ViraResponse",
+    "build_observation_intent", "build_lifecycle_intent", "build_handoff_intent", "build_agent_native_observation_intent",
+    "build_behavior_lifecycle_observation_intent", "build_preference_intent", "build_workflow_start_intent", "build_workflow_step_intent", "build_workflow_complete_intent",
+    "build_action_proposed_intent", "build_action_completed_intent", "build_checkpoint_created_intent", "build_compensation_completed_intent",
+    "create_online_delivery", "create_offline_delivery", "create_online_observation_delivery", "create_offline_observation_delivery", "offline_signing_digest", "utc_now_iso", "verify_observation_intent", "verify_agent_native_observation_intent",
+    "canonical_json", "sha256_canonical", "BehaviorExecutionContext", "ModelTarget", "RuntimeHost", "RuntimeLifecycle", "PythonFrameworkBridge", "RuntimeIntegrationManifest", "create_framework_bridge", "ExecutionBoundaryIdentityV2", "ViraRuntimeCompatibilityError", "parse_runtime_v2_compatibility_envelope", "require_runtime_v2_enforcement",
+]
+

tryvira_sdk-0.1.1/vira_client.py

@@ -0,0 +1,386 @@
+"""Typed Python SDK boundary for the versioned Vira control API.
+
+The client deliberately reuses the same admitted-observation authority as the
+JavaScript SDK; it does not create a second telemetry or learning store.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+import json
+import time
+from typing import Any, Callable, Mapping, Sequence
+from urllib.error import HTTPError, URLError
+from urllib.request import Request, urlopen
+
+Json = Any
+Transport = Callable[[str, str, Mapping[str, str], bytes | None, float], tuple[int, Mapping[str, str], bytes]]
+
+
+class ViraApiError(RuntimeError):
+    def __init__(self, status: int, body: Json, request_id: str = "") -> None:
+        super().__init__(f"VIRA_API_{status}")
+        self.status, self.body, self.request_id = status, body, request_id
+
+
+@dataclass(frozen=True)
+class ViraResponse:
+    status: int
+    body: Json
+    request_id: str = ""
+
+
+def _default_transport(url: str, method: str, headers: Mapping[str, str], body: bytes | None, timeout: float) -> tuple[int, Mapping[str, str], bytes]:
+    try:
+        with urlopen(Request(url, data=body, headers=dict(headers), method=method), timeout=timeout) as response:
+            return response.status, response.headers, response.read()
+    except HTTPError as error:
+        return error.code, error.headers, error.read()
+
+
+class ViraClient:
+    def __init__(self, base_url: str, *, api_key: str | None = None, timeout: float = 15.0, retries: int = 2,
+                 failure_mode: str = "throw", transport: Transport | None = None) -> None:
+        if not base_url.strip(): raise ValueError("SDK_BASE_URL_REQUIRED")
+        if failure_mode not in {"throw", "open"}: raise ValueError("SDK_FAILURE_MODE_INVALID")
+        self.base_url, self.api_key = base_url.rstrip("/"), api_key
+        self.timeout, self.retries, self.failure_mode = max(1.0, min(timeout, 120.0)), max(0, min(retries, 5)), failure_mode
+        self.transport = transport or _default_transport
+
+    def _request(self, method: str, path: str, *, query: Mapping[str, str] | None = None,
+                 body: Mapping[str, Json] | None = None, idempotency_key: str | None = None,
+                 enforcing: bool = False) -> ViraResponse | None:
+        from urllib.parse import urlencode
+        url = self.base_url + path + (("?" + urlencode(query)) if query else "")
+        headers = {"accept": "application/json"}
+        if self.api_key: headers["authorization"] = f"Bearer {self.api_key}"
+        if idempotency_key: headers["idempotency-key"] = idempotency_key
+        encoded = json.dumps(body, separators=(",", ":")).encode() if body is not None else None
+        if encoded is not None: headers["content-type"] = "application/json"
+        for attempt in range(self.retries + 1):
+            try:
+                status, response_headers, raw = self.transport(url, method, headers, encoded, self.timeout)
+                try: parsed = json.loads(raw) if raw else None
+                except json.JSONDecodeError: parsed = raw.decode(errors="replace")
+                request_id = response_headers.get("x-request-id", "")
+                if status >= 400:
+                    if status >= 500 and attempt < self.retries: time.sleep(0.025 * (2 ** attempt)); continue
+                    if self.failure_mode == "open" and not enforcing and status >= 500: return None
+                    raise ViraApiError(status, parsed, request_id)
+                return ViraResponse(status, parsed, request_id)
+            except (TimeoutError, URLError, OSError) as error:
+                if attempt < self.retries: time.sleep(0.025 * (2 ** attempt)); continue
+                if self.failure_mode == "open" and not enforcing: return None
+                raise error
+        raise RuntimeError("SDK_REQUEST_EXHAUSTED")
+
+    def connect(self, name: str, system_type: str, scope: Mapping[str, str], *, idempotency_key: str | None = None) -> ViraResponse | None:
+        return self._request("POST", "/v1/ai-systems", body={"name": name, "systemType": system_type, **dict(scope)}, idempotency_key=idempotency_key)
+
+    def connect_adapter(self, system_id: str, adapter_type: str, adapter_version: str, *, capabilities: list[str] | None = None, config: Json | None = None, idempotency_key: str | None = None) -> ViraResponse | None:
+        if not str(system_id).strip(): raise ValueError("SDK_SYSTEM_ID_REQUIRED")
+        return self._request("POST", f"/v1/ai-systems/{system_id}/connections", body={"adapterType": adapter_type, "adapterVersion": adapter_version, "capabilities": list(capabilities or []), "config": config or {}}, idempotency_key=idempotency_key)
+
+    def connect_once(self, name: str, system_type: str, scope: Mapping[str, str], adapter_type: str, adapter_version: str, *, capabilities: list[str] | None = None, config: Json | None = None, idempotency_key: str | None = None) -> ViraResponse | None:
+        system = self.connect(name, system_type, scope, idempotency_key=idempotency_key)
+        if system is None: return None
+        system_id = str(system.body.get("system", {}).get("id", ""))
+        connection = self.connect_adapter(system_id, adapter_type, adapter_version, capabilities=capabilities, config=config, idempotency_key=idempotency_key)
+        if connection is None: return None
+        return ViraResponse(connection.status, {"system": system.body.get("system"), "connection": connection.body.get("connection"), "handshake": connection.body.get("handshake")}, connection.request_id)
+
+    def observe(self, event: Mapping[str, Json], *, idempotency_key: str | None = None) -> ViraResponse | None:
+        required = ("eventId", "eventType", "aiSystemId", "connectionId")
+        if any(not str(event.get(key, "")).strip() for key in required): raise ValueError("SDK_OBSERVATION_FIELD_REQUIRED")
+        return self._request("POST", "/v1/observations", body=dict(event), idempotency_key=idempotency_key or str(event["eventId"]))
+
+    def observe_batch(self, events: list[Mapping[str, Json]], *, idempotency_key: str | None = None) -> ViraResponse | None:
+        if not 1 <= len(events) <= 100: raise ValueError("SDK_OBSERVATION_BATCH_INVALID")
+        return self._request("POST", "/v1/observations/batch", body={"events": events}, idempotency_key=idempotency_key)
+
+    def trace(self, event: Mapping[str, Json], **kwargs: Any) -> ViraResponse | None: return self.observe({**event, "eventType": "model.response"}, **kwargs)
+    def outcome(self, event: Mapping[str, Json], **kwargs: Any) -> ViraResponse | None: return self.observe({**event, "eventType": "business.outcome"}, **kwargs)
+    def feedback(self, event: Mapping[str, Json], **kwargs: Any) -> ViraResponse | None: return self.observe({**event, "eventType": "feedback.user"}, **kwargs)
+
+    def lifecycle(self, kind: str, payload: Mapping[str, Json], *, idempotency_key: str | None = None) -> ViraResponse | None:
+        """Emit an agent-native lifecycle observation with a client-owned digest."""
+        from agent_native import build_lifecycle_intent, create_online_delivery
+        intent = build_lifecycle_intent(kind, payload)
+        return self._request("POST", "/v1/observations/sdk", body=create_online_delivery(
+            client_instance_id=str(payload.get("clientInstanceId", "python-sdk")),
+            client_sequence=int(payload.get("clientSequence", 0)), intent=intent,
+        ), idempotency_key=idempotency_key or str(intent["eventId"]))
+
+    def preference(self, payload: Mapping[str, Json], *, idempotency_key: str | None = None) -> ViraResponse | None:
+        return self.lifecycle("workflow.step", {**payload, "payload": {"preference": dict(payload)}} , idempotency_key=idempotency_key)
+
+    def handoff(self, payload: Mapping[str, Json], *, idempotency_key: str | None = None) -> ViraResponse | None:
+        """Admit an agent handoff as an authority-free observation intent."""
+        from agent_native import build_handoff_intent, create_online_delivery
+        intent = build_handoff_intent(payload)
+        return self._request("POST", "/v1/observations/sdk", body=create_online_delivery(
+            client_instance_id=str(payload.get("clientInstanceId", "python-sdk")),
+            client_sequence=int(payload.get("clientSequence", 0)), intent=intent,
+        ), idempotency_key=idempotency_key or str(intent["eventId"]))
+
+    def workflow_start(self, payload: Mapping[str, Json], **kwargs: Any) -> ViraResponse | None:
+        return self.lifecycle("workflow.started", payload, **kwargs)
+
+    def workflow_step(self, payload: Mapping[str, Json], **kwargs: Any) -> ViraResponse | None:
+        return self.lifecycle("workflow.step", payload, **kwargs)
+
+    def workflow_complete(self, payload: Mapping[str, Json], **kwargs: Any) -> ViraResponse | None:
+        return self.lifecycle("workflow.completed", payload, **kwargs)
+
+    def action_proposed(self, payload: Mapping[str, Json], **kwargs: Any) -> ViraResponse | None:
+        return self.lifecycle("action.proposed", payload, **kwargs)
+
+    def action_completed(self, payload: Mapping[str, Json], **kwargs: Any) -> ViraResponse | None:
+        return self.lifecycle("action.completed", payload, **kwargs)
+
+    def checkpoint_created(self, payload: Mapping[str, Json], **kwargs: Any) -> ViraResponse | None:
+        return self.lifecycle("checkpoint.created", payload, **kwargs)
+
+    def compensation_completed(self, payload: Mapping[str, Json], **kwargs: Any) -> ViraResponse | None:
+        return self.lifecycle("compensation.completed", payload, **kwargs)
+
+    def execute_runtime(self, request: Mapping[str, Json]) -> ViraResponse | None:
+        return self._request("POST", "/v1/runtime/execute", body=dict(request), idempotency_key=str(request.get("idempotencyKey", "")), enforcing=True)
+
+    def evaluate_quality(self, request: Mapping[str, Json], *, idempotency_key: str | None = None) -> ViraResponse | None:
+        """Rank bounded chatbot candidates through Vira's quality/JEV gate."""
+        return self._request("POST", "/v1/quality/evaluate", body=dict(request), idempotency_key=idempotency_key, enforcing=True)
+
+    def create_signal_discovery_proposal(self, request: Mapping[str, Json], *, idempotency_key: str | None = None) -> ViraResponse | None:
+        return self._request("POST", "/v1/signals/discovery-proposals", body=dict(request), idempotency_key=idempotency_key or str(request.get("signalStableKey", "")))
+
+    def review_signal_discovery_proposal(self, proposal_id: str, decision: str, *, idempotency_key: str | None = None) -> ViraResponse | None:
+        if not proposal_id.strip(): raise ValueError("SDK_SIGNAL_PROPOSAL_ID_REQUIRED")
+        if decision not in {"APPROVE", "REJECT"}: raise ValueError("SDK_SIGNAL_DECISION_INVALID")
+        return self._request("POST", f"/v1/signals/discovery-proposals/{proposal_id}/review", body={"decision": decision}, idempotency_key=idempotency_key or f"signal-review:{proposal_id}")
+
+    def materialize_signal_discovery(self, proposal_id: str, request: Mapping[str, Json] | None = None, *, idempotency_key: str | None = None) -> ViraResponse | None:
+        if not proposal_id.strip(): raise ValueError("SDK_SIGNAL_PROPOSAL_ID_REQUIRED")
+        return self._request("POST", f"/v1/signals/discovery-proposals/{proposal_id}/materialize", body=dict(request or {}), idempotency_key=idempotency_key or f"signal-materialize:{proposal_id}")
+
+    def create_signal_mapping(self, request: Mapping[str, Json], *, idempotency_key: str | None = None) -> ViraResponse | None:
+        return self._request("POST", "/v1/signals/mappings", body=dict(request), idempotency_key=idempotency_key or str(request.get("signalStableKey", "")))
+
+    def get_signal_mapping(self, mapping_id: str) -> ViraResponse | None:
+        if not mapping_id.strip(): raise ValueError("SDK_SIGNAL_MAPPING_ID_REQUIRED")
+        return self._request("GET", f"/v1/signals/mappings/{mapping_id}")
+
+    def review_signal_mapping(self, mapping_id: str, request: Mapping[str, Json] | None = None, *, idempotency_key: str | None = None) -> ViraResponse | None:
+        if not mapping_id.strip(): raise ValueError("SDK_SIGNAL_MAPPING_ID_REQUIRED")
+        return self._request("POST", f"/v1/signals/mappings/{mapping_id}/review", body=dict(request or {}), idempotency_key=idempotency_key or f"signal-mapping-review:{mapping_id}")
+
+    def compile_behavior_capsule(self, request: Mapping[str, Json]) -> ViraResponse | None:
+        if not str(request.get("programId", "")).strip() or not str(request.get("input", "")).strip():
+            raise ValueError("SDK_BEHAVIOR_CAPSULE_INPUT_REQUIRED")
+        return self._request("POST", "/v1/runtime/behavior-capsule", body=dict(request), idempotency_key=str(request.get("idempotencyKey", "")))
+
+    def serve_behavior_projection(self, request: Mapping[str, Json]) -> ViraResponse | None:
+        if not str(request.get("input", "")).strip() or not str(request.get("provider", "")).strip():
+            raise ValueError("SDK_BEHAVIOR_PROJECTION_INPUT_REQUIRED")
+        return self._request("POST", "/v1/runtime/behavior-projection", body=dict(request), idempotency_key=str(request.get("idempotencyKey", "")))
+
+    def resolve(self, request: Mapping[str, Json]) -> ViraResponse | None:
+        """Backward-compatible alias for the explicit runtime resolver."""
+        return self.resolve_runtime(request)
+
+    def resolve_runtime(self, request: Mapping[str, Json]) -> ViraResponse | None:
+        """Resolve a persisted route through the governed runtime boundary.
+
+        A caller may provide either an explicit behaviorPoint or a canonical
+        semanticContext produced by semantic activation. The latter is the
+        boundary-only path used by framework integrations.
+        """
+        boundary = request.get("executionBoundary")
+        nested = boundary.get("behaviorPoint") if isinstance(boundary, Mapping) else None
+        semantic = request.get("semanticContext")
+        selected = semantic.get("behaviorPoint") if isinstance(semantic, Mapping) else None
+        if not str(request.get("behaviorPoint") or nested or selected or "").strip(): raise ValueError("SDK_RUNTIME_ROUTE_REQUIRED")
+        return self._request("POST", "/v1/runtime/resolve", body=dict(request), idempotency_key=str(request.get("idempotencyKey", "")), enforcing=True)
+
+    def resolve_boundary(self, execution_boundary: Mapping[str, Json], *, semantic_context: Mapping[str, Json] | None = None, idempotency_key: str | None = None) -> ViraResponse | None:
+        """Resolve a route without requiring a caller-selected BehaviorPoint."""
+        if not isinstance(execution_boundary, Mapping) or not execution_boundary:
+            raise ValueError("SDK_EXECUTION_BOUNDARY_REQUIRED")
+        body: dict[str, Json] = {"executionBoundary": dict(execution_boundary)}
+        if semantic_context is not None: body["semanticContext"] = dict(semantic_context)
+        if idempotency_key: body["idempotencyKey"] = idempotency_key
+        return self.resolve_runtime(body)
+
+    def resolve_semantic(self, request: Mapping[str, Json], *, idempotency_key: str | None = None) -> ViraResponse | None:
+        if not str(request.get("input", "")).strip(): raise ValueError("SDK_SEMANTIC_INPUT_REQUIRED")
+        return self._request("POST", "/v1/semantic/resolve", body=dict(request), idempotency_key=idempotency_key or f"sdk:semantic:{request['input']}")
+
+    def resolve_semantic_runtime(self, request: Mapping[str, Json]) -> ViraResponse | None:
+        """Resolve free-form user intent, then resolve its governed runtime behavior."""
+        if not str(request.get("input", "")).strip(): raise ValueError("SDK_SEMANTIC_INPUT_REQUIRED")
+        semantic = self.resolve_semantic(request, idempotency_key=str(request.get("idempotencyKey", "")) or None)
+        if not semantic: return None
+        body = semantic.body if isinstance(semantic.body, Mapping) else {}
+        receipt = body.get("receipt") if isinstance(body.get("receipt"), Mapping) else {}
+        if receipt.get("outcome") != "select" or not str(receipt.get("taskKey", "")).strip():
+            return ViraResponse(status=semantic.status, body={"semantic": semantic.body, "runtime": None}, request_id=semantic.request_id)
+        capsules = body.get("capsules") if isinstance(body.get("capsules"), list) else []
+        capsule = capsules[0] if capsules and isinstance(capsules[0], Mapping) else {}
+        behavior_point = str(capsule.get("behaviorKey") or receipt.get("taskKey") or "").strip()
+        if not behavior_point:
+            return ViraResponse(status=semantic.status, body={"semantic": semantic.body, "runtime": None}, request_id=semantic.request_id)
+        runtime_request: dict[str, Json] = {"semanticContext": {"taskKey": str(receipt.get("taskKey")), "behaviorPoint": behavior_point, "capsule": dict(capsule)}, "idempotencyKey": f"sdk:runtime:{request.get('idempotencyKey') or receipt.get('requestId') or request['input']}"}
+        if isinstance(request.get("executionBoundary"), Mapping): runtime_request["executionBoundary"] = dict(request["executionBoundary"])
+        runtime = self.resolve_runtime(runtime_request)
+        return ViraResponse(status=runtime.status, body={"semantic": semantic.body, "runtime": runtime.body}, request_id=runtime.request_id)
+
+    def list_behavior_programs(self) -> ViraResponse | None: return self._request("GET", "/v1/behavior-programs")
+    def list_behavior_strategies(self) -> ViraResponse | None: return self._request("GET", "/v1/behavior-strategies")
+    def get_behavior_strategy(self, strategy_id: str) -> ViraResponse | None:
+        if not strategy_id.strip(): raise ValueError("SDK_STRATEGY_ID_REQUIRED")
+        from urllib.parse import quote
+        return self._request("GET", f"/v1/behavior-strategies/{quote(strategy_id, safe='')}")
+    def create_behavior_strategy(self, definition: Json, *, strategy_id: str | None = None) -> ViraResponse | None:
+        if not definition: raise ValueError("SDK_STRATEGY_DEFINITION_REQUIRED")
+        return self._request("POST", "/v1/behavior-strategies", body={"definition": definition, **({"id": strategy_id} if strategy_id else {})})
+    def validate_behavior_strategy(self, strategy_id: str) -> ViraResponse | None:
+        if not strategy_id.strip(): raise ValueError("SDK_STRATEGY_ID_REQUIRED")
+        from urllib.parse import quote
+        return self._request("POST", f"/v1/behavior-strategies/{quote(strategy_id, safe='')}/validate", body={})
+    def simulate_behavior_strategy(self, strategy_id: str, initial_state: Mapping[str, Json] | None = None) -> ViraResponse | None:
+        if not strategy_id.strip(): raise ValueError("SDK_STRATEGY_ID_REQUIRED")
+        from urllib.parse import quote
+        return self._request("POST", f"/v1/behavior-strategies/{quote(strategy_id, safe='')}/simulate", body={"initialState": dict(initial_state or {})})
+    def start_strategy_execution(self, artifact_digest: str, *, organization_id: str, project_id: str, environment_id: str, revision_id: str, idempotency_key: str, nonce: str, expires_at: int | float, decision_plan_id: str, candidates: Sequence[Mapping[str, Json]], policy: str, behavior_point: str | None = None, execution_boundary: Mapping[str, Json] | None = None, allowed_ids: Sequence[str] | None = None, calibration_id: str | None = None, post_model_judge: Json | None = None, shadow: Json | None = None, trace_id: str | None = None, execution_id: str | None = None, state: Mapping[str, Json] | None = None) -> ViraResponse | None:
+        if not artifact_digest.strip(): raise ValueError("SDK_ARTIFACT_DIGEST_REQUIRED")
+        for value in (organization_id, project_id, environment_id, revision_id, idempotency_key, nonce, decision_plan_id, policy):
+            if not isinstance(value, str) or not value.strip(): raise ValueError("SDK_STRATEGY_START_FIELD_REQUIRED")
+        if not isinstance(expires_at, (int, float)): raise ValueError("SDK_EXPIRY_REQUIRED")
+        if not candidates: raise ValueError("SDK_STRATEGY_CANDIDATES_REQUIRED")
+        if behavior_point is not None and not behavior_point.strip(): raise ValueError("SDK_BEHAVIOR_POINT_REQUIRED")
+        body: Json = {"artifactDigest": artifact_digest, "organizationId": organization_id, "projectId": project_id, "environmentId": environment_id, "revisionId": revision_id, "idempotencyKey": idempotency_key, "nonce": nonce, "expiresAt": expires_at, "decisionPlanId": decision_plan_id, "candidates": [dict(candidate) for candidate in candidates], "policy": policy, **({"behaviorPoint": behavior_point} if behavior_point else {}), **({"executionBoundary": dict(execution_boundary)} if execution_boundary is not None else {}), **({"allowedIds": list(allowed_ids)} if allowed_ids is not None else {}), **({"calibrationId": calibration_id} if calibration_id else {}), **({"postModelJudge": post_model_judge} if post_model_judge is not None else {}), **({"shadow": shadow} if shadow is not None else {}), **({"traceId": trace_id} if trace_id else {}), **({"executionId": execution_id} if execution_id else {}), **({"state": dict(state)} if state is not None else {})}
+        return self._request("POST", "/v1/runtime/strategy-executions", body=body, idempotency_key=idempotency_key)
+    def get_strategy_execution(self, execution_id: str) -> ViraResponse | None:
+        if not execution_id.strip(): raise ValueError("SDK_EXECUTION_ID_REQUIRED")
+        from urllib.parse import quote
+        return self._request("GET", f"/v1/runtime/strategy-executions/{quote(execution_id, safe='')}")
+    def get_strategy_execution_trace(self, execution_id: str) -> ViraResponse | None:
+        if not execution_id.strip(): raise ValueError("SDK_EXECUTION_ID_REQUIRED")
+        from urllib.parse import quote
+        return self._request("GET", f"/v1/runtime/strategy-executions/{quote(execution_id, safe='')}/trace")
+    def continue_strategy_execution(self, execution_id: str, authority_digest: str | None = None, *, state: Mapping[str, Json] | None = None, references: Mapping[str, Json] | None = None) -> ViraResponse | None:
+        if not execution_id.strip(): raise ValueError("SDK_EXECUTION_ID_REQUIRED")
+        from urllib.parse import quote
+        body: dict[str, Json] = {}
+        if authority_digest: body["authorityDigest"] = authority_digest
+        if state is not None: body["state"] = dict(state)
+        if references is not None: body["references"] = dict(references)
+        return self._request("POST", f"/v1/runtime/strategy-executions/{quote(execution_id, safe='')}/continue", body=body)
+    def cancel_strategy_execution(self, execution_id: str) -> ViraResponse | None:
+        if not execution_id.strip(): raise ValueError("SDK_EXECUTION_ID_REQUIRED")
+        from urllib.parse import quote
+        return self._request("POST", f"/v1/runtime/strategy-executions/{quote(execution_id, safe='')}/cancel", body={})
+    def list_packs(self) -> ViraResponse | None: return self._request("GET", "/v1/packs")
+    def import_pack(self, manifest: Json | None = None, objects: Mapping[str, Json] | None = None, *, idempotency_key: str | None = None, archive_base64: str | None = None, file_name: str | None = None) -> ViraResponse | None:
+        if manifest is None and not archive_base64: raise ValueError("SDK_PACK_MANIFEST_OR_ARCHIVE_REQUIRED")
+        if archive_base64 and not file_name: raise ValueError("SDK_PACK_FILE_NAME_REQUIRED")
+        body: dict[str, Json] = {"objects": dict(objects or {})}
+        if manifest is not None: body["manifest"] = manifest
+        if archive_base64: body.update({"archiveBase64": archive_base64, "fileName": file_name})
+        return self._request("POST", "/v1/packs/import", body=body, idempotency_key=idempotency_key)
+    def install_pack(self, pack_id: str, variables: Mapping[str, Json] | None = None, *, idempotency_key: str | None = None) -> ViraResponse | None:
+        if not pack_id.strip(): raise ValueError("SDK_PACK_ID_REQUIRED")
+        from urllib.parse import quote
+        return self._request("POST", f"/v1/packs/{quote(pack_id, safe='')}/install", body={"variables": dict(variables or {})}, idempotency_key=idempotency_key or f"sdk:pack:install:{pack_id}")
+    def evaluate_pack(self, pack_id: str, request: Mapping[str, Json], *, idempotency_key: str | None = None) -> ViraResponse | None:
+        if not pack_id.strip(): raise ValueError("SDK_PACK_ID_REQUIRED")
+        from urllib.parse import quote
+        return self._request("POST", f"/v1/packs/{quote(pack_id, safe='')}/evaluate", body=dict(request), idempotency_key=idempotency_key or f"sdk:pack:evaluate:{pack_id}")
+    def release_pack(self, pack_id: str, *, idempotency_key: str | None = None) -> ViraResponse | None:
+        if not pack_id.strip(): raise ValueError("SDK_PACK_ID_REQUIRED")
+        from urllib.parse import quote
+        return self._request("POST", f"/v1/packs/{quote(pack_id, safe='')}/release", body={}, idempotency_key=idempotency_key or f"sdk:pack:release:{pack_id}")
+    def approve_pack(self, pack_id: str, *, idempotency_key: str | None = None) -> ViraResponse | None:
+        if not pack_id.strip(): raise ValueError("SDK_PACK_ID_REQUIRED")
+        from urllib.parse import quote
+        return self._request("POST", f"/v1/packs/{quote(pack_id, safe='')}/approve", body={}, idempotency_key=idempotency_key or f"sdk:pack:approve:{pack_id}")
+    def preview_pack_upgrade(self, pack_id: str, incoming: Mapping[str, Json], *, idempotency_key: str | None = None) -> ViraResponse | None:
+        if not pack_id.strip(): raise ValueError("SDK_PACK_ID_REQUIRED")
+        if not isinstance(incoming, Mapping): raise ValueError("SDK_PACK_UPGRADE_INPUT_REQUIRED")
+        from urllib.parse import quote
+        return self._request("POST", f"/v1/packs/{quote(pack_id, safe='')}/upgrade-preview", body={"incoming": dict(incoming)}, idempotency_key=idempotency_key or f"sdk:pack:upgrade-preview:{pack_id}")
+    def get_behavior_program(self, program_id: str) -> ViraResponse | None:
+        if not program_id.strip(): raise ValueError("SDK_PROGRAM_ID_REQUIRED")
+        from urllib.parse import quote
+        return self._request("GET", f"/v1/behavior-programs/{quote(program_id, safe='')}")
+    def create_behavior_program(self, program: Mapping[str, Json], *, idempotency_key: str | None = None) -> ViraResponse | None:
+        if not isinstance(program, Mapping) or not str(program.get("id", "")).strip(): raise ValueError("SDK_PROGRAM_REQUIRED")
+        return self._request("POST", "/v1/behavior-programs", body=dict(program), idempotency_key=idempotency_key or f"sdk:program:{program['id']}")
+
+    def list_discovery_candidates(self, review_state: str | None = None) -> ViraResponse | None:
+        return self._request("GET", "/v1/discovery/candidates", query={"reviewState": review_state} if review_state else None)
+    def start_evaluation(self, request: Mapping[str, Json], *, idempotency_key: str | None = None) -> ViraResponse | None:
+        return self._request("POST", "/v1/evaluations", body=dict(request), idempotency_key=idempotency_key)
+    def get_evaluation(self, evaluation_id: str) -> ViraResponse | None:
+        if not evaluation_id.strip(): raise ValueError("SDK_EVALUATION_ID_REQUIRED")
+        from urllib.parse import quote
+        return self._request("GET", f"/v1/evaluations/{quote(evaluation_id, safe='')}")
+    def create_release(self, request: Mapping[str, Json], *, idempotency_key: str | None = None) -> ViraResponse | None:
+        return self._request("POST", "/v1/releases", body=dict(request), idempotency_key=idempotency_key)
+    def submit_teach_evidence(self, evidence: Mapping[str, Json], *, idempotency_key: str | None = None) -> ViraResponse | None:
+        return self._request("POST", "/v1/teach/evidence", body=dict(evidence), idempotency_key=idempotency_key)
+
+    def attest_host_capabilities(self, attestation: Mapping[str, Json], *, idempotency_key: str | None = None) -> ViraResponse | None:
+        if attestation.get("schemaVersion") != 2:
+            raise ValueError("HOST_CAPABILITY_SCHEMA_VERSION_INVALID")
+        return self._request("POST", "/v1/runtime/capabilities/attest", body=dict(attestation), idempotency_key=idempotency_key)
+
+    def resolve_with_capabilities(self, attestation_id: str, request: Mapping[str, Json], *, idempotency_key: str | None = None) -> ViraResponse | None:
+        context = request.get("executionContext")
+        if not attestation_id.strip() or not isinstance(context, Mapping) or not str(context.get("executionId", "")).strip():
+            raise ValueError("HOST_CAPABILITY_EXECUTION_ID_REQUIRED")
+        return self._request("POST", "/v1/runtime/capabilities/resolve", body={"attestationId": attestation_id, "request": dict(request)}, idempotency_key=idempotency_key, enforcing=True)
+
+    def trace_with_capabilities(self, decision_digest: str, trace: Mapping[str, Json], *, idempotency_key: str | None = None) -> ViraResponse | None:
+        context = trace.get("executionContext")
+        if not decision_digest.strip() or not str(trace.get("id", "")).strip() or not isinstance(context, Mapping) or not str(context.get("executionId", "")).strip():
+            raise ValueError("HOST_CAPABILITY_TRACE_IDENTITY_REQUIRED")
+        return self._request("POST", "/v1/runtime/capabilities/traces", body={"decisionDigest": decision_digest, "trace": dict(trace)}, idempotency_key=idempotency_key)
+
+    def model_selection(self, request: Mapping[str, Json], *, idempotency_key: str | None = None) -> ViraResponse | None:
+        return self._request("POST", "/v1/model-serving/resolve", body=dict(request), idempotency_key=idempotency_key, enforcing=True)
+
+    def served_trace(self, trace: Mapping[str, Json], selection: Mapping[str, Json], *, idempotency_key: str | None = None) -> ViraResponse | None:
+        if not str(trace.get("id", "")).strip() or not isinstance(trace.get("executionContext"), Mapping):
+            raise ValueError("MODEL_SERVING_TRACE_IDENTITY_REQUIRED")
+        return self._request("POST", "/v1/model-serving/traces", body={"trace": dict(trace), "selection": dict(selection)}, idempotency_key=idempotency_key)
+
+    def teach(self, evidence: Mapping[str, Json], *, idempotency_key: str | None = None) -> ViraResponse | None:
+        return self._request("POST", "/v1/teach/evidence", body=dict(evidence), idempotency_key=idempotency_key)
+
+    def compare_rollout(self, deployment_id: str, comparison: Mapping[str, Json], *, idempotency_key: str | None = None) -> ViraResponse | None:
+        if not deployment_id.strip():
+            raise ValueError("DEPLOYMENT_ID_REQUIRED")
+        from urllib.parse import quote
+        return self._request("POST", f"/v1/deployments/{quote(deployment_id, safe='')}/comparisons", body=dict(comparison), idempotency_key=idempotency_key)
+
+    def rollout_health(self, deployment_id: str, health: Mapping[str, Json], *, idempotency_key: str | None = None) -> ViraResponse | None:
+        if not deployment_id.strip():
+            raise ValueError("DEPLOYMENT_ID_REQUIRED")
+        from urllib.parse import quote
+        return self._request("POST", f"/v1/deployments/{quote(deployment_id, safe='')}/authoritative-health", body=dict(health), idempotency_key=idempotency_key)
+
+    def connection_health(self, connection_id: str) -> ViraResponse | None: return self._request("GET", f"/v1/connections/{connection_id}/health")
+    def inventory(self, system_id: str) -> ViraResponse | None: return self._request("GET", f"/v1/ai-systems/{system_id}/inventory")
+    def test_connection(self, connection_id: str, *, idempotency_key: str | None = None) -> ViraResponse | None:
+        if not connection_id.strip(): raise ValueError("SDK_CONNECTION_ID_REQUIRED")
+        from urllib.parse import quote
+        return self._request("POST", f"/v1/connections/{quote(connection_id, safe='')}/test", body={}, idempotency_key=idempotency_key)
+
+    def close(self) -> None:
+        return None
+
+    def __enter__(self) -> "ViraClient":
+        return self
+
+    def __exit__(self, exc_type: object, exc_value: object, traceback: object) -> None:
+        self.close()