agskillmanager 1.0.0__py3-none-any.whl

skill_manager/config.py

@@ -0,0 +1,33 @@
+"""Immutable Skill Manager policy and limit configuration."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class SkillManagerConfig(BaseModel):
+    """Policy switches and resource limits for one `SkillManager`.
+
+    Attributes:
+        allow_agent_skill_creation: Accept agent-generated Skills at all.
+        require_human_approval: Hold agent-generated Skills in
+            ``PENDING_APPROVAL`` until a reviewer approves them.
+        max_document_bytes: Largest Skill YAML document a source may supply.
+        capability_candidate_limit: Candidates requested from
+            `MCPRuntime.retrieve` per required capability name.
+        capability_cache_size: Resolved capabilities kept between bundle builds.
+        feedback_context_limit: Rejection events passed to a `SkillGenerator`
+            when it revises a parent Skill.
+        error_history_size: Observability and XAI failures retained on
+            `SkillManager.observability_errors`.
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    allow_agent_skill_creation: bool = True
+    require_human_approval: bool = False
+    max_document_bytes: int = Field(default=1_000_000, ge=1)
+    capability_candidate_limit: int = Field(default=50, ge=1)
+    capability_cache_size: int = Field(default=1024, ge=0)
+    feedback_context_limit: int = Field(default=20, ge=0)
+    error_history_size: int = Field(default=100, ge=1)

skill_manager/discovery.py

@@ -0,0 +1,345 @@
+"""Composable retrieval and reranking for bounded Skill discovery."""
+
+from __future__ import annotations
+
+import asyncio
+import math
+import re
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+from skill_manager.errors import SkillDiscoveryError
+from skill_manager.models import Skill, SkillLifecycleState
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping, Sequence
+
+    from mcp_capability_router import Embedder
+
+_TOKEN_PATTERN = re.compile(r"[a-z0-9][a-z0-9_.]*", re.IGNORECASE)
+_FILTER_KEYS = frozenset({"name", "version", "tag", "capability"})
+
+
+@dataclass(frozen=True, slots=True)
+class RetrievedSkill:
+    """A retrieved Skill candidate and its backend-specific relevance score."""
+
+    skill: Skill
+    score: float
+
+
+class SkillRetriever(ABC):
+    """Extension point that indexes Skills and returns scored candidates.
+
+    `PipelineDiscoveryProvider` calls `index` whenever the catalog changes and
+    `retrieve` for each query. Return only ``ACTIVE`` Skills that satisfy
+    ``filters``; use `matches_filters` to apply them.
+    """
+
+    @abstractmethod
+    async def index(self, skills: Sequence[Skill]) -> None:
+        """Replace the retriever's catalog snapshot."""
+
+    @abstractmethod
+    async def retrieve(
+        self,
+        query: str,
+        *,
+        limit: int,
+        filters: Mapping[str, Any] | None = None,
+    ) -> list[RetrievedSkill]:
+        """Return at most ``limit`` active, filtered candidates."""
+
+
+class SkillReranker(ABC):
+    """Extension point that orders retrieved candidates into the final result."""
+
+    @abstractmethod
+    async def rerank(
+        self,
+        query: str,
+        candidates: Sequence[RetrievedSkill],
+        *,
+        top_k: int,
+    ) -> list[Skill]:
+        """Return at most ``top_k`` of ``candidates`` in final relevance order."""
+
+
+class DiscoveryProvider(ABC):
+    """Extension point for indexed, bounded Skill discovery.
+
+    `SkillManager` keeps the provider's index in sync with the catalog and calls
+    `discover` from `SkillManager.discover`.
+    """
+
+    @abstractmethod
+    async def index(self, skills: Sequence[Skill]) -> None:
+        """Replace the discoverable catalog snapshot."""
+
+    @abstractmethod
+    async def discover(
+        self,
+        query: str,
+        *,
+        top_k: int = 5,
+        filters: Mapping[str, Any] | None = None,
+    ) -> list[Skill]:
+        """Return at most ``top_k`` active candidates."""
+
+
+def validate_filters(filters: Mapping[str, Any] | None) -> None:
+    """Raise `SkillDiscoveryError` when ``filters`` uses an unsupported key.
+
+    Supported keys are ``name``, ``version``, ``tag`` and ``capability``.
+    """
+    if filters:
+        unknown = sorted(set(filters) - _FILTER_KEYS)
+        if unknown:
+            raise SkillDiscoveryError(f"unsupported Skill discovery filters: {unknown}")
+
+
+def matches_filters(skill: Skill, filters: Mapping[str, Any] | None) -> bool:
+    """Return whether ``skill`` is ``ACTIVE`` and satisfies every filter."""
+    if skill.lifecycle.state is not SkillLifecycleState.ACTIVE:
+        return False
+    if not filters:
+        return True
+    checks = {
+        "name": lambda expected: skill.metadata.name == expected,
+        "version": lambda expected: skill.metadata.version == expected,
+        "tag": lambda expected: expected in skill.metadata.tags,
+        "capability": lambda expected: any(item.name == expected for item in skill.capabilities),
+    }
+    return all(checks[key](expected) for key, expected in filters.items())
+
+
+def skill_document(skill: Skill) -> str:
+    """Return the text that retrievers index for ``skill``."""
+    return "\n".join(
+        (
+            skill.metadata.name,
+            skill.metadata.description,
+            " ".join(skill.metadata.tags),
+            "\n".join(skill.instructions),
+            " ".join(capability.name for capability in skill.capabilities),
+        )
+    )
+
+
+def _active(skills: Sequence[Skill]) -> tuple[Skill, ...]:
+    return tuple(skill for skill in skills if skill.lifecycle.state is SkillLifecycleState.ACTIVE)
+
+
+def _check_limit(limit: int) -> None:
+    if limit < 1:
+        raise SkillDiscoveryError("retrieval limit must be at least 1")
+
+
+def _top(retrieved: list[RetrievedSkill], limit: int) -> list[RetrievedSkill]:
+    retrieved.sort(key=lambda item: (-item.score, item.skill.skill_id))
+    return retrieved[:limit]
+
+
+class LexicalSkillRetriever(SkillRetriever):
+    """Deterministic inverted-index retrieval over Skill text.
+
+    The score is the number of distinct query terms found in a Skill. An empty
+    query matches every active Skill with score zero.
+    """
+
+    def __init__(self) -> None:
+        self._skills: tuple[Skill, ...] = ()
+        self._tokens: dict[str, frozenset[str]] = {}
+        self._postings: dict[str, frozenset[str]] = {}
+
+    async def index(self, skills: Sequence[Skill]) -> None:
+        """Tokenize every active Skill and rebuild the inverted index."""
+        active = _active(skills)
+        tokens = {
+            skill.skill_id: frozenset(_TOKEN_PATTERN.findall(skill_document(skill).lower()))
+            for skill in active
+        }
+        postings: dict[str, set[str]] = {}
+        for skill_id, skill_tokens in tokens.items():
+            for token in skill_tokens:
+                postings.setdefault(token, set()).add(skill_id)
+        self._skills = active
+        self._tokens = tokens
+        self._postings = {token: frozenset(ids) for token, ids in postings.items()}
+
+    async def retrieve(
+        self,
+        query: str,
+        *,
+        limit: int,
+        filters: Mapping[str, Any] | None = None,
+    ) -> list[RetrievedSkill]:
+        """Return the active Skills sharing the most terms with ``query``."""
+        _check_limit(limit)
+        validate_filters(filters)
+        terms = frozenset(_TOKEN_PATTERN.findall(query.lower()))
+        if terms:
+            ids = frozenset().union(*(self._postings.get(term, frozenset()) for term in terms))
+            candidates = [skill for skill in self._skills if skill.skill_id in ids]
+        else:
+            candidates = list(self._skills)
+        return _top(
+            [
+                RetrievedSkill(skill, float(len(terms & self._tokens[skill.skill_id])))
+                for skill in candidates
+                if matches_filters(skill, filters)
+            ],
+            limit,
+        )
+
+
+def _unit(vector: Sequence[float]) -> tuple[float, ...]:
+    norm = math.sqrt(math.fsum(value * value for value in vector))
+    return tuple(value / norm for value in vector) if norm else tuple(0.0 for _ in vector)
+
+
+class SemanticSkillRetriever(SkillRetriever):
+    """Dense cosine-similarity retrieval backed by an injected `Embedder`.
+
+    Any `mcp_capability_router.Embedder` works. With the ``langchain`` extra,
+    `skill_manager.integrations.langchain.LangChainEmbedder` adapts every
+    LangChain ``Embeddings``.
+    """
+
+    def __init__(self, embedder: Embedder) -> None:
+        self._embedder = embedder
+        self._entries: tuple[tuple[Skill, tuple[float, ...]], ...] = ()
+        self._index_lock = asyncio.Lock()
+
+    async def index(self, skills: Sequence[Skill]) -> None:
+        """Embed every active Skill and store unit-length vectors."""
+        active = _active(skills)
+        try:
+            vectors = await self._embedder.embed_documents([skill_document(s) for s in active])
+        except Exception as error:
+            raise SkillDiscoveryError("semantic Skill index embedding failed") from error
+        if len(vectors) != len(active):
+            raise SkillDiscoveryError("embedder returned a different number of vectors")
+        async with self._index_lock:
+            self._entries = tuple(
+                (skill, _unit(vector)) for skill, vector in zip(active, vectors, strict=True)
+            )
+
+    async def retrieve(
+        self,
+        query: str,
+        *,
+        limit: int,
+        filters: Mapping[str, Any] | None = None,
+    ) -> list[RetrievedSkill]:
+        """Return the active Skills closest to ``query`` by cosine similarity."""
+        _check_limit(limit)
+        validate_filters(filters)
+        async with self._index_lock:
+            entries = self._entries
+        try:
+            query_vector = _unit(await self._embedder.embed_query(query))
+        except Exception as error:
+            raise SkillDiscoveryError("semantic Skill query embedding failed") from error
+        try:
+            return _top(
+                [
+                    RetrievedSkill(
+                        skill,
+                        math.fsum(a * b for a, b in zip(query_vector, vector, strict=True)),
+                    )
+                    for skill, vector in entries
+                    if matches_filters(skill, filters)
+                ],
+                limit,
+            )
+        except ValueError as error:
+            raise SkillDiscoveryError("query and index vectors differ in dimension") from error
+
+
+class ScoreSkillReranker(SkillReranker):
+    """Order candidates by retrieval score, breaking ties by Skill ID."""
+
+    async def rerank(
+        self,
+        query: str,
+        candidates: Sequence[RetrievedSkill],
+        *,
+        top_k: int,
+    ) -> list[Skill]:
+        """Return the ``top_k`` highest-scoring Skills."""
+        del query
+        return [item.skill for item in _top(list(candidates), top_k)]
+
+
+class PipelineDiscoveryProvider(DiscoveryProvider):
+    """Compose a retriever and a reranker into bounded, verified discovery.
+
+    The provider asks the retriever for ``max(top_k, candidate_pool_size)``
+    candidates, reranks them, and checks that neither stage exceeded its limit,
+    invented a Skill, or returned an inactive or filtered-out Skill.
+
+    Args:
+        retriever: Candidate source; defaults to `LexicalSkillRetriever`.
+        reranker: Final ordering; defaults to `ScoreSkillReranker`.
+        candidate_pool_size: Minimum number of candidates to rerank.
+    """
+
+    def __init__(
+        self,
+        retriever: SkillRetriever | None = None,
+        *,
+        reranker: SkillReranker | None = None,
+        candidate_pool_size: int = 50,
+    ) -> None:
+        if candidate_pool_size < 1:
+            raise ValueError("candidate_pool_size must be at least 1")
+        self._retriever = retriever if retriever is not None else LexicalSkillRetriever()
+        self._reranker = reranker if reranker is not None else ScoreSkillReranker()
+        self._candidate_pool_size = candidate_pool_size
+
+    async def index(self, skills: Sequence[Skill]) -> None:
+        """Forward the catalog snapshot to the retriever."""
+        await self._retriever.index(skills)
+
+    async def discover(
+        self,
+        query: str,
+        *,
+        top_k: int = 5,
+        filters: Mapping[str, Any] | None = None,
+    ) -> list[Skill]:
+        """Retrieve, rerank and verify at most ``top_k`` Skills."""
+        if top_k < 1:
+            raise SkillDiscoveryError("top_k must be at least 1")
+        validate_filters(filters)
+        limit = max(top_k, self._candidate_pool_size)
+        candidates = await self._retriever.retrieve(query, limit=limit, filters=filters)
+        if len(candidates) > limit:
+            raise SkillDiscoveryError("Skill retriever returned more than its candidate limit")
+        allowed = tuple(item for item in candidates if matches_filters(item.skill, filters))
+        ranked = await self._reranker.rerank(query, allowed, top_k=top_k)
+        if len(ranked) > top_k:
+            raise SkillDiscoveryError("Skill reranker returned more than top_k candidates")
+        by_id = {item.skill.skill_id: item.skill for item in allowed}
+        if len({skill.skill_id for skill in ranked}) != len(ranked) or any(
+            by_id.get(skill.skill_id) != skill for skill in ranked
+        ):
+            raise SkillDiscoveryError("Skill reranker returned an invalid candidate set")
+        return ranked
+
+
+__all__ = [
+    "DiscoveryProvider",
+    "LexicalSkillRetriever",
+    "PipelineDiscoveryProvider",
+    "RetrievedSkill",
+    "ScoreSkillReranker",
+    "SemanticSkillRetriever",
+    "SkillReranker",
+    "SkillRetriever",
+    "matches_filters",
+    "skill_document",
+    "validate_filters",
+]

skill_manager/errors.py

@@ -0,0 +1,83 @@
+"""Skill Manager exception hierarchy.
+
+Every expected failure derives from `SkillManagerError`, so callers can catch
+one base class or a precise subclass.
+"""
+
+from __future__ import annotations
+
+
+class SkillManagerError(Exception):
+    """Base class for expected Skill Manager failures."""
+
+
+class OptionalDependencyError(SkillManagerError, ImportError):
+    """An integration needs an extra that is not installed."""
+
+
+class SkillValidationError(SkillManagerError):
+    """A Skill document or domain value is invalid."""
+
+
+class SkillNotFoundError(SkillManagerError):
+    """No Skill matches the requested immutable ID or name and version."""
+
+
+class SkillSourceError(SkillManagerError):
+    """A Skill source failed to load, persist, or delete a Skill."""
+
+
+class SkillDiscoveryError(SkillManagerError):
+    """Discovery or ranking failed."""
+
+
+class SkillDependencyError(SkillManagerError):
+    """A dependency is missing or its version constraint cannot be satisfied."""
+
+
+class SkillDependencyCycleError(SkillDependencyError):
+    """The dependency graph contains a cycle.
+
+    Attributes:
+        path: Skill names along the cycle, starting and ending with the same name.
+    """
+
+    def __init__(self, path: tuple[str, ...]) -> None:
+        self.path = path
+        super().__init__("Skill dependency cycle: " + " -> ".join(path))
+
+
+class SkillConflictError(SkillManagerError):
+    """Two catalog entries conflict or an update is stale."""
+
+
+class CapabilityResolutionError(SkillManagerError):
+    """A required MCP capability could not be resolved."""
+
+
+class SkillCreationDisabledError(SkillManagerError):
+    """Agent Skill creation is disabled by policy."""
+
+
+class SkillGenerationError(SkillManagerError):
+    """A `SkillGenerator` could not produce a valid Skill."""
+
+
+class SkillGovernanceError(SkillManagerError):
+    """A governance policy does not permit the requested operation."""
+
+
+class SkillApprovalError(SkillManagerError):
+    """Approval could not be completed or persisted."""
+
+
+class SkillRejectionError(SkillManagerError):
+    """Rejection could not be completed or persisted."""
+
+
+class SkillLifecycleError(SkillManagerError):
+    """A Skill lifecycle transition is invalid."""
+
+
+class SkillBundleError(SkillManagerError):
+    """A SkillBundle could not be built."""

skill_manager/generation.py

@@ -0,0 +1,83 @@
+"""Framework-agnostic contract for agent Skill generation."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+    from datetime import datetime
+
+    from skill_manager.models import Skill
+
+
+@dataclass(frozen=True, slots=True)
+class SkillFeedback:
+    """One rejection recorded against a parent Skill revision.
+
+    Attributes:
+        feedback_id: The feedback-manager event ID.
+        payload: The rejection payload, including the reviewer's ``feedback`` text.
+        metadata: Reviewer-supplied metadata.
+        created_at: When the rejection was submitted.
+    """
+
+    feedback_id: str
+    payload: Mapping[str, Any]
+    metadata: Mapping[str, Any]
+    created_at: datetime
+
+
+@dataclass(frozen=True, slots=True)
+class SkillGenerationRequest:
+    """Everything a `SkillGenerator` receives for one generation.
+
+    Attributes:
+        input: The caller's task description, prompt or structured input.
+        parent: The rejected revision being improved, if any.
+        feedback: Rejections of ``parent``, newest first.
+    """
+
+    input: Any
+    parent: Skill | None = None
+    feedback: tuple[SkillFeedback, ...] = field(default=())
+
+
+class SkillGenerator(ABC):
+    """Extension point that turns a request into a candidate Skill.
+
+    Implement it with any model, agent framework or rule engine.
+    `SkillManager.generate_skill` stamps agent provenance, lineage and the
+    lifecycle state on the result, then validates and registers it, so a
+    generator only needs to produce the Skill content. With the ``langchain``
+    extra, `skill_manager.integrations.langchain.XStructuredSkillGenerator`
+    wraps any LangChain chat model.
+
+    Example:
+        ```python
+        class TemplateGenerator(SkillGenerator):
+            async def generate(self, request):
+                return Skill(
+                    metadata=SkillMetadata(name="echo", version="1.0.0", description="Echo."),
+                    instructions=(f"Repeat: {request.input}",),
+                )
+        ```
+    """
+
+    @property
+    def name(self) -> str:
+        """Return the provenance source recorded on generated Skills."""
+        return type(self).__name__
+
+    @abstractmethod
+    async def generate(self, request: SkillGenerationRequest) -> Skill:
+        """Return one candidate Skill.
+
+        Raises:
+            SkillGenerationError: If no valid Skill can be produced.
+        """
+
+
+__all__ = ["SkillFeedback", "SkillGenerationRequest", "SkillGenerator"]

skill_manager/integrations/__init__.py

@@ -0,0 +1 @@
+"""Optional framework integrations; each module needs its matching extra."""

skill_manager/integrations/langchain.py

@@ -0,0 +1,130 @@
+"""LangChain integration: xstructured Skill generation and embeddings.
+
+Install with ``pip install 'agskillmanager[langchain]'``.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping
+from typing import TYPE_CHECKING, Any
+
+from pydantic import Field, model_validator
+
+from skill_manager._optional import optional_import
+from skill_manager.errors import SkillGenerationError
+from skill_manager.generation import SkillGenerationRequest, SkillGenerator
+from skill_manager.models import (
+    FrozenModel,
+    Skill,
+    SkillCapability,
+    SkillDependency,
+    SkillMetadata,
+    SkillReference,
+)
+
+if TYPE_CHECKING:
+    from langchain_core.runnables import Runnable
+
+_xstructured = optional_import("xstructured", "langchain")
+LangChainEmbedder = optional_import(
+    "mcp_capability_router.integrations.langchain", "langchain"
+).LangChainEmbedder
+
+
+def _feedback_payload(request: SkillGenerationRequest) -> list[dict[str, Any]]:
+    return [
+        {
+            "feedback": dict(item.payload),
+            "metadata": dict(item.metadata),
+            "created_at": item.created_at.isoformat(),
+        }
+        for item in request.feedback
+    ]
+
+
+class _SkillDraft(FrozenModel):
+    """The model-authored part of a Skill.
+
+    The ID, revision, provenance, lifecycle and governance belong to the
+    manager, so the model is never asked to invent them.
+    """
+
+    metadata: SkillMetadata
+    instructions: tuple[str, ...]
+    dependencies: tuple[SkillDependency, ...] = ()
+    capabilities: tuple[SkillCapability, ...] = ()
+    resources: tuple[SkillReference, ...] = ()
+    prompts: dict[str, str] = Field(default_factory=dict)
+
+    @model_validator(mode="after")
+    def validate_as_skill(self) -> _SkillDraft:
+        """Apply every Skill rule, so xstructured repair sees the violations."""
+        self.to_skill()
+        return self
+
+    def to_skill(self) -> Skill:
+        """Return a new Skill revision built from the draft."""
+        return Skill(**dict(self))
+
+
+class XStructuredSkillGenerator(SkillGenerator):
+    """Generate a Skill from any LangChain runnable through xstructured.
+
+    xstructured injects the authorable Skill fields (metadata, instructions,
+    dependencies, capabilities, resources and prompts) into the prompt,
+    extracts and validates the JSON answer, and optionally repairs it with
+    ``repair``. The manager assigns the ID, revision and governance.
+    When the request revises a rejected parent, the parent Skill and the
+    reviewer feedback are added to the input: as ``parent_skill`` and
+    ``previous_skill_feedback`` keys for mapping inputs, or as appended text
+    otherwise. Model and transport errors propagate unchanged.
+
+    Args:
+        runnable: The model or chain, for example ``ChatOpenAI(...)``.
+        repair: Optional runnable that repairs invalid output.
+        **options: Any other `xstructured.with_xstructured_output` option,
+            such as ``parser_config``, ``repair_config`` or ``observer``.
+    """
+
+    def __init__(
+        self,
+        runnable: Runnable[Any, Any],
+        *,
+        repair: Runnable[Any, Any] | None = None,
+        **options: Any,
+    ) -> None:
+        self._structured = _xstructured.with_xstructured_output(
+            runnable, _SkillDraft, repair=repair, **options
+        )
+
+    @property
+    def name(self) -> str:
+        """Return ``xstructured``."""
+        return "xstructured"
+
+    async def generate(self, request: SkillGenerationRequest) -> Skill:
+        """Run the structured runnable and return the extracted Skill."""
+        try:
+            result = await self._structured.ainvoke(self._input(request))
+        except _xstructured.XStructuredError as error:
+            raise SkillGenerationError("xstructured could not extract a valid Skill") from error
+        if not isinstance(result.structured, _SkillDraft):
+            raise SkillGenerationError("xstructured returned a value that is not a valid Skill")
+        return result.structured.to_skill()
+
+    @staticmethod
+    def _input(request: SkillGenerationRequest) -> Any:
+        if request.parent is None:
+            return request.input
+        parent = request.parent.model_dump(mode="json")
+        feedback = _feedback_payload(request)
+        if isinstance(request.input, Mapping):
+            return {**request.input, "parent_skill": parent, "previous_skill_feedback": feedback}
+        return (
+            f"{request.input}\n\nRevise this rejected Skill:\n{json.dumps(parent)}"
+            f"\n\nReviewer feedback:\n{json.dumps(feedback)}"
+        )
+
+
+__all__ = ["LangChainEmbedder", "XStructuredSkillGenerator"]