pleiad 0.1.0__py3-none-any.whl

pleiad/agent/agent.py

@@ -0,0 +1,62 @@
+from dataclasses import dataclass, field
+
+from jsonschema import SchemaError
+
+from pleiad.agent.errors import AgentConfigurationError
+from pleiad.agent.policy import AgentPolicyHints
+from pleiad.contracts import JsonSchema, SkillRef, ToolRef, freeze_json_object
+from pleiad.models.anthropic.client import AnthropicModelClient
+from pleiad.models.openai.client import OpenAIModelClient
+from pleiad.schemas import validate_json_schema
+from pleiad.tools.contracts import DEFAULT_TOOL_CODES, default_tool_refs
+
+SUPPORTED_SCHEMA_DIALECT = "https://json-schema.org/draft/2020-12/schema"
+
+
+@dataclass(frozen=True, slots=True)
+class Agent:
+    """Reusable Agent recipe containing only immutable declarations and refs."""
+
+    name: str
+    model: OpenAIModelClient | AnthropicModelClient
+    prompt: str
+    tools: tuple[ToolRef, ...] = ()
+    skills: tuple[SkillRef, ...] = ()
+    output_schema: JsonSchema | None = None
+    policy_hints: AgentPolicyHints = field(default_factory=AgentPolicyHints)
+
+    def __post_init__(self) -> None:
+        """Validate the identity, schema, and capability references."""
+        if not self.name.strip():
+            raise AgentConfigurationError("Agent name must not be blank.")
+        if len(self.name) > 256:
+            raise AgentConfigurationError("Agent name must not exceed 256 characters.")
+        if not isinstance(self.model, OpenAIModelClient | AnthropicModelClient):
+            raise AgentConfigurationError("Agent model must be an OpenAIModelClient or AnthropicModelClient.")
+        if not self.prompt.strip():
+            raise AgentConfigurationError("Agent prompt must not be blank.")
+        explicit_tool_codes = tuple(ref.code for ref in self.tools)
+        if len(explicit_tool_codes) != len(set(explicit_tool_codes)):
+            raise AgentConfigurationError("Agent Tool refs must be unique.")
+        skill_codes = tuple(ref.code for ref in self.skills)
+        if len(skill_codes) != len(set(skill_codes)):
+            raise AgentConfigurationError("Agent Skill refs must be unique.")
+        if self.output_schema is not None:
+            validate_output_schema(self.output_schema)
+            object.__setattr__(self, "output_schema", freeze_json_object(self.output_schema))
+        default_codes = frozenset(DEFAULT_TOOL_CODES)
+        merged_tools = default_tool_refs() + tuple(ref for ref in self.tools if ref.code not in default_codes)
+        object.__setattr__(self, "tools", merged_tools)
+
+
+def validate_output_schema(schema: JsonSchema) -> None:
+    """Validate one local Draft 2020-12 JSON Schema without network resolution."""
+    dialect = schema.get("$schema")
+    if dialect is not None and dialect != SUPPORTED_SCHEMA_DIALECT:
+        raise AgentConfigurationError("Agent output_schema must use the Draft 2020-12 JSON Schema dialect.")
+    try:
+        validate_json_schema(schema)
+    except ValueError as error:
+        raise AgentConfigurationError(str(error)) from error
+    except SchemaError as error:
+        raise AgentConfigurationError("Agent output_schema is invalid.") from error

pleiad/agent/errors.py

@@ -0,0 +1,21 @@
+from pleiad.errors.base import BusinessError, SystemFault
+
+
+class AgentConfigurationError(SystemFault):
+    """Report an invalid Agent definition or unavailable capability binding."""
+
+    def __init__(self, message: str = "The Agent configuration is invalid.") -> None:
+        """Create an Agent configuration fault."""
+        super().__init__("agent.config.invalid", message)
+
+
+class InvalidAgentOutputError(BusinessError):
+    """Report a final model output that violates the Agent contract."""
+
+    def __init__(self, message: str = "The model output does not satisfy the Agent result contract.") -> None:
+        """Create an invalid output error.
+
+        Args:
+            message: Diagnostic description of the invalid output.
+        """
+        super().__init__("agent.output.invalid", message)

pleiad/agent/policy.py

@@ -0,0 +1,18 @@
+from pydantic import ConfigDict, Field
+
+from pleiad.contracts import CapabilityGrants, ContractModel
+
+
+class AgentPolicyHints(ContractModel):
+    """Optional bounds requested by an Agent author.
+
+    Hints are never an authorization grant. The host intersects them with the
+    request and parent policy before a Run starts.
+    """
+
+    model_config = ConfigDict(strict=True)
+
+    timeout_seconds: float | None = Field(default=None, gt=0, allow_inf_nan=False)
+    max_turns: int | None = Field(default=None, gt=0)
+    max_output_tokens: int | None = Field(default=None, gt=0)
+    grants: CapabilityGrants | None = None

pleiad/agent/prompt.py

@@ -0,0 +1,37 @@
+from pleiad.skills.contracts import Skill
+from pleiad.tools.contracts import ToolDescriptor
+
+
+def build_prompt(
+    base_prompt: str,
+    *,
+    tools: tuple[ToolDescriptor, ...],
+    skills: tuple[Skill, ...],
+) -> str:
+    """Compose a prompt from the capabilities visible in the current Run."""
+    sections = [base_prompt.strip()]
+    tool_codes = frozenset(tool.code for tool in tools)
+    guidance: list[str] = []
+    if "read_file" in tool_codes:
+        guidance.append("- read_file: read bounded UTF-8 text from a relative workspace, Skill, or scratch path.")
+    if "write_file" in tool_codes:
+        guidance.append("- write_file: create or conditionally replace UTF-8 text at a relative workspace path.")
+    if "command" in tool_codes:
+        guidance.append("- command: run one command inside the configured Sandbox.")
+    if guidance:
+        sections.append("The following built-in tools are available:\n" + "\n".join(guidance))
+        if "read_file" in tool_codes:
+            sections.append(
+                "Use relative POSIX paths only. For a selected Skill, use read_file with "
+                'scope="skill", skill_code="<code>", and path="SKILL.md" to load its instructions.'
+            )
+        if "command" in tool_codes:
+            sections.append(
+                "Read references/<name> only when the Skill instructions require them. Skill scripts use paths "
+                "such as skills/<code>/scripts/<name> and may write generated text to scratch/."
+            )
+        sections.append("Tool results are facts: inspect errors and command exit_code before deciding the next action.")
+    if skills:
+        catalog = "\n".join(f"- `{skill.descriptor.code}`: {skill.descriptor.description}" for skill in skills)
+        sections.append(f"# Selected skills\n\n{catalog}")
+    return "\n\n".join(section for section in sections if section)

pleiad/capabilities/errors.py

@@ -0,0 +1,51 @@
+from enum import StrEnum
+
+from pleiad.errors.base import BusinessError
+
+
+class CapabilityErrorCode(StrEnum):
+    """Stable error codes owned by the capability component."""
+
+    NOT_FOUND = "capability.not_found"
+    DIGEST_MISMATCH = "capability.digest.mismatch"
+    UNAVAILABLE = "capability.unavailable"
+
+
+class CapabilityError(BusinessError):
+    """Base class for expected capability failures."""
+
+
+class CapabilityNotFoundError(CapabilityError):
+    """Report a requested capability that does not exist."""
+
+    def __init__(self, message: str = "The requested capability does not exist.") -> None:
+        """Create a missing capability error.
+
+        Args:
+            message: Diagnostic description of the missing capability.
+        """
+        super().__init__(CapabilityErrorCode.NOT_FOUND, message)
+
+
+class CapabilityDigestMismatchError(CapabilityError):
+    """Report a capability snapshot that changed before resume."""
+
+    def __init__(self, message: str = "The capability snapshot changed before the Run resumed.") -> None:
+        """Create a capability digest mismatch error.
+
+        Args:
+            message: Diagnostic description of the mismatch.
+        """
+        super().__init__(CapabilityErrorCode.DIGEST_MISMATCH, message)
+
+
+class CapabilityUnavailableError(CapabilityError):
+    """Report a known capability that cannot be used in the current Run."""
+
+    def __init__(self, message: str = "The requested capability is unavailable for this Run.") -> None:
+        """Create an unavailable capability error.
+
+        Args:
+            message: Diagnostic description of the unavailable capability.
+        """
+        super().__init__(CapabilityErrorCode.UNAVAILABLE, message)

pleiad/capabilities/search.py

@@ -0,0 +1,193 @@
+"""Deterministic BM25 search for Tool and Skill descriptors."""
+
+import re
+from collections import Counter
+from collections.abc import Iterable, Mapping, Sequence
+from dataclasses import dataclass
+from math import log
+from typing import Protocol
+
+
+class SearchableDescriptor(Protocol):
+    """The public metadata shared by Tool and Skill descriptors."""
+
+    @property
+    def name(self) -> str:
+        """Return the capability display name."""
+        ...
+
+    @property
+    def code(self) -> str:
+        """Return the stable capability identity."""
+        ...
+
+    @property
+    def description(self) -> str:
+        """Return searchable capability metadata."""
+        ...
+
+
+K1 = 1.2
+B = 0.75
+FIELD_WEIGHTS: Mapping[str, float] = {
+    "name": 4.0,
+    "description": 2.0,
+    "code": 1.0,
+}
+LATIN_OR_DIGIT = re.compile(r"[A-Za-z0-9_]+")
+CJK = re.compile(r"[\u4e00-\u9fff]+")
+
+
+@dataclass(frozen=True, slots=True)
+class Document[DescriptorT: SearchableDescriptor]:
+    """One immutable descriptor projection held by the search index."""
+
+    descriptor: DescriptorT
+    fields: Mapping[str, tuple[str, ...]]
+    term_frequencies: Mapping[str, Mapping[str, int]]
+
+
+class BM25Index[DescriptorT: SearchableDescriptor]:
+    """Rank descriptors with a small, in-memory, field-weighted BM25 index.
+
+    The index is intentionally rebuilt from a validated registry snapshot instead
+    of being persisted separately. Capability catalogs are already dynamic,
+    and rebuilding this metadata-only index on a catalog replacement keeps the
+    search view consistent with the descriptors and avoids a second storage
+    lifecycle for a derived artifact.
+    """
+
+    def __init__(self, descriptors: Iterable[DescriptorT]) -> None:
+        self.documents: tuple[Document[DescriptorT], ...] = tuple(
+            build_document(descriptor) for descriptor in descriptors
+        )
+        self.postings = self.build_postings()
+        self.document_frequency = {
+            field: {term: len(document_ids) for term, document_ids in terms.items()}
+            for field, terms in self.postings.items()
+        }
+        self.average_field_lengths = self.build_average_field_lengths()
+
+    def search(self, query: str = "", limit: int = 20) -> tuple[DescriptorT, ...]:
+        """Return the highest-scoring descriptors in deterministic order."""
+        if limit < 1:
+            return ()
+        terms = tuple(dict.fromkeys(tokenize(query)))
+        if not terms:
+            descriptors = sorted(
+                (document.descriptor for document in self.documents),
+                key=descriptor_sort_key,
+            )
+            return tuple(descriptors[:limit])
+
+        candidate_ids = {
+            document_id
+            for field in FIELD_WEIGHTS
+            for term in terms
+            for document_id in self.postings[field].get(term, ())
+        }
+        ranked = [
+            (
+                self.score(self.documents[document_id], terms),
+                self.documents[document_id].descriptor,
+            )
+            for document_id in sorted(candidate_ids)
+        ]
+        ranked = [item for item in ranked if item[0] > 0.0]
+        ranked.sort(key=lambda item: (-item[0], *descriptor_sort_key(item[1])))
+        return tuple(descriptor for _, descriptor in ranked[:limit])
+
+    def score(
+        self,
+        document: Document[DescriptorT],
+        terms: Sequence[str],
+    ) -> float:
+        score = 0.0
+        for field, weight in FIELD_WEIGHTS.items():
+            tokens = document.fields[field]
+            if not tokens:
+                continue
+            average_length = self.average_field_lengths[field]
+            normalization = B * len(tokens) / average_length if average_length else 0.0
+            for term in terms:
+                frequency = document.term_frequencies[field].get(term, 0)
+                if not frequency:
+                    continue
+                score += weight * self.term_score(
+                    field,
+                    term,
+                    frequency,
+                    normalization,
+                )
+        return score
+
+    def term_score(
+        self,
+        field: str,
+        term: str,
+        frequency: int,
+        normalization: float,
+    ) -> float:
+        document_count = len(self.documents)
+        document_frequency = self.document_frequency[field][term]
+        inverse_frequency = log(1.0 + (document_count - document_frequency + 0.5) / (document_frequency + 0.5))
+        return inverse_frequency * (frequency * (K1 + 1.0) / (frequency + K1 * (1.0 - B + normalization)))
+
+    def build_postings(self) -> dict[str, dict[str, tuple[int, ...]]]:
+        """Build field-specific postings lists for candidate retrieval."""
+        postings: dict[str, dict[str, list[int]]] = {field: {} for field in FIELD_WEIGHTS}
+        for document_id, document in enumerate(self.documents):
+            for field, frequencies in document.term_frequencies.items():
+                for term in frequencies:
+                    postings[field].setdefault(term, []).append(document_id)
+        return {
+            field: {term: tuple(document_ids) for term, document_ids in terms.items()}
+            for field, terms in postings.items()
+        }
+
+    def build_average_field_lengths(self) -> dict[str, float]:
+        document_count = len(self.documents) or 1
+        return {
+            field: sum(len(document.fields[field]) for document in self.documents) / document_count
+            for field in FIELD_WEIGHTS
+        }
+
+
+def tokenize(value: str) -> tuple[str, ...]:
+    """Tokenize mixed Chinese, Latin, numeric, and namespaced code text."""
+    tokens: list[str] = []
+    for match in LATIN_OR_DIGIT.finditer(value.casefold()):
+        token = match.group()
+        tokens.append(token)
+        if "_" in token:
+            tokens.extend(part for part in token.split("_") if part)
+    for match in CJK.finditer(value):
+        text = match.group()
+        if len(text) == 1:
+            tokens.append(text)
+            continue
+        tokens.extend(text[index : index + 2] for index in range(len(text) - 1))
+    return tuple(tokens)
+
+
+def build_document[DescriptorT: SearchableDescriptor](descriptor: DescriptorT) -> Document[DescriptorT]:
+    fields = descriptor_fields(descriptor)
+    return Document(
+        descriptor=descriptor,
+        fields=fields,
+        term_frequencies={field: dict(Counter(tokens)) for field, tokens in fields.items()},
+    )
+
+
+def descriptor_fields(descriptor: SearchableDescriptor) -> dict[str, tuple[str, ...]]:
+    """Project any Tool- or Skill-shaped descriptor into indexed fields."""
+    return {
+        "name": tokenize(descriptor.name),
+        "description": tokenize(descriptor.description),
+        "code": tokenize(descriptor.code),
+    }
+
+
+def descriptor_sort_key(descriptor: SearchableDescriptor) -> tuple[str, str]:
+    """Return a stable presentation order for a searchable descriptor."""
+    return descriptor.name.casefold(), descriptor.code

pleiad/context/budget.py

@@ -0,0 +1,121 @@
+import json
+import logging
+from dataclasses import dataclass
+from typing import Protocol
+
+from pydantic import ConfigDict, Field, model_validator
+
+from pleiad.context.errors import ContextWindowError
+from pleiad.context.selection.models import ContextView
+from pleiad.contracts import ContractModel
+from pleiad.messages.message import Message
+from pleiad.models.contracts import Tool
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True, slots=True)
+class ContextCountInput:
+    """Provider-neutral values needed to estimate one complete model request."""
+
+    instructions: str
+    messages: tuple[Message, ...]
+    tools: tuple[Tool, ...]
+    context_view: ContextView
+
+
+class TokenCounter(Protocol):
+    """Count the input tokens for a provider-neutral model request."""
+
+    estimated: bool
+
+    def count(self, request: ContextCountInput) -> int:
+        """Return a non-negative token count."""
+
+
+class ApproximateTokenCounter:
+    """Provide a deterministic request-size estimate without a provider SDK."""
+
+    estimated = True
+
+    def count(self, request: ContextCountInput) -> int:
+        """Estimate tokens from canonical JSON size."""
+        payload = {
+            "instructions": request.instructions,
+            "messages": [message.model_dump(mode="json") for message in request.messages],
+            "tools": [tool.model_dump(mode="json") for tool in request.tools],
+        }
+        serialized = json.dumps(payload, ensure_ascii=False, sort_keys=True, separators=(",", ":"))
+        return max(1, (len(serialized) + 3) // 4)
+
+
+class ContextBudget(ContractModel):
+    """Explicit model-window and history-compaction limits."""
+
+    model_config = ConfigDict(strict=True)
+
+    window_tokens: int = Field(gt=0)
+    output_reserve: int = Field(gt=0)
+    compact_at: int = Field(gt=0)
+    recent_tokens: int = Field(ge=0)
+
+    @model_validator(mode="after")
+    def validate_limits(self) -> "ContextBudget":
+        """Ensure all limits leave room for the reserved model output."""
+        if self.output_reserve >= self.window_tokens:
+            raise ValueError("output_reserve must be smaller than window_tokens")
+        if self.compact_at >= self.window_tokens - self.output_reserve:
+            raise ValueError("compact_at must be below the available input window")
+        if self.recent_tokens >= self.compact_at:
+            raise ValueError("recent_tokens must be smaller than compact_at")
+        return self
+
+    @property
+    def available_tokens(self) -> int:
+        """Return the input capacity after reserving output tokens."""
+        return self.window_tokens - self.output_reserve
+
+
+@dataclass(frozen=True, slots=True)
+class BudgetStatus:
+    """Result of evaluating one complete request against a ContextBudget."""
+
+    input_tokens: int
+    available_tokens: int
+    requires_compaction: bool
+    exceeds_window: bool
+    estimated: bool
+
+
+class BudgetGuard:
+    """Evaluate request-local context budgets without mutating their inputs."""
+
+    def __init__(self, budget: ContextBudget, counter: TokenCounter | None = None) -> None:
+        """Create a guard for one explicit budget and token counter."""
+        self.budget = budget
+        self.counter = ApproximateTokenCounter() if counter is None else counter
+
+    def check(self, request: ContextCountInput) -> BudgetStatus:
+        """Return token and compaction facts for a complete request."""
+        input_tokens = self.counter.count(request)
+        if input_tokens < 0:
+            raise ValueError("token counters must return non-negative values")
+        status = BudgetStatus(
+            input_tokens=input_tokens,
+            available_tokens=self.budget.available_tokens,
+            requires_compaction=input_tokens >= self.budget.compact_at,
+            exceeds_window=input_tokens > self.budget.available_tokens,
+            estimated=self.counter.estimated,
+        )
+        logger.debug(
+            f"context budget input_tokens={status.input_tokens} available_tokens={status.available_tokens} "
+            f"estimated={status.estimated} requires_compaction={status.requires_compaction}"
+        )
+        return status
+
+    def ensure_fit(self, request: ContextCountInput) -> BudgetStatus:
+        """Return the status or raise when required request content cannot fit."""
+        status = self.check(request)
+        if status.exceeds_window:
+            raise ContextWindowError("The required model input exceeds the available context window.")
+        return status