bbagents 0.1.0__py3-none-any.whl

bbagents/__init__.py

@@ -0,0 +1,70 @@
+"""BrilBerry Agents: provider-neutral contracts for agent applications.
+
+The root namespace intentionally contains only the most common execution path.
+Import specialised APIs from their responsibility-specific modules, for example
+``bbagents.intervention`` or ``bbagents.models``.
+"""
+
+from .core import LanguageModel, Observation, TraceSink
+from .decision import (
+    DecisionModel,
+    DecisionOutput,
+    DecisionRequest,
+    DecisionResult,
+    DecisionRuntime,
+    DecisionSchema,
+    DecisionUsage,
+    PythonTypeSchema,
+)
+from .planning import (
+    AgentState,
+    DependencyCycleError,
+    Plan,
+    PlanExecutor,
+    PlanStep,
+    StepStatus,
+)
+from .provenance import Provenance, TrustLevel
+from .runtime import (
+    Action,
+    ActionResult,
+    ActionRuntime,
+    ActionStatus,
+    AuthorizationDecision,
+    AuthorizationStatus,
+)
+from .tools import FunctionTool, Tool, ToolCall, ToolRegistry
+
+__all__ = [
+    "Action",
+    "ActionResult",
+    "ActionRuntime",
+    "ActionStatus",
+    "AgentState",
+    "AuthorizationDecision",
+    "AuthorizationStatus",
+    "DecisionModel",
+    "DecisionOutput",
+    "DecisionRequest",
+    "DecisionResult",
+    "DecisionRuntime",
+    "DecisionSchema",
+    "DecisionUsage",
+    "DependencyCycleError",
+    "FunctionTool",
+    "LanguageModel",
+    "Observation",
+    "Plan",
+    "PlanExecutor",
+    "PlanStep",
+    "Provenance",
+    "PythonTypeSchema",
+    "StepStatus",
+    "Tool",
+    "ToolCall",
+    "ToolRegistry",
+    "TraceSink",
+    "TrustLevel",
+]
+
+__version__ = "0.1.0"

bbagents/compaction.py

@@ -0,0 +1,38 @@
+"""Grade structured continuation probes rather than compression ratios."""
+
+from dataclasses import dataclass
+
+from .evaluation import Grade, TrialEvidence
+
+
+@dataclass(frozen=True, slots=True)
+class ContinuationObservation:
+    retained_constraints: frozenset[str]
+    proposed_action_ids: frozenset[str]
+    recovered_evidence_refs: frozenset[str]
+
+
+@dataclass(frozen=True, slots=True)
+class CompactionGrader:
+    required_constraints: frozenset[str]
+    completed_action_ids: frozenset[str]
+    required_evidence_refs: frozenset[str]
+
+    def grade(self, trial: TrialEvidence[ContinuationObservation | None]) -> Grade:
+        observation = trial.outcome
+        if observation is None:
+            return Grade(None, "No continuation evidence")
+        missing_constraints = (
+            self.required_constraints - observation.retained_constraints
+        )
+        repeated = self.completed_action_ids & observation.proposed_action_ids
+        missing_evidence = (
+            self.required_evidence_refs - observation.recovered_evidence_refs
+        )
+        passed = not (missing_constraints or repeated or missing_evidence)
+        return Grade(
+            passed,
+            f"Missing constraints: {sorted(missing_constraints)}; "
+            f"repeated actions: {sorted(repeated)}; missing evidence: {sorted(missing_evidence)}",
+            evidence_refs=tuple(sorted(observation.recovered_evidence_refs)),
+        )

bbagents/context.py

@@ -0,0 +1,124 @@
+"""Budgeted context assembly and state-projection contracts.
+
+Applications decide which domain facts matter. This module provides the
+portable mechanics for selecting, truncating, and optionally summarizing those
+facts before they are passed to a model or another agent.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Protocol, Sequence, TypeVar
+
+from .provenance import Provenance
+
+StateT = TypeVar("StateT", contravariant=True)
+
+
+@dataclass(frozen=True, slots=True)
+class ContextBudget:
+    """Limits applied when assembling an execution context."""
+
+    max_items: int = 20
+    max_characters: int = 12_000
+
+    def __post_init__(self) -> None:
+        if self.max_items < 1:
+            raise ValueError("max_items must be positive")
+        if self.max_characters < 1:
+            raise ValueError("max_characters must be positive")
+
+
+@dataclass(frozen=True, slots=True)
+class ContextItem:
+    """One application-provided candidate for a model context."""
+
+    content: str
+    source: str
+    priority: int = 0
+    metadata: dict[str, Any] = field(default_factory=dict)
+    provenance: Provenance = field(
+        default_factory=lambda: Provenance.system("context")
+    )
+
+
+@dataclass(frozen=True, slots=True)
+class Context:
+    """A bounded, attributable view of application state."""
+
+    content: str
+    items: tuple[ContextItem, ...]
+    omitted_items: int = 0
+    summarized: bool = False
+    summary_sources: tuple[ContextItem, ...] = ()
+
+
+class StateProjector(Protocol[StateT]):
+    """Maps application state into ranked, attributable context candidates."""
+
+    def project(self, state: StateT) -> Sequence[ContextItem]: ...
+
+
+class ContextSummarizer(Protocol):
+    """Compresses omitted context using an application-selected implementation."""
+
+    def summarize(
+        self,
+        items: Sequence[ContextItem],
+        *,
+        max_characters: int,
+    ) -> str: ...
+
+
+class ContextBuilder:
+    """Deterministically assembles a bounded context from ranked candidates."""
+
+    def __init__(
+        self,
+        budget: ContextBudget,
+        *,
+        summarizer: ContextSummarizer | None = None,
+    ) -> None:
+        self.budget = budget
+        self.summarizer = summarizer
+
+    def build(self, items: Sequence[ContextItem]) -> Context:
+        ranked = sorted(enumerate(items), key=lambda pair: (-pair[1].priority, pair[0]))
+        selected: list[ContextItem] = []
+        omitted: list[ContextItem] = []
+        used = 0
+        for _, item in ranked:
+            separator = 1 if selected else 0
+            if (
+                len(selected) < self.budget.max_items
+                and used + separator + len(item.content) <= self.budget.max_characters
+            ):
+                selected.append(item)
+                used += separator + len(item.content)
+            else:
+                omitted.append(item)
+
+        content = "\n".join(item.content for item in selected)
+        if not omitted or self.summarizer is None:
+            return Context(content, tuple(selected), omitted_items=len(omitted))
+
+        available = self.budget.max_characters - len(content) - (1 if content else 0)
+        if available < 1:
+            return Context(content, tuple(selected), omitted_items=len(omitted))
+        summary = self.summarizer.summarize(omitted, max_characters=available).strip()
+        if len(summary) > available:
+            summary = summary[:available]
+        if summary:
+            content = f"{content}\n{summary}" if content else summary
+        return Context(
+            content,
+            tuple(selected),
+            omitted_items=len(omitted),
+            summarized=bool(summary),
+            summary_sources=tuple(omitted) if summary else (),
+        )
+
+    def project(self, state: StateT, projector: StateProjector[StateT]) -> Context:
+        """Build a context from an application's state projection."""
+
+        return self.build(projector.project(state))

bbagents/core.py

@@ -0,0 +1,49 @@
+"""Shared value objects and provider-neutral interfaces."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Mapping, Protocol, TypeVar
+
+from .provenance import Provenance
+
+T = TypeVar("T")
+
+
+@dataclass(slots=True)
+class Observation:
+    """A fact returned by a tool or runtime component."""
+
+    source: str
+    content: str
+    metadata: dict[str, Any] = field(default_factory=dict)
+    provenance: Provenance = field(
+        default_factory=lambda: Provenance.system("runtime")
+    )
+
+
+class LanguageModel(Protocol):
+    """Minimal structured-completion interface adapted by the decision runtime."""
+
+    def complete(
+        self,
+        system: str,
+        user: str,
+        *,
+        response_format: Any | None = None,
+    ) -> T | str: ...
+
+
+class TraceSink(Protocol):
+    """Receives structured execution events."""
+
+    def record(
+        self, event: Any, payload: Mapping[str, Any] | None = None
+    ) -> None: ...
+
+
+class NullTrace:
+    """Trace sink for callers that do not need telemetry."""
+
+    def record(self, event: Any, payload: Mapping[str, Any] | None = None) -> None:
+        del event, payload

bbagents/decision.py

@@ -0,0 +1,225 @@
+"""Provider-neutral structured model decisions with validation and tracing."""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from typing import Any, Callable, Generic, Mapping, Protocol, TypeVar
+
+from .context import Context
+from .core import LanguageModel, NullTrace, TraceSink
+from .observability import TraceEventName
+
+T = TypeVar("T")
+SchemaT = TypeVar("SchemaT", covariant=True)
+
+
+@dataclass(frozen=True, slots=True)
+class DecisionRequirements:
+    """Quality and latency constraints used by an application model selector."""
+
+    minimum_quality: float = 0.0
+    maximum_latency_seconds: float | None = None
+
+    def __post_init__(self) -> None:
+        if not 0 <= self.minimum_quality <= 1:
+            raise ValueError("minimum_quality must be between 0 and 1")
+        if (
+            self.maximum_latency_seconds is not None
+            and self.maximum_latency_seconds <= 0
+        ):
+            raise ValueError("maximum_latency_seconds must be positive")
+
+
+class DecisionSchema(Protocol[SchemaT]):
+    """Parse and validate provider output without imposing a schema dependency."""
+
+    @property
+    def name(self) -> str: ...
+
+    @property
+    def provider_format(self) -> Any | None: ...
+
+    def parse(self, value: Any) -> SchemaT: ...
+
+
+@dataclass(frozen=True, slots=True)
+class PythonTypeSchema(Generic[T]):
+    """Schema adapter for ordinary Python runtime types and dataclasses."""
+
+    value_type: type[T]
+
+    @property
+    def name(self) -> str:
+        return self.value_type.__name__
+
+    @property
+    def provider_format(self) -> type[T] | None:
+        return None if self.value_type is str else self.value_type
+
+    def parse(self, value: Any) -> T:
+        if not isinstance(value, self.value_type):
+            raise TypeError(
+                "Model returned "
+                f"{type(value).__name__}, expected {self.value_type.__name__}"
+            )
+        return value
+
+
+@dataclass(frozen=True, slots=True)
+class DecisionUsage:
+    input_tokens: int | None = None
+    output_tokens: int | None = None
+    total_tokens: int | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class DecisionOutput(Generic[T]):
+    """Provider adapter output with optional portable execution metadata."""
+
+    value: T
+    model_id: str | None = None
+    usage: DecisionUsage | None = None
+    metadata: Mapping[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True, slots=True)
+class DecisionRequest(Generic[T]):
+    """A bounded request with an explicit output schema and application validator."""
+
+    task: str
+    system: str
+    context: Context
+    schema: DecisionSchema[T] | type[T]
+    requirements: DecisionRequirements = field(default_factory=DecisionRequirements)
+    validate: Callable[[T], bool] | None = None
+    metadata: Mapping[str, Any] = field(default_factory=dict)
+
+    def output_schema(self) -> DecisionSchema[T]:
+        return _coerce_schema(self.schema)
+
+
+@dataclass(frozen=True, slots=True)
+class DecisionResult(Generic[T]):
+    value: T
+    attempts: int
+    duration_seconds: float
+    model_id: str | None = None
+    usage: DecisionUsage | None = None
+    metadata: Mapping[str, Any] = field(default_factory=dict)
+
+
+class DecisionModel(Protocol):
+    """Produces a proposal; it does not execute application actions."""
+
+    def decide(self, request: DecisionRequest[T]) -> T | DecisionOutput[T]: ...
+
+
+class DecisionFailure(RuntimeError):
+    """Raised after an invalid or failed model decision exhausts its retries."""
+
+    def __init__(self, attempts: int, last_error: Exception) -> None:
+        self.attempts = attempts
+        self.last_error = last_error
+        super().__init__(f"Decision failed after {attempts} attempts: {last_error}")
+
+
+class LanguageModelDecisionAdapter:
+    """Adapt the package's minimal completion protocol to a decision model."""
+
+    def __init__(
+        self, model: LanguageModel, *, model_id: str | None = None
+    ) -> None:
+        self.model = model
+        self.model_id = model_id
+
+    def decide(self, request: DecisionRequest[T]) -> DecisionOutput[Any]:
+        value = self.model.complete(
+            request.system,
+            _render_user_message(request),
+            response_format=request.output_schema().provider_format,
+        )
+        return DecisionOutput(value, model_id=self.model_id)
+
+
+class DecisionRuntime:
+    """Invoke a model with schema validation, retries, and portable metadata."""
+
+    def __init__(
+        self,
+        model: DecisionModel,
+        *,
+        trace: TraceSink | None = None,
+        model_id: str | None = None,
+    ) -> None:
+        self.model = model
+        self.trace = trace or NullTrace()
+        self.model_id = model_id
+
+    def decide(
+        self, request: DecisionRequest[T], *, retries: int = 0
+    ) -> DecisionResult[T]:
+        started = time.monotonic()
+        schema = request.output_schema()
+        self.trace.record(
+            TraceEventName.DECISION_STARTED,
+            {
+                "task": request.task,
+                "schema": schema.name,
+                "context_item_count": len(request.context.items),
+                "context_omitted_items": request.context.omitted_items,
+                **dict(request.metadata),
+            },
+        )
+        error: Exception | None = None
+        for attempt in range(1, retries + 2):
+            try:
+                output = _coerce_output(self.model.decide(request))
+                value = schema.parse(output.value)
+                if request.validate is not None and not request.validate(value):
+                    raise ValueError("Decision failed application validation")
+                result = DecisionResult(
+                    value,
+                    attempt,
+                    time.monotonic() - started,
+                    model_id=output.model_id or self.model_id,
+                    usage=output.usage,
+                    metadata=output.metadata,
+                )
+                self.trace.record(
+                    TraceEventName.DECISION_COMPLETED,
+                    {
+                        "task": request.task,
+                        "attempts": attempt,
+                        "model_id": result.model_id,
+                        **dict(request.metadata),
+                    },
+                )
+                return result
+            except Exception as exc:
+                error = exc
+                self.trace.record(
+                    TraceEventName.DECISION_FAILED,
+                    {
+                        "task": request.task,
+                        "attempt": attempt,
+                        "error": str(exc),
+                        **dict(request.metadata),
+                    },
+                )
+        assert error is not None
+        raise DecisionFailure(retries + 1, error) from error
+
+
+def _coerce_schema(schema: DecisionSchema[T] | type[T]) -> DecisionSchema[T]:
+    if isinstance(schema, type):
+        return PythonTypeSchema(schema)
+    return schema
+
+
+def _coerce_output(value: T | DecisionOutput[T]) -> DecisionOutput[T]:
+    return value if isinstance(value, DecisionOutput) else DecisionOutput(value)
+
+
+def _render_user_message(request: DecisionRequest[Any]) -> str:
+    return f"Task:\n{request.task}\n\nContext:\n{request.context.content}"

bbagents/evaluation.py

@@ -0,0 +1,114 @@
+"""Portable evaluation evidence, graders, and repeated-trial reporting.
+
+Applications run trials in isolated environments and provide actual outcome
+snapshots. This module does not execute agents or infer state from their answers.
+"""
+
+from dataclasses import dataclass, field
+from math import isfinite
+from typing import Any, Generic, Mapping, Protocol, Sequence, TypeVar
+
+from .observability import TraceEvent
+
+OutcomeT = TypeVar("OutcomeT")
+
+
+@dataclass(frozen=True, slots=True)
+class TrialEvidence(Generic[OutcomeT]):
+    case_id: str
+    trial_id: str
+    response: str
+    transcript: tuple[TraceEvent, ...]
+    outcome: OutcomeT
+    configuration: Mapping[str, Any]
+    duration_seconds: float
+    cost: float | None = None
+
+    def __post_init__(self) -> None:
+        if not isfinite(self.duration_seconds) or self.duration_seconds < 0:
+            raise ValueError("duration_seconds must be finite and nonnegative")
+        if self.cost is not None and (not isfinite(self.cost) or self.cost < 0):
+            raise ValueError("cost must be finite and nonnegative")
+
+
+@dataclass(frozen=True, slots=True)
+class Grade:
+    """None means insufficient evidence, distinct from passing or failing."""
+
+    passed: bool | None
+    reason: str
+    score: float | None = None
+    evidence_refs: tuple[str, ...] = ()
+
+    def __post_init__(self) -> None:
+        if self.score is not None and (
+            not isfinite(self.score) or not 0 <= self.score <= 1
+        ):
+            raise ValueError("score must be finite and between 0 and 1")
+
+
+class Grader(Protocol[OutcomeT]):
+    def grade(self, trial: TrialEvidence[OutcomeT]) -> Grade: ...
+
+
+@dataclass(frozen=True, slots=True)
+class TrialGrades:
+    case_id: str
+    trial_id: str
+    grades: Mapping[str, Grade] = field(default_factory=dict)
+
+    @property
+    def passed(self) -> bool | None:
+        if any(grade.passed is False for grade in self.grades.values()):
+            return False
+        if not self.grades or any(
+            grade.passed is None for grade in self.grades.values()
+        ):
+            return None
+        return True
+
+
+def grade_trial(
+    trial: TrialEvidence[OutcomeT], graders: Mapping[str, Grader[OutcomeT]]
+) -> TrialGrades:
+    return TrialGrades(
+        trial.case_id,
+        trial.trial_id,
+        {name: grader.grade(trial) for name, grader in graders.items()},
+    )
+
+
+@dataclass(frozen=True, slots=True)
+class TrialReport:
+    trials: int
+    passed: int
+    failed: int
+    insufficient: int
+    empirical_success_rate: float | None
+    cases_with_any_success: int
+    cases_with_all_successes: int
+
+
+def report_trials(results: Sequence[TrialGrades]) -> TrialReport:
+    """Report observed rates only, without assuming independent repetitions."""
+
+    by_case: dict[str, list[bool | None]] = {}
+    seen: set[tuple[str, str]] = set()
+    for result in results:
+        identity = (result.case_id, result.trial_id)
+        if identity in seen:
+            raise ValueError(f"Duplicate trial: {identity}")
+        seen.add(identity)
+        by_case.setdefault(result.case_id, []).append(result.passed)
+    statuses = [result.passed for result in results]
+    passed = sum(status is True for status in statuses)
+    failed = sum(status is False for status in statuses)
+    return TrialReport(
+        len(results),
+        passed,
+        failed,
+        sum(status is None for status in statuses),
+        passed / len(results) if results else None,
+        sum(any(status is True for status in case) for case in by_case.values()),
+        sum(all(status is True for status in case) for case in by_case.values()),
+    )