cogno-cortex 0.1.0__py3-none-any.whl

cogno_cortex/__init__.py

@@ -0,0 +1,46 @@
+"""cogno-cortex — the in-process skills framework for the Cogno stack.
+
+Skills are authored as ``BaseTool`` subclasses + ``SkillManifest`` metadata,
+ranked against NER tags by ``SkillRegistry``, executed by ``SkillBus`` (via a
+``SkillProvider`` — ``LocalProvider`` ships), and discovered from disk by the
+loader. ``CortexDispatcher`` bridges them to cogno-anima's ``ToolDispatcher`` so the
+EGO / cogno-soma see skills as ordinary tools — merge with MCP/native sources via
+``cogno_anima.tools.CompositeDispatcher``.
+"""
+
+from cogno_cortex.base import BasePromptTool, BaseTool, ToolContext
+from cogno_cortex.bus import (
+    LocalProvider,
+    SkillBus,
+    SkillNotFoundError,
+    SkillProvider,
+)
+from cogno_cortex.dispatcher import CortexDispatcher
+from cogno_cortex.loader import (
+    discover,
+    load_skill_dir,
+    parse_frontmatter,
+    register_all,
+)
+from cogno_cortex.registry import SkillRegistry
+from cogno_cortex.types import SkillManifest, SkillResult
+
+__all__ = [
+    "BaseTool",
+    "BasePromptTool",
+    "ToolContext",
+    "SkillManifest",
+    "SkillResult",
+    "SkillRegistry",
+    "SkillBus",
+    "SkillProvider",
+    "LocalProvider",
+    "SkillNotFoundError",
+    "CortexDispatcher",
+    "discover",
+    "load_skill_dir",
+    "register_all",
+    "parse_frontmatter",
+]
+
+__version__ = "0.1.0"

cogno_cortex/base.py

@@ -0,0 +1,98 @@
+"""Skill authoring contracts: ``BaseTool`` / ``BasePromptTool`` / ``ToolContext``.
+
+A skill is a ``BaseTool`` subclass: its Pydantic fields ARE the tool's arguments,
+and ``run(context)`` executes it, returning a :class:`SkillResult`. ``ToolContext``
+carries the injected LLM backend + free-form metadata (the host passes domains,
+constraints, the user query, etc.) — note it carries NO pipeline/DB handle: a skill
+is infra-agnostic, exactly like the rest of the stack.
+
+Ported from the parent ``cogno.skills.base``; the ``PipelineContext`` coupling of
+the parent's ``ToolContext`` is replaced by a plain ``metadata`` dict.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict
+
+from cogno_cortex.types import SkillResult
+
+
+class ToolContext(BaseModel):
+    """Execution context passed to a skill's ``run()``.
+
+    Attributes:
+        backend:  an injected ``cogno_synapse.LLMBackend`` (typed ``Any`` to avoid a
+                  hard import + circulars); ``None`` for skills that need no LLM.
+        trace_id: optional correlation id for observability.
+        metadata: extra context from the host (domains, constraints, user query, ...).
+    """
+
+    backend: Any = None
+    trace_id: str = ""
+    metadata: dict[str, Any] = {}
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+
+class BaseTool(BaseModel, ABC):
+    """Abstract base for all skills. Subclasses declare arguments as Pydantic fields.
+
+    Example::
+
+        class MathTool(BaseTool):
+            a: float
+            op: str
+            b: float
+
+            @property
+            def name(self) -> str: return "math"
+
+            @property
+            def description(self) -> str: return "Basic arithmetic."
+
+            async def run(self, context: ToolContext) -> SkillResult:
+                ...
+    """
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Unique skill name (must match the ``SkillManifest.name``)."""
+
+    @property
+    @abstractmethod
+    def description(self) -> str:
+        """Human-readable description of what this skill does."""
+
+    @abstractmethod
+    async def run(self, context: ToolContext) -> SkillResult:
+        """Execute the skill and return a :class:`SkillResult`."""
+
+    @classmethod
+    def args_schema(cls) -> dict[str, Any]:
+        """JSON-Schema for this skill's arguments (its Pydantic fields)."""
+        return cls.model_json_schema()
+
+
+class BasePromptTool(BaseTool):
+    """Convenience base for LLM-driven skills: ``run`` formats a prompt + calls the backend."""
+
+    @property
+    @abstractmethod
+    def prompt_template(self) -> str:
+        """A ``str.format`` template with ``{field_name}`` placeholders."""
+
+    async def run(self, context: ToolContext) -> SkillResult:
+        formatted = self.prompt_template.format(**self.model_dump())
+        response = await context.backend.generate("You are a specialized tool assistant.", formatted)
+        text = response[0] if isinstance(response, tuple) else response
+        usage: dict[str, int] = {}
+        if isinstance(response, tuple) and len(response) >= 3:
+            usage = {"tokens_in": response[1], "tokens_out": response[2]}
+        return SkillResult(
+            skill_name=self.name, payload=text, status="success",
+            evidence=[f"prompt tool '{self.name}' executed"], usage=usage)

cogno_cortex/bus.py

@@ -0,0 +1,95 @@
+"""``SkillBus`` — provider-based skill dispatch.
+
+The bus maps a skill name → its execution provider. ``LocalProvider`` runs an
+in-process ``BaseTool`` (the only provider cortex ships); the ``SkillProvider``
+Protocol is the seam a host plugs shell/http/remote providers into (those carry
+subprocess/network + security decisions that are host concerns).
+
+Ported from the parent ``cogno.skills.bus`` — the os/JSONL debug logging is dropped
+in favour of the house-rule structured logger (lazy ``key=value``, no handlers).
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Optional, Protocol, runtime_checkable
+
+from cogno_cortex.base import ToolContext
+from cogno_cortex.types import SkillManifest, SkillResult
+
+logger = logging.getLogger(__name__)
+
+
+@runtime_checkable
+class SkillProvider(Protocol):
+    """Execution backend for a class of skills."""
+
+    def supports(self, manifest: SkillManifest) -> bool:
+        """Return True if this provider can execute the given manifest."""
+        ...
+
+    async def invoke(
+        self, manifest: SkillManifest, context: ToolContext,
+        tool_args: Optional[dict[str, Any]] = None,
+    ) -> SkillResult:
+        """Execute the skill and return a :class:`SkillResult`."""
+        ...
+
+
+class LocalProvider:
+    """Runs skills that carry a ``tool_class`` (a ``BaseTool`` subclass), in-process."""
+
+    def supports(self, manifest: SkillManifest) -> bool:
+        return manifest.tool_class is not None
+
+    async def invoke(
+        self, manifest: SkillManifest, context: ToolContext,
+        tool_args: Optional[dict[str, Any]] = None,
+    ) -> SkillResult:
+        if manifest.tool_class is None:
+            raise RuntimeError(f"manifest '{manifest.name}' has no tool_class")
+        tool = manifest.tool_class(**(tool_args or {}))
+        return await tool.run(context)
+
+
+class SkillNotFoundError(KeyError):
+    """Raised by the bus when a skill name has no registered manifest."""
+
+
+class SkillBus:
+    """Dispatches skill invocations to the first registered provider that supports them."""
+
+    def __init__(self) -> None:
+        self.providers: list[SkillProvider] = []
+        self._manifests: dict[str, SkillManifest] = {}
+
+    def register_provider(self, provider: SkillProvider) -> None:
+        self.providers.append(provider)
+
+    def register_manifest(self, manifest: SkillManifest) -> None:
+        self._manifests[manifest.name] = manifest
+
+    def get_manifest(self, skill_name: str) -> Optional[SkillManifest]:
+        return self._manifests.get(skill_name)
+
+    async def invoke(
+        self, skill_name: str, context: ToolContext,
+        tool_args: Optional[dict[str, Any]] = None,
+    ) -> SkillResult:
+        """Execute a skill by name.
+
+        Raises:
+            SkillNotFoundError: the name has no registered manifest.
+            RuntimeError:       no provider supports the manifest.
+        """
+        manifest = self._manifests.get(skill_name)
+        if manifest is None:
+            raise SkillNotFoundError(skill_name)
+        for provider in self.providers:
+            if provider.supports(manifest):
+                result = await provider.invoke(manifest, context, tool_args)
+                result.skill_name = skill_name  # dispatched name wins over a generic tool name
+                logger.debug("event=skill_invoked name=%s provider=%s status=%s",
+                             skill_name, manifest.provider_type, result.status)
+                return result
+        raise RuntimeError(f"no provider supports skill '{skill_name}'")

cogno_cortex/dispatcher.py

@@ -0,0 +1,90 @@
+"""``CortexDispatcher`` — the bridge from skills to cogno-anima's tool contract.
+
+This is the keystone: it implements cogno-anima's ``ToolDispatcher`` (and
+``ToolPolicyDispatcher``), so the EGO / cogno-soma see skills as ordinary tools and
+never know what a "skill" is. ``tools_schema()`` renders the selected manifests as
+OpenAI tool defs; ``execute()`` runs the skill via the bus and maps ``SkillResult``
+→ ``ToolResult``; the policy methods read the manifest's ``mutating`` / ``destructive``
+flags so the EGO's read-only mask and confirmation gate work for skills too.
+
+The host ranks skills first (``SkillRegistry.rank`` against the NER tags) and passes
+the chosen ``names`` — or omits them to expose all registered skills. A skill is
+NOT a tool: it is a richer thing (manifest + provider + impl) that *resolves to* one
+tool here. The ``ToolDispatcher`` contract is the unifier; merge cortex with an MCP
+or native dispatcher via ``cogno_anima.tools.CompositeDispatcher``.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional, Sequence
+
+from cogno_anima.types import ToolResult
+
+from cogno_cortex.base import ToolContext
+from cogno_cortex.bus import SkillBus, SkillNotFoundError
+from cogno_cortex.registry import SkillRegistry
+
+
+class CortexDispatcher:
+    """A cogno-anima ``ToolDispatcher`` (+ ``ToolPolicyDispatcher``) backed by skills."""
+
+    def __init__(
+        self,
+        registry: SkillRegistry,
+        bus: SkillBus,
+        *,
+        names: Optional[Sequence[str]] = None,
+        backend: Any = None,
+        metadata: Optional[dict] = None,
+        trace_id: str = "",
+    ) -> None:
+        """
+        Args:
+            registry:  source of manifests (for schemas + policy flags).
+            bus:       executes the skills (must have a provider + the manifests registered).
+            names:     the skill names to expose this turn (e.g. ``registry.rank(tags)``);
+                       ``None`` → expose every registered skill.
+            backend:   the ``LLMBackend`` injected into each skill's ``ToolContext``.
+            metadata:  extra context handed to every skill (domains, user query, ...).
+            trace_id:  correlation id stamped on the ``ToolContext``.
+        """
+        self._registry = registry
+        self._bus = bus
+        self._names = list(names) if names is not None else registry.skill_names()
+        self._backend = backend
+        self._metadata = metadata or {}
+        self._trace_id = trace_id
+
+    def _manifest(self, name: str):
+        return self._registry.get(name)
+
+    def tools_schema(self) -> list[dict]:
+        schemas = []
+        for name in self._names:
+            m = self._manifest(name)
+            if m is not None:
+                schemas.append(m.to_tool_schema())
+        return schemas
+
+    async def execute(self, name: str, arguments: dict) -> ToolResult:
+        context = ToolContext(backend=self._backend, trace_id=self._trace_id,
+                              metadata=dict(self._metadata))
+        try:
+            result = await self._bus.invoke(name, context, tool_args=arguments)
+        except SkillNotFoundError:
+            # hallucinated / unknown tool name → recoverable, EGO self-corrects
+            return ToolResult(output="", ok=False, error=f"unknown tool: {name}")
+        manifest = self._manifest(name)
+        side_effect = bool(manifest.mutating) if manifest else False
+        if result.ok:
+            return ToolResult(output=str(result.payload), ok=True, side_effect=side_effect)
+        return ToolResult(output="", ok=False, error=str(result.payload), side_effect=side_effect)
+
+    # ── ToolPolicyDispatcher ──────────────────────────────────────────────
+    def is_mutating(self, name: str) -> bool:
+        m = self._manifest(name)
+        return bool(m.mutating) if m else True  # unknown → conservative (masked read-only)
+
+    def requires_confirmation(self, name: str) -> bool:
+        m = self._manifest(name)
+        return bool(m.destructive) if m else False

cogno_cortex/loader.py

@@ -0,0 +1,128 @@
+"""``SkillLoader`` — discover on-disk skills (``SKILL.md`` + a ``BaseTool``).
+
+A skill directory contains a ``SKILL.md`` (YAML-ish frontmatter: name/description/
+tags/... + operational instructions in the body) and one or more ``.py`` files with
+a ``BaseTool`` subclass. ``discover`` scans a root for such directories and returns
+``SkillManifest``s (with ``tool_class`` wired to the found ``BaseTool`` and
+``skill_instructions`` set to the SKILL.md body). ``register_all`` loads them into a
+registry + bus. The XDG/builtins hardcoded paths of the parent are dropped — the
+host passes the directories it wants.
+
+Frontmatter parsing mirrors cogno-persona's loader (simple ``key: value`` + ``- list``).
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import inspect
+import logging
+import re
+from pathlib import Path
+from typing import Optional, Type
+
+from cogno_cortex.base import BaseTool
+from cogno_cortex.bus import SkillBus
+from cogno_cortex.registry import SkillRegistry
+from cogno_cortex.types import SkillManifest
+
+logger = logging.getLogger(__name__)
+
+_FRONTMATTER_RE = re.compile(r"\A---\s*\n(.*?)\n---\s*\n?(.*)\Z", re.DOTALL)
+_BOOL_TRUE = {"true", "yes", "1"}
+
+
+def parse_frontmatter(text: str) -> tuple[dict, str]:
+    """Split ``---``-delimited frontmatter from the body. Returns ``(meta, body)``."""
+    m = _FRONTMATTER_RE.match(text)
+    if not m:
+        return {}, text
+    raw, body = m.group(1), m.group(2)
+    meta: dict = {}
+    key: Optional[str] = None
+    for line in raw.splitlines():
+        if not line.strip():
+            continue
+        list_item = re.match(r"\s*-\s+(.*)", line)
+        if list_item and key is not None and isinstance(meta.get(key), list):
+            meta[key].append(list_item.group(1).strip().strip("'\""))
+            continue
+        kv = re.match(r"([A-Za-z0-9_]+)\s*:\s*(.*)", line)
+        if not kv:
+            continue
+        key, val = kv.group(1), kv.group(2).strip()
+        if val == "":
+            meta[key] = []          # a list follows on the next lines
+        else:
+            meta[key] = val.strip("'\"")
+    return meta, body.strip()
+
+
+def _find_tool_class(skill_dir: Path) -> Optional[Type[BaseTool]]:
+    """Import the .py files in ``skill_dir`` and return the first ``BaseTool`` subclass."""
+    for py in sorted(skill_dir.glob("*.py")):
+        if py.name == "__init__.py":
+            continue
+        spec = importlib.util.spec_from_file_location(f"_cortex_skill_{py.stem}", py)
+        if spec is None or spec.loader is None:
+            continue
+        module = importlib.util.module_from_spec(spec)
+        try:
+            spec.loader.exec_module(module)
+        except Exception as exc:  # noqa: BLE001 — a broken skill file must not crash discovery
+            logger.warning("event=skill_import_failed file=%s error=%s", py.name, exc)
+            continue
+        for _, obj in inspect.getmembers(module, inspect.isclass):
+            if issubclass(obj, BaseTool) and obj.__module__ == module.__name__:
+                return obj
+    return None
+
+
+def load_skill_dir(skill_dir: Path) -> Optional[SkillManifest]:
+    """Build a ``SkillManifest`` from one skill directory (needs a ``SKILL.md``)."""
+    md = skill_dir / "SKILL.md"
+    if not md.exists():
+        return None
+    meta, body = parse_frontmatter(md.read_text(encoding="utf-8"))
+    name = meta.get("name") or skill_dir.name
+    tool_class = _find_tool_class(skill_dir)
+    raw_tags = meta.get("tags", [])
+    if isinstance(raw_tags, list):
+        tags: list[str] = [str(t) for t in raw_tags]
+    else:
+        tags = [t.strip() for t in str(raw_tags).split(",") if t.strip()]
+    return SkillManifest(
+        name=name,
+        description=meta.get("description", ""),
+        tags=tags,
+        version=meta.get("version", "0.1.0"),
+        provider_type=meta.get("provider", "local"),
+        priority=int(meta.get("priority", 5)),
+        mutating=str(meta.get("mutating", "false")).lower() in _BOOL_TRUE,
+        destructive=str(meta.get("destructive", "false")).lower() in _BOOL_TRUE,
+        tool_class=tool_class,
+        skill_instructions=body,
+        metadata={"source_dir": str(skill_dir)},
+    )
+
+
+def discover(root: Path | str) -> list[SkillManifest]:
+    """Discover all skills under ``root`` (each immediate subdir with a ``SKILL.md``)."""
+    root = Path(root)
+    manifests: list[SkillManifest] = []
+    if not root.is_dir():
+        return manifests
+    for child in sorted(root.iterdir()):
+        if child.is_dir():
+            man = load_skill_dir(child)
+            if man is not None:
+                manifests.append(man)
+    return manifests
+
+
+def register_all(
+    manifests: list[SkillManifest], registry: SkillRegistry, bus: SkillBus,
+) -> None:
+    """Register every manifest in both the registry (ranking) and the bus (dispatch)."""
+    for man in manifests:
+        registry.register(man)
+        bus.register_manifest(man)

cogno_cortex/registry.py

@@ -0,0 +1,83 @@
+"""``SkillRegistry`` — tag-based skill matching and ranking (pure, no I/O).
+
+Ranks registered manifests against NER-extracted tags (domains + mandatory_tags +
+intent hints) so the host can pick the most relevant skills to expose to the EGO.
+Ported from the parent ``cogno.skills.registry``.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from cogno_cortex.types import SkillManifest
+
+
+class SkillRegistry:
+    """Holds ``SkillManifest``s and ranks them by tag overlap.
+
+    Ranking (descending): direct name match (+100) → tag overlap (+10 each) →
+    tie-break by (priority, performance_rating).
+    """
+
+    def __init__(self) -> None:
+        self._manifests: list[SkillManifest] = []
+
+    def register(self, manifest: SkillManifest) -> None:
+        # replace an existing manifest of the same name (idempotent re-register)
+        self._manifests = [m for m in self._manifests if m.name != manifest.name]
+        self._manifests.append(manifest)
+
+    def get(self, name: str) -> Optional[SkillManifest]:
+        for m in self._manifests:
+            if m.name == name:
+                return m
+        return None
+
+    @property
+    def manifests(self) -> list[SkillManifest]:
+        return list(self._manifests)
+
+    def skill_names(self) -> list[str]:
+        return [m.name for m in self._manifests]
+
+    @staticmethod
+    def _normalize_tags(tags: list[str]) -> set[str]:
+        """Lowercase + strip a ``NER.`` prefix (NER emits ``NER.MATH`` → ``math``)."""
+        out: set[str] = set()
+        for tag in tags:
+            low = tag.lower()
+            out.add(low)
+            if low.startswith("ner."):
+                out.add(low[4:])
+        return out
+
+    def rank(self, tags: list[str], *, max_results: int = 3) -> list[str]:
+        """Return up to ``max_results`` skill names ordered by relevance to ``tags``."""
+        tags_set = self._normalize_tags(tags)
+        scored: list[tuple[tuple[int, int, float], SkillManifest]] = []
+        for m in self._manifests:
+            score = 0
+            if m.name.lower() in tags_set:
+                score += 100
+            overlap = {t.lower() for t in m.tags} & tags_set
+            score += len(overlap) * 10
+            if score > 0:
+                scored.append(((score, m.priority, m.performance_rating), m))
+        scored.sort(key=lambda x: x[0], reverse=True)
+        return [m.name for _, m in scored[:max_results]]
+
+    def apply_feedback(self, skill_name: str, feedback: str) -> None:
+        """Nudge a skill's ``performance_rating`` from execution feedback.
+
+        ``good`` → +0.1, ``bad`` → −0.1, ``dangerous`` → −0.3 (clamped to [0,1]).
+        """
+        m = self.get(skill_name)
+        if m is None:
+            return
+        fb = feedback.lower()
+        if fb == "good":
+            m.performance_rating = min(1.0, m.performance_rating + 0.1)
+        elif fb == "bad":
+            m.performance_rating = max(0.0, m.performance_rating - 0.1)
+        elif fb == "dangerous":
+            m.performance_rating = max(0.0, m.performance_rating - 0.3)

cogno_cortex/types.py

@@ -0,0 +1,115 @@
+"""Data contracts for the skill framework.
+
+``SkillManifest`` — declarative metadata for registry/ranking + the OpenAI tool
+schema the EGO sees. ``SkillResult`` — the structured output a skill returns.
+
+Ported from the parent ``cogno.skills.types`` with the infra-leaning fields
+trimmed (XDG paths, sub-doc dirs) and two policy flags added (``mutating`` /
+``destructive``) so a :class:`~cogno_cortex.dispatcher.CortexDispatcher` can satisfy
+cogno-anima's ``ToolPolicyDispatcher`` and drive the EGO's read-only / confirmation
+gates.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Optional
+
+
+@dataclass
+class SkillManifest:
+    """Declarative metadata for a registered skill.
+
+    Args:
+        name:               Unique skill identifier (e.g. "math", "search").
+        description:        One-line capability summary (shown to the model).
+        tags:               Discovery tags — matched against NER domains/mandatory_tags.
+        parameters:         JSON-Schema for the tool's arguments (OpenAI format). Empty
+                            dict → a minimal ``{query: string}`` schema.
+        version:            Semver string.
+        provider_type:      Execution backend label ("local", "shell", "http", ...).
+        priority:           Tie-breaker for equally-scored skills (higher = preferred).
+        performance_rating: Adaptive quality score (0..1), nudged by ``apply_feedback``.
+        tool_class:         The ``BaseTool`` subclass that implements this skill (for the
+                            in-process ``LocalProvider``); ``None`` for provider-only skills.
+        skill_instructions: Operational instructions (from SKILL.md) the model may read.
+        mutating:           True if the skill writes / causes a side effect (drives the
+                            EGO read-only mask).
+        destructive:        True if the skill is dangerous and must be confirmed first
+                            (drives the EGO confirmation gate).
+        pricing_model:      "free" | "per_call" (metadata; metering is cogno-meter's job).
+        unit_cost:          Cost per invocation (metadata only).
+        timeout_seconds:    Advisory max execution time.
+        metadata:           Free-form extra (model name, source dir, etc.).
+    """
+
+    name: str
+    description: str = ""
+    tags: list[str] = field(default_factory=list)
+    parameters: dict[str, Any] = field(default_factory=dict)
+    version: str = "0.1.0"
+    provider_type: str = "local"
+    priority: int = 5
+    performance_rating: float = 0.5
+    tool_class: Optional[Any] = None
+    skill_instructions: str = ""
+    mutating: bool = False
+    destructive: bool = False
+    pricing_model: str = "free"
+    unit_cost: float = 0.0
+    timeout_seconds: float = 30.0
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def to_tool_schema(self) -> dict[str, Any]:
+        """Render this manifest as an OpenAI function-calling tool definition.
+
+        With no ``parameters`` declared, falls back to a minimal ``{query: string}``
+        schema (the skill reads the raw user query).
+        """
+        params = self.parameters or {
+            "type": "object",
+            "properties": {
+                "query": {"type": "string",
+                          "description": "The user's query or input for this tool"}
+            },
+            "required": ["query"],
+        }
+        return {
+            "type": "function",
+            "function": {
+                "name": self.name,
+                "description": self.description,
+                "parameters": params,
+            },
+        }
+
+
+@dataclass
+class SkillResult:
+    """Structured output from a skill execution.
+
+    Args:
+        skill_name:    Which skill produced this result.
+        payload:       The actual output (text / JSON-serialisable value).
+        status:        "success" | "error" | "blocked".
+        evidence:      Strings explaining what was done.
+        risks:         Risk strings (empty if safe).
+        confidence:    0..1 confidence in result quality.
+        provider_type: Execution backend used.
+        usage:         Token usage if an LLM was involved ({"tokens_in", "tokens_out"}).
+        metadata:      Extra context (model name, etc.).
+    """
+
+    skill_name: str
+    payload: Any
+    status: str = "success"
+    evidence: list[str] = field(default_factory=list)
+    risks: list[str] = field(default_factory=list)
+    confidence: float = 1.0
+    provider_type: str = "local"
+    usage: dict[str, int] = field(default_factory=dict)
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def ok(self) -> bool:
+        return self.status == "success"

cogno_cortex-0.1.0.dist-info/METADATA

@@ -0,0 +1,158 @@
+Metadata-Version: 2.4
+Name: cogno-cortex
+Version: 0.1.0
+Summary: The in-process skills framework for the Cogno stack — author skills as BaseTool + manifest, rank them against NER tags, execute via a provider bus, discover from disk, and bridge to cogno-anima's tool contract via CortexDispatcher. The framework, not the skills; infra-agnostic.
+Author: Vinicius Vale
+Maintainer: Sudoers AI
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/sudoers-ai/cogno-cortex
+Project-URL: Repository, https://github.com/sudoers-ai/cogno-cortex
+Project-URL: Issues, https://github.com/sudoers-ai/cogno-cortex/issues
+Keywords: skills,tools,agents,function-calling,cogno,llm
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Operating System :: OS Independent
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic>=2.0
+Requires-Dist: cogno-anima<0.2,>=0.1
+Requires-Dist: cogno-synapse<0.2,>=0.1
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Requires-Dist: mypy>=1.8; extra == "dev"
+Dynamic: license-file
+
+# cogno-cortex
+
+**The in-process skills framework for the Cogno stack.**
+
+A *skill* is a richer thing than a tool: a `BaseTool` implementation **+** a
+`SkillManifest` (tags, policy flags, instructions) for discovery and ranking.
+cortex is the layer that authors, discovers, ranks and executes skills — and then
+**bridges them to a plain tool** via `CortexDispatcher`, so the EGO / `cogno-soma`
+see ordinary tools and never know what a "skill" is.
+
+cortex ships the **framework, not the skills** (like `cogno-persona` ships the
+store, not the personas). It is infra-agnostic: in-process execution only; shell /
+http / remote providers are a host seam.
+
+```
+SKILL.md + BaseTool ─▶ SkillRegistry.rank(NER tags) ─▶ CortexDispatcher
+                                                              │ (implements
+                                                              ▼  cogno-anima's
+                                              soma.run_turn(dispatcher=…) → EGO
+                                                                 ToolDispatcher)
+```
+
+## Install
+
+```bash
+pip install cogno-cortex      # pulls cogno-anima + cogno-synapse + pydantic
+```
+
+> The sibling cogno libs are not on PyPI yet — install them from git first
+> (`cogno-homeo`, `cogno-synapse`, `cogno-anima`); see `.github/workflows/ci.yml`.
+
+## Author a skill
+
+```python
+from cogno_cortex import BaseTool, SkillResult, ToolContext
+
+class MathTool(BaseTool):
+    a: float
+    op: str          # the Pydantic fields ARE the tool arguments
+    b: float
+
+    @property
+    def name(self): return "math"
+    @property
+    def description(self): return "Basic arithmetic."
+
+    async def run(self, ctx: ToolContext) -> SkillResult:
+        val = {"+": self.a + self.b, "*": self.a * self.b}[self.op]
+        return SkillResult(skill_name=self.name, payload=val)
+```
+
+Pair it with a `SKILL.md` (frontmatter: `name`, `description`, `tags`, `priority`,
+`mutating`, `destructive` + operational instructions in the body) in a directory,
+and `discover()` loads it.
+
+## Wire it to the EGO
+
+```python
+from cogno_cortex import (SkillRegistry, SkillBus, LocalProvider,
+                          CortexDispatcher, discover, register_all)
+
+registry, bus = SkillRegistry(), SkillBus()
+bus.register_provider(LocalProvider())
+register_all(discover("./skills"), registry, bus)
+
+chosen = registry.rank(ctx.intent.domains + ctx.intent.mandatory_tags)   # NER-driven
+dispatcher = CortexDispatcher(registry, bus, names=chosen, backend=llm_backend)
+
+# hand it straight to cogno-soma:
+await pipe.run_turn(ctx, cfg, dispatcher=dispatcher)
+```
+
+`CortexDispatcher` implements cogno-anima's `ToolDispatcher` **and**
+`ToolPolicyDispatcher`: `tools_schema()` renders the chosen manifests; `execute()`
+runs the skill and maps `SkillResult → ToolResult`; `is_mutating` / `requires_confirmation`
+read the manifest flags so the EGO's read-only mask + confirmation gate work for
+skills too.
+
+## Skills + MCP + native tools together
+
+A persona may draw tools from several sources at once. Each source is a
+`ToolDispatcher`; merge them with `cogno_anima.tools.CompositeDispatcher`:
+
+```python
+from cogno_anima.tools import CompositeDispatcher
+dispatcher = CompositeDispatcher([cortex_dispatcher, mcp_dispatcher, native_dispatcher])
+```
+
+The `ToolDispatcher` contract is the unifier — skill / MCP / native are just
+sources behind it. The persona declares modules **by name**; the host resolves each
+to a source and composes.
+
+## What stays at the host
+
+The concrete skills (shell/web/browser/...), shell/http/remote **providers**
+(subprocess/network + security), persona selection, metering (`cogno-meter`), RBAC.
+cortex is the framework; the host plugs providers via the `SkillProvider` Protocol.
+
+## The Cogno ecosystem
+
+`cogno-cortex` is one organ of **[Cogno](https://github.com/sudoers-ai)** — a family of
+small, composable, Apache-2.0 libraries that together form a complete
+conversational-agent platform. Each library owns a single concern and stays
+infra-agnostic; a **host** assembles them into a running agent:
+
+![The Cogno ecosystem](docs/assets/cogno-ecosystem.svg)
+
+The open-source libraries are the organs; the **host is the body** that joins
+them. Our reference host — `cogno-host`, with its `cogno-ui` dashboard — is the
+private product layer, but it holds no special powers: everything it does rides
+on the public seams documented in each library's `docs/HOST_INTEGRATION.md`, so
+you can assemble a body of your own.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest tests/unit -q            # fast, no network
+pytest tests/integration -q     # real EGO over Ollama, auto-skips if absent
+ruff check cogno_cortex tests && mypy cogno_cortex
+python examples/host_min.py     # offline demo: discover → rank → bridge → execute
+```
+
+Apache-2.0.

cogno_cortex-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+cogno_cortex/__init__.py,sha256=8-HrG2Ctk5cl86L0YRA58qDeuICWCGeIXKW6uXAqQRs,1320
+cogno_cortex/base.py,sha256=-FqMz0bwidyzkOgQy9ocajB2aQ31PS2mXI6BHEjM2Lc,3462
+cogno_cortex/bus.py,sha256=4HDNkkn-KUkdNz-PyAdQdII98d6GGUxjQGGE1MtcVZ0,3562
+cogno_cortex/dispatcher.py,sha256=i3WPr-bEgbAI9GAWoNQtSCiTMzTEtOtcggKWDxJ9Pf4,4114
+cogno_cortex/loader.py,sha256=0Jfty2kMFdKd6kjj7RN3N1tFINVF8H3e_83iQ6umukg,4928
+cogno_cortex/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cogno_cortex/registry.py,sha256=2rvzeCAVUoZlBE8TN18zi_bZ9xqr-hIbutNFNp9t7BM,3080
+cogno_cortex/types.py,sha256=6VAtFJmqrzOtVns0sUXiMhLBJKBbBFFv8IevIwrcwFI,4731
+cogno_cortex-0.1.0.dist-info/licenses/LICENSE,sha256=4cK96oGhr1hZsZT3Bo5cnKQ3mx6DJ0u8XuTtJ-TNuso,11340
+cogno_cortex-0.1.0.dist-info/METADATA,sha256=L-gufCPTJ12lsx-UVPPSVsVnGikKk5RUpSPRp819jMo,6387
+cogno_cortex-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+cogno_cortex-0.1.0.dist-info/top_level.txt,sha256=VmKptl32sT1wMSV5ysQ2xnGqKsyzZkKa75CFzzvhv54,13
+cogno_cortex-0.1.0.dist-info/RECORD,,

cogno_cortex-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

cogno_cortex-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Sudoers AI
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

cogno_cortex-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+cogno_cortex