tenaxisos-sdk 0.2.0__py3-none-any.whl

tenaxisos_sdk/__init__.py

@@ -0,0 +1,14 @@
+"""TenaxisOS SDK — build, validate, sign, and publish packages."""
+
+__version__ = "0.2.0"
+
+# The SDK authoring/runtime host contract version (`compatibility.sdk_api` in
+# a package manifest). Distinct axis from `__version__`: this only changes
+# when the *shape* of `tenaxisos_sdk.agents`/`tenaxisos_sdk.host` changes in
+# a way that could break a package built against an older contract (a new
+# required `Host` method, a renamed `Agent` method, a changed `ToolOutcome`
+# member) — not on every release. Bump both together only when a release
+# happens to also be a contract change. The kernel checks a package's
+# declared `compatibility.sdk_api` range against this value before running
+# packages that rely on the public SDK runtime contract.
+SDK_API_VERSION = "0.2.0"

tenaxisos_sdk/agents/__init__.py

@@ -0,0 +1,20 @@
+from tenaxisos_sdk.agents.base import Agent, ProgressCallback
+from tenaxisos_sdk.agents.context import RunContext
+from tenaxisos_sdk.agents.findings import (
+    BASE_INPUT_SCHEMA,
+    FINDING_SCHEMA,
+    Finding,
+    validate_findings,
+)
+from tenaxisos_sdk.agents.manifest import generate_agent_payload
+
+__all__ = [
+    "Agent",
+    "ProgressCallback",
+    "RunContext",
+    "Finding",
+    "FINDING_SCHEMA",
+    "BASE_INPUT_SCHEMA",
+    "validate_findings",
+    "generate_agent_payload",
+]

tenaxisos_sdk/agents/base.py

@@ -0,0 +1,277 @@
+"""Agent — the SDK's public agent-authoring base class.
+
+Provides the shape a native agent needs (metadata class attributes,
+`add_finding`/`set_output`/`effective_config`/`progress`/`fail`, an
+abstract `run()`) while keeping every LLM/tool/file call routed through a
+`Host` (`tenaxisos_sdk.host`) supplied at construction time, never through
+a direct kernel import. In production the kernel supplies a `Host`
+implementation that binds this same class to real governance; for local
+development, `tenaxisos_sdk.testing.local_host.LocalMockHost` is a
+deterministic fake, so an author can write and run tests with no kernel
+installed.
+
+What this deliberately does NOT include, since these are the kernel's job,
+not something an agent author should reach for directly:
+- No org/tenant injection, no direct tool registry access — the host
+  decides how a tool call actually executes.
+- No LLM provider/task-hint routing — the host's `llm_complete` already
+  returns a routed, governed completion.
+- No integration wire-name resolution — an agent calls `self.tools.call(name,
+  args)` by logical name; the host resolves the underlying wiring.
+"""
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any, Awaitable, Callable, Optional
+
+from tenaxisos_sdk.agents.context import RunContext
+from tenaxisos_sdk.agents.findings import BASE_INPUT_SCHEMA, Finding
+from tenaxisos_sdk.host import Host, ToolCallResult
+
+ProgressCallback = Callable[[int, str], Awaitable[None]]
+
+
+class Agent(ABC):
+    """Base class for all SDK-authored agents.
+
+    Each agent implements `run()` and returns a list of `Finding` dicts via
+    `self.findings` / `self.add_finding(...)`.
+    """
+
+    # -- Metadata (override in subclass) ----------------------------------
+    display_name: str = "Unknown Agent"
+    description: str = ""
+    category: str = "general"
+    tools: list[str] = []
+    capability_tags: list[str] = []
+    toolchains: list[str] = []
+    input_types: list[str] = []
+    output_types: list[str] = []
+    CONFIG_SCHEMA: dict = {}
+    INPUT_SCHEMA: dict = {}
+    OUTPUT_SCHEMA: dict = {}
+    DECLARED_OUTPUT_SHAPE: dict = {}
+    privacy_tier: str = "standard"
+    # -- Behaviour contract ------------------------------------------------
+    version: str = "1.0.0"
+    deterministic: bool = True
+    idempotent: bool = True
+    side_effects: str = "none"  # none | external | irreversible
+    _skip_schema_validation: bool = False
+
+    def __init__(self, config: dict | None = None, *, host: Host) -> None:
+        """`host` is required and keyword-only: an `Agent` never has an
+        implicit default authority channel. Callers must be explicit about
+        whether they're binding to `LocalMockHost` or a production host."""
+        self.config: dict[str, Any] = config or {}
+        self._host = host
+        self.findings: list[Finding] = []
+        self.output: dict[str, Any] = {}
+        self.log_lines: list[str] = []
+        self._run_failed = False
+        self._fail_reason = ""
+        self.ctx = RunContext(self.config.get("context", {}))
+        self._validate_config_schema()
+
+    # -- Contract validation -------------------------------------------------
+
+    def workflow_variables(self) -> dict[str, Any]:
+        """Flat workflow/run variable values resolved for this run."""
+        workflow = self.config.get("workflow", {})
+        if isinstance(workflow, dict):
+            variables = workflow.get("effective_variables", {})
+            if isinstance(variables, dict):
+                return variables
+        return {}
+
+    def workflow_var(self, name: str, default: Any = None) -> Any:
+        """Read a resolved workflow variable by name."""
+        return self.workflow_variables().get(name, default)
+
+    def effective_config(self, name: str | None = None, default: Any = None) -> Any:
+        """Read the node's effective runtime config.
+
+        Effective config is derived by the host using this priority:
+        agent defaults < workflow variables < run variables < node config.
+        """
+        effective = self.config.get("effective_config")
+        if not isinstance(effective, dict):
+            effective = self.config
+        if name is None:
+            return effective
+        return effective.get(name, default)
+
+    def _validate_config_schema(self) -> None:
+        if self.__class__._skip_schema_validation:
+            return
+        schema = self.__class__.CONFIG_SCHEMA or {}
+        missing = [k for k, v in schema.items() if v.get("required") and k not in self.config]
+        if missing:
+            raise ValueError(
+                f"{self.__class__.__name__}: missing required config fields: {', '.join(missing)}"
+            )
+
+    def validate_input(self, runtime_data: dict) -> list[str]:
+        """Validate runtime execution data against INPUT_SCHEMA. Returns a
+        list of error strings — empty means valid."""
+        errors: list[str] = []
+        schema = {**BASE_INPUT_SCHEMA, **self.__class__.INPUT_SCHEMA}
+        for field_name, spec in schema.items():
+            if spec.get("required") and field_name not in runtime_data:
+                errors.append(f"missing required input field: '{field_name}'")
+            if field_name in runtime_data:
+                allowed = spec.get("enum")
+                val = runtime_data[field_name]
+                if allowed is not None and val not in allowed:
+                    errors.append(
+                        f"input field '{field_name}' must be one of {allowed}, got {val!r}"
+                    )
+        return errors
+
+    def validate_output(self, findings: list) -> list[str]:
+        """Validate findings against `FINDING_SCHEMA` before they're stored.
+        Returns a list of warning strings — empty means valid. Non-fatal:
+        callers should append error findings rather than aborting the run."""
+        from tenaxisos_sdk.agents.findings import validate_findings
+
+        return validate_findings(findings)
+
+    # -- Host-brokered channels ----------------------------------------------
+
+    async def call_tool(
+        self, name: str, args: Optional[dict[str, Any]] = None, **kwargs: Any
+    ) -> ToolCallResult:
+        """Propose a tool call through the host. The host decides
+        allow/deny/approval/dry-run — this never executes anything itself."""
+        payload: dict[str, Any] = dict(args or {})
+        payload.update(kwargs)
+        result = await self._host.call_tool(name, payload)
+        self.log_lines.append(f"[tool] {name}: {result.outcome.value}")
+        return result
+
+    async def llm_complete(
+        self, prompt: str, system: str | None = None, category: str = "llm"
+    ) -> str | None:
+        """Complete a prompt through the host's governed LLM channel.
+
+        Mirrors `BaseAgent.llm_complete`: emits an 'error' severity finding
+        on failure instead of raising, and returns None so callers can check
+        the result without a try/except.
+        """
+        try:
+            return await self._host.llm_complete(prompt, system)
+        except Exception as exc:  # noqa: BLE001 - host failures are reported as findings, not raised
+            self.add_finding(
+                severity="error",
+                category=category,
+                title="LLM call failed",
+                message=str(exc),
+            )
+            return None
+
+    async def read_file(self, path: str) -> str:
+        return await self._host.read_file(path)
+
+    async def read_file_bytes(self, path: str) -> bytes:
+        return await self._host.read_file_bytes(path)
+
+    async def list_files(self, path: str, pattern: str = "*") -> list[str]:
+        return await self._host.list_files(path, pattern)
+
+    # -- Run lifecycle --------------------------------------------------------
+
+    @abstractmethod
+    async def run(self, on_progress: ProgressCallback | None = None) -> list[dict]:
+        """Execute the agent. Should call `self.progress(...)` periodically.
+        Returns findings as dicts (use `self.findings_as_dicts()`)."""
+
+    async def progress(self, on_progress: Optional[ProgressCallback], pct: int, msg: str) -> None:
+        self.log_lines.append(f"[{pct}%] {msg}")
+        if on_progress:
+            await on_progress(pct, msg)
+
+    def fail(self, reason: str) -> None:
+        """Mark this run as failed without raising — the caller records
+        status='error' even though `run()` returned normally."""
+        self._run_failed = True
+        self._fail_reason = reason
+
+    @property
+    def failed(self) -> bool:
+        return self._run_failed
+
+    @property
+    def fail_reason(self) -> str:
+        return self._fail_reason
+
+    # -- Findings / outputs ----------------------------------------------------
+
+    def add_finding(
+        self,
+        severity: str,
+        category: str,
+        title: str,
+        message: str,
+        file: str | None = None,
+        line: int | None = None,
+        rule: str | None = None,
+        suggestion: str | None = None,
+        **extra: Any,
+    ) -> Finding:
+        f = Finding(severity, category, title, message, file, line, rule, suggestion)
+        f.extra.update({k: v for k, v in extra.items() if v is not None})
+        self.findings.append(f)
+        return f
+
+    def findings_as_dicts(self) -> list[dict]:
+        return [f.to_dict() for f in self.findings]
+
+    def set_output(self, name: str, value: Any) -> None:
+        """Record a declared contract output for this run. The key must be
+        declared in `output_types`."""
+        if name == "findings" or name not in self.__class__.output_types:
+            raise ValueError(
+                f"{self.__class__.__name__}: output '{name}' is not declared in output_types"
+            )
+        self.output[name] = value
+
+    def output_as_dict(self) -> dict[str, Any]:
+        return dict(self.output)
+
+    def summary(self) -> dict:
+        counts: dict[str, int] = {}
+        for f in self.findings:
+            counts[f.severity] = counts.get(f.severity, 0) + 1
+        return {"total": len(self.findings), "by_severity": counts}
+
+    @classmethod
+    def docs_metadata(cls) -> dict:
+        """Structured documentation metadata. See `agents/manifest.py` for
+        full package-manifest generation."""
+        config_docs = {}
+        for k, v in (cls.CONFIG_SCHEMA or {}).items():
+            config_docs[k] = {
+                "type": v.get("type", "str"),
+                "required": v.get("required", False),
+                "description": v.get("desc", v.get("description", "")),
+                "default": v.get("default"),
+            }
+        return {
+            "name": cls.display_name,
+            "category": cls.category,
+            "description": cls.description,
+            "input_types": list(cls.input_types),
+            "output_types": list(cls.output_types),
+            "config": config_docs,
+            "tools": list(cls.tools),
+            "capability_tags": list(cls.capability_tags),
+            "toolchains": list(cls.toolchains),
+            "privacy_tier": cls.privacy_tier,
+            "version": cls.version,
+            "deterministic": cls.deterministic,
+            "idempotent": cls.idempotent,
+            "side_effects": cls.side_effects,
+            "input_schema": dict(cls.INPUT_SCHEMA),
+            "output_schema": dict(cls.OUTPUT_SCHEMA),
+            "declared_output_shape": dict(cls.DECLARED_OUTPUT_SHAPE),
+        }

tenaxisos_sdk/agents/context.py

@@ -0,0 +1,132 @@
+"""RunContext — structured read-only accessor over kernel-assembled context.
+
+A read-only view over per-run context, so agent authors don't need to dig
+through raw JSON. The kernel assembles the payload in production; the local
+mock host (`tenaxisos_sdk.testing.local_host`) hands this the same shape
+locally so agent code doesn't need to know which one it's running under.
+
+Usage inside an SDK-authored agent:
+    prior = self.ctx.prior_findings("SomeUpstreamAgent")
+    rules = self.ctx.compliance_rules()
+"""
+from __future__ import annotations
+
+from typing import Any
+
+
+class RunContext:
+    """Structured accessor for the runtime context payload assembled by the
+    host. Agents receive this as `self.ctx` — see `agents/base.py`."""
+
+    def __init__(self, payload: dict[str, Any] | None = None) -> None:
+        self._payload = payload or {}
+
+    # -- Identity --------------------------------------------------------
+
+    @property
+    def agent_name(self) -> str:
+        return self._payload.get("agent_name", "unknown")
+
+    @property
+    def assembled_at(self) -> str:
+        return self._payload.get("assembled_at", "")
+
+    @property
+    def sources(self) -> list[str]:
+        return self._payload.get("sources", [])
+
+    @property
+    def snapshot_id(self) -> str | None:
+        return self._payload.get("context_snapshot_id")
+
+    # -- Prior findings from other agents ---------------------------------
+
+    def prior_findings(self, agent_name: str | None = None) -> list[dict]:
+        """Findings from the most recent completed run of other agents.
+        Pass agent_name to filter to a specific agent."""
+        all_prior = self._payload.get("prior_findings", [])
+        if agent_name:
+            for entry in all_prior:
+                if entry.get("agent") == agent_name:
+                    return entry.get("findings", [])
+            return []
+        flat: list[dict] = []
+        for entry in all_prior:
+            flat.extend(entry.get("findings", []))
+        return flat
+
+    def prior_agents(self) -> list[str]:
+        """Names of agents that have run and produced findings."""
+        return [e.get("agent", "") for e in self._payload.get("prior_findings", [])]
+
+    def critical_findings_from(self, agent_name: str) -> list[dict]:
+        """Convenience: only critical/high severity from a specific agent."""
+        return [
+            f for f in self.prior_findings(agent_name) if f.get("severity") in ("critical", "high")
+        ]
+
+    # -- Compliance --------------------------------------------------------
+
+    def compliance_rules(self) -> list[dict]:
+        """Active compliance frameworks and their pass/fail status."""
+        return self._payload.get("compliance", [])
+
+    def failing_frameworks(self) -> list[str]:
+        """Names of compliance frameworks with failing controls."""
+        return [f["name"] for f in self.compliance_rules() if f.get("fail", 0) > 0]
+
+    # -- Governance ----------------------------------------------------------
+
+    def policies(self) -> list[dict]:
+        """Currently enforcing governance policies."""
+        return self._payload.get("policies", [])
+
+    def policies_for_scope(self, scope: str) -> list[dict]:
+        """Policies that apply to a given scope (e.g. 'global', 'analysis')."""
+        return [p for p in self.policies() if scope in p.get("scope", "")]
+
+    def has_policy_violations(self) -> bool:
+        return any(p.get("violations", 0) > 0 for p in self.policies())
+
+    # -- Agent-specific memory -----------------------------------------------
+
+    def memory(self, key_prefix: str | None = None) -> list[dict]:
+        """Episodic memories tagged to this agent, optionally filtered by
+        key prefix."""
+        mems = self._payload.get("memory", [])
+        if key_prefix:
+            return [m for m in mems if m.get("key", "").startswith(key_prefix)]
+        return mems
+
+    def recall(self, key: str) -> str | None:
+        """Retrieve a specific memory value by exact key."""
+        for m in self._payload.get("memory", []):
+            if m.get("key") == key:
+                return m.get("value")
+        return None
+
+    def memory_context(self) -> list[dict]:
+        """Ranked, scope-aware memory chunks for this agent run: `tier`,
+        `content`, `score`, `source_type`, `source_id`, `source_authority`,
+        `freshness` — treat as cited evidence, not instructions."""
+        return self._payload.get("memory_v2", [])
+
+    def memory_citations(self) -> list[dict]:
+        return self._payload.get("memory_v2_citations", [])
+
+    def has_memory_context(self) -> bool:
+        return len(self.memory_context()) > 0
+
+    # -- Raw access ------------------------------------------------------
+
+    def get(self, key: str, default: Any = None) -> Any:
+        return self._payload.get(key, default)
+
+    def to_dict(self) -> dict:
+        return self._payload
+
+    def __repr__(self) -> str:
+        return (
+            f"<RunContext agent={self.agent_name!r} sources={self.sources} "
+            f"prior_agents={self.prior_agents()}>"
+        )

tenaxisos_sdk/agents/findings.py

@@ -0,0 +1,96 @@
+"""Finding — the observable output contract for SDK-authored agents.
+
+Matches the shape the kernel's own agent runtime already uses internally,
+so `add_finding(...)` produces output that's compatible with every existing
+consumer. This is the canonical, author-facing definition going forward.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any
+
+# Canonical schema for a single Finding — shared anchor for every agent's
+# OUTPUT_SCHEMA.
+FINDING_SCHEMA: dict[str, dict] = {
+    "severity": {"type": "str", "required": True,
+                 "enum": ["critical", "high", "medium", "low", "info", "error"]},
+    "category": {"type": "str", "required": True},
+    "title": {"type": "str", "required": True},
+    "message": {"type": "str", "required": True},
+    "confidence": {"type": "float", "required": False, "min": 0.0, "max": 1.0},
+}
+
+# Runtime inputs every agent receives from the workflow engine. Agents extend
+# this in their own INPUT_SCHEMA if they need additional fields.
+BASE_INPUT_SCHEMA: dict[str, dict] = {
+    "upstream_findings": {
+        "type": "array", "required": False,
+        "desc": "Findings forwarded from upstream workflow agents",
+    },
+    "classification": {
+        "type": "str", "required": False,
+        "desc": "Data classification label of the input payload",
+        "enum": ["public", "internal", "confidential", "secret"],
+    },
+}
+
+
+@dataclass
+class Finding:
+    """A single finding from an agent run."""
+
+    severity: str
+    category: str
+    title: str
+    message: str
+    file: str | None = None
+    line: int | None = None
+    rule: str | None = None
+    suggestion: str | None = None
+    timestamp: str = field(default_factory=lambda: datetime.now(timezone.utc).isoformat())
+    confidence: float = 1.0
+    extra: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        data = {
+            "severity": self.severity,
+            "category": self.category,
+            "title": self.title,
+            "message": self.message,
+            "file": self.file,
+            "line": self.line,
+            "rule": self.rule,
+            "suggestion": self.suggestion,
+            "timestamp": self.timestamp,
+            "confidence": self.confidence,
+        }
+        data.update(self.extra)
+        return data
+
+
+def validate_findings(findings: list[Any]) -> list[str]:
+    """Validate agent findings against `FINDING_SCHEMA`. Returns a list of
+    warning strings — empty means valid. Mirrors
+    `BaseAgent.validate_output` so local and production checks agree."""
+    errors: list[str] = []
+    valid_severities = {"critical", "high", "medium", "low", "info", "error"}
+    for i, f in enumerate(findings):
+        if not isinstance(f, dict):
+            errors.append(f"finding[{i}] is not a dict (got {type(f).__name__})")
+            continue
+        for req in ("severity", "category", "title", "message"):
+            if req not in f:
+                errors.append(f"finding[{i}] missing required field '{req}'")
+        sev = f.get("severity")
+        if sev and sev not in valid_severities:
+            errors.append(f"finding[{i}] severity '{sev}' not in {valid_severities}")
+        conf = f.get("confidence")
+        if conf is not None:
+            try:
+                cf = float(conf)
+                if not (0.0 <= cf <= 1.0):
+                    errors.append(f"finding[{i}] confidence {cf} out of range [0, 1]")
+            except (TypeError, ValueError):
+                errors.append(f"finding[{i}] confidence must be a float, got {type(conf).__name__}")
+    return errors