agent-learning-kit 0.1.0__py3-none-any.whl

fi/alk/harness/data/persona_vocabulary.json

@@ -0,0 +1,111 @@
+{
+  "GenderChoices": [
+    "male",
+    "female"
+  ],
+  "AgeGroupChoices": [
+    "18-25",
+    "25-32",
+    "32-40",
+    "40-50",
+    "50-60",
+    "60+"
+  ],
+  "LocationChoices": [
+    "United States",
+    "Canada",
+    "United Kingdom",
+    "Australia",
+    "India"
+  ],
+  "ProfessionChoices": [
+    "Student",
+    "Teacher",
+    "Engineer",
+    "Doctor",
+    "Nurse",
+    "Business Owner",
+    "Manager",
+    "Sales Representative",
+    "Customer Service",
+    "Technician",
+    "Consultant",
+    "Accountant",
+    "Marketing Professional",
+    "Retired",
+    "Homemaker",
+    "Freelancer",
+    "Other"
+  ],
+  "PersonalityChoices": [
+    "Friendly and cooperative",
+    "Professional and formal",
+    "Cautious and skeptical",
+    "Impatient and direct",
+    "Detail-oriented",
+    "Easy-going",
+    "Anxious",
+    "Confident",
+    "Analytical",
+    "Emotional",
+    "Reserved",
+    "Talkative"
+  ],
+  "CommunicationStyleChoices": [
+    "Direct and concise",
+    "Detailed and elaborate",
+    "Casual and friendly",
+    "Formal and polite",
+    "Technical",
+    "Simple and clear",
+    "Questioning",
+    "Assertive",
+    "Passive",
+    "Collaborative"
+  ],
+  "AccentChoices": [
+    "American",
+    "Australian",
+    "Indian",
+    "Canadian",
+    "Neutral"
+  ],
+  "LanguageChoices": [
+    "Arabic",
+    "Bulgarian",
+    "Chinese Simplified",
+    "Czech",
+    "Danish",
+    "Dutch",
+    "English",
+    "Finnish",
+    "French",
+    "German",
+    "Greek",
+    "Hindi",
+    "Hungarian",
+    "Indonesian",
+    "Italian",
+    "Japanese",
+    "Korean",
+    "Malay",
+    "Norwegian",
+    "Polish",
+    "Portuguese",
+    "Romanian",
+    "Russian",
+    "Slovak",
+    "Spanish",
+    "Swedish",
+    "Turkish",
+    "Ukrainian",
+    "Vietnamese"
+  ],
+  "ConversationSpeedChoices": [
+    "0.5",
+    "0.75",
+    "1.0",
+    "1.25",
+    "1.5"
+  ]
+}

fi/alk/harness/environment.py

@@ -0,0 +1,99 @@
+"""The small ``fi.simulate.environment`` contract a generated world implements.
+
+The parent package currently imports optional LiveKit code from ``fi.simulate.__init__`` before a
+submodule can be imported. Keep the normal integration when that import is available, while
+letting the standalone harness run its deterministic world and scenario gates from the base
+editable dependency alone.
+"""
+
+from __future__ import annotations
+
+from abc import ABC
+from typing import Any, Mapping
+
+try:
+    from fi.simulate.environment import (
+        EnvironmentAdapter,
+        EnvironmentSnapshot,
+        ToolExecutionResult,
+    )
+except (
+    ImportError
+):  # pragma: no cover - exercised only without the parent's optional extras
+    from pydantic import BaseModel, Field
+
+    class EnvironmentSnapshot(BaseModel):
+        """State and tool definitions published by a local environment."""
+
+        tools: list[dict[str, Any]] = Field(default_factory=list)
+        artifacts: list[Any] = Field(default_factory=list)
+        events: list[Any] = Field(default_factory=list)
+        state: dict[str, Any] = Field(default_factory=dict)
+        metadata: dict[str, Any] = Field(default_factory=dict)
+
+    class ToolExecutionResult(BaseModel):
+        """Result from executing one local tool call."""
+
+        tool_call_id: str | None = None
+        tool_name: str
+        content: str
+        result: Any = None
+        success: bool = True
+        error: str | None = None
+        state_updates: dict[str, Any] = Field(default_factory=dict)
+        artifacts: list[Any] = Field(default_factory=list)
+        events: list[Any] = Field(default_factory=list)
+        metadata: dict[str, Any] = Field(default_factory=dict)
+
+        def to_tool_message(self) -> dict[str, Any]:
+            return {
+                "role": "tool",
+                "tool_call_id": self.tool_call_id or self.tool_name,
+                "content": self.content,
+            }
+
+    class EnvironmentAdapter(ABC):
+        """The subset of the parent environment protocol the harness needs."""
+
+        name = "environment"
+
+        def reset(self, **_context: Any) -> EnvironmentSnapshot:
+            return EnvironmentSnapshot()
+
+        def observe(self, **_context: Any) -> EnvironmentSnapshot:
+            return EnvironmentSnapshot()
+
+        def handle_tool_call(
+            self, tool_call: Mapping[str, Any], **_context: Any
+        ) -> ToolExecutionResult | None:
+            return None
+
+
+# Compatibility exports: the environment artifact was split into focused catalogue and
+# simulator modules. Existing ALK integrations may keep importing the original surface.
+from .catalogue import (  # noqa: E402
+    Catalogue,
+    SubGoal,
+    load_catalogue,
+    save_catalogue,
+    validate_sub_goal,
+)
+from .simulator import (  # noqa: E402
+    load_simulator_prompt,
+    save_simulator_prompt,
+    validate_simulator_prompt,
+)
+
+__all__ = [
+    "Catalogue",
+    "EnvironmentAdapter",
+    "EnvironmentSnapshot",
+    "SubGoal",
+    "ToolExecutionResult",
+    "load_catalogue",
+    "load_simulator_prompt",
+    "save_catalogue",
+    "save_simulator_prompt",
+    "validate_simulator_prompt",
+    "validate_sub_goal",
+]

fi/alk/harness/environment_plan.py

@@ -0,0 +1,168 @@
+"""Canonical, immutable description of an ALK environment.
+
+The bundle is the portable payload.  The environment plan is the stable decision record inside
+that payload: which source revision was admitted, which runtime document will be used, which
+services/capabilities exist, and how readiness is proven.  It deliberately excludes ephemeral
+project names, allocated host ports, and resolved secret values.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from pathlib import Path
+
+from pydantic import BaseModel, Field, JsonValue, model_validator
+
+from .bundle import (
+    BundleRuntime,
+    Capability,
+    EnvironmentBundle,
+    ReadinessProbe,
+)
+
+ENVIRONMENT_PLAN_SCHEMA_VERSION = "futureagi.environment-plan.v1"
+ENVIRONMENT_PLAN_FILE = "environment-plan.json"
+
+
+class EnvironmentPlanError(RuntimeError):
+    """The frozen plan is absent, corrupt, or inconsistent with its bundle."""
+
+
+class PlanSource(BaseModel):
+    kind: str
+    repository: str | None = None
+    commit_sha: str | None = None
+    source_digest: str
+
+
+class EnvironmentPlan(BaseModel):
+    schema_version: str = ENVIRONMENT_PLAN_SCHEMA_VERSION
+    digest: str
+    source: PlanSource
+    runtime: BundleRuntime
+    services: list[str] = Field(default_factory=list)
+    capabilities: dict[str, Capability] = Field(default_factory=dict)
+    readiness: list[ReadinessProbe] = Field(default_factory=list)
+    configuration_names: list[str] = Field(default_factory=list)
+    metadata: dict[str, JsonValue] = Field(default_factory=dict)
+
+    @model_validator(mode="after")
+    def _valid_plan(self) -> "EnvironmentPlan":
+        if self.schema_version != ENVIRONMENT_PLAN_SCHEMA_VERSION:
+            raise ValueError(
+                f"environment_plan_schema_unsupported: {self.schema_version}"
+            )
+        if not re.fullmatch(r"sha256:[0-9a-f]{64}", self.digest):
+            raise ValueError("environment_plan_digest_invalid")
+        missing = [
+            probe.capability
+            for probe in self.readiness
+            if probe.capability not in self.capabilities
+        ]
+        if missing:
+            raise ValueError(
+                "environment_plan_readiness_capability_missing: "
+                + ", ".join(sorted(set(missing)))
+            )
+        if self.configuration_names != sorted(set(self.configuration_names)):
+            raise ValueError("environment_plan_configuration_names_not_canonical")
+        return self
+
+
+def _digest(raw: dict) -> str:
+    canonical = dict(raw)
+    canonical.pop("digest", None)
+    encoded = json.dumps(
+        canonical, sort_keys=True, separators=(",", ":"), ensure_ascii=False
+    ).encode("utf-8")
+    return "sha256:" + hashlib.sha256(encoded).hexdigest()
+
+
+def create_environment_plan(
+    *,
+    source: PlanSource,
+    runtime: BundleRuntime,
+    services: list[str],
+    capabilities: dict[str, Capability],
+    readiness: list[ReadinessProbe],
+    metadata: dict[str, JsonValue] | None = None,
+) -> EnvironmentPlan:
+    """Create the same plan digest for the same admitted environment decision."""
+    names = sorted(
+        {
+            capability.configuration_name
+            for capability in capabilities.values()
+            if capability.configuration_name
+        }
+    )
+    raw = {
+        "schema_version": ENVIRONMENT_PLAN_SCHEMA_VERSION,
+        "digest": "sha256:" + "0" * 64,
+        "source": source.model_dump(mode="json"),
+        "runtime": runtime.model_dump(mode="json"),
+        "services": sorted(set(services)),
+        "capabilities": {
+            key: capabilities[key].model_dump(mode="json")
+            for key in sorted(capabilities)
+        },
+        "readiness": [
+            probe.model_dump(mode="json") for probe in readiness
+        ],
+        "configuration_names": names,
+        "metadata": metadata or {},
+    }
+    raw["digest"] = _digest(raw)
+    return EnvironmentPlan.model_validate(raw)
+
+
+def write_environment_plan(root: str | Path, plan: EnvironmentPlan) -> Path:
+    target = Path(root) / ENVIRONMENT_PLAN_FILE
+    temporary = target.with_name(f".{target.name}.tmp")
+    temporary.write_text(plan.model_dump_json(indent=2) + "\n", encoding="utf-8")
+    temporary.replace(target)
+    return target
+
+
+def load_environment_plan(
+    root: str | Path, *, bundle: EnvironmentBundle | None = None
+) -> EnvironmentPlan:
+    target = Path(root) / ENVIRONMENT_PLAN_FILE
+    if not target.is_file():
+        raise EnvironmentPlanError(f"environment_plan_missing: {target}")
+    try:
+        plan = EnvironmentPlan.model_validate_json(target.read_text(encoding="utf-8"))
+    except (OSError, ValueError) as exc:
+        raise EnvironmentPlanError(f"environment_plan_invalid: {exc}") from exc
+    if _digest(plan.model_dump(mode="json")) != plan.digest:
+        raise EnvironmentPlanError("environment_plan_digest_mismatch")
+    if bundle is not None:
+        expected = create_environment_plan(
+            source=PlanSource(
+                kind=bundle.provenance.source_kind,
+                repository=bundle.provenance.repository,
+                commit_sha=bundle.provenance.commit,
+                source_digest=bundle.provenance.source_digest,
+            ),
+            runtime=bundle.runtime,
+            services=bundle.services,
+            capabilities=bundle.capabilities,
+            readiness=bundle.readiness,
+            metadata=plan.metadata,
+        )
+        if expected.digest != plan.digest:
+            raise EnvironmentPlanError("environment_plan_bundle_mismatch")
+    return plan
+
+
+__all__ = [
+    "ENVIRONMENT_PLAN_FILE",
+    "ENVIRONMENT_PLAN_SCHEMA_VERSION",
+    "EnvironmentPlan",
+    "EnvironmentPlanError",
+    "PlanSource",
+    "create_environment_plan",
+    "load_environment_plan",
+    "write_environment_plan",
+]

fi/alk/harness/events.py

@@ -0,0 +1,125 @@
+"""Durable harness progress delivery for both local and hosted execution."""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from threading import RLock
+from typing import Protocol
+
+from fi.simulate.runtime.events import CanonicalEvent
+
+
+class EventTransport(Protocol):
+    """Platform boundary. Implementations must be idempotent by ``event_id``."""
+
+    def send(self, run_id: str, events: list[CanonicalEvent]) -> set[str]: ...
+
+
+class EventOutbox:
+    """Append-only event journal with a durable acknowledgement cursor.
+
+    Every event lands locally before a network attempt. A killed local CLI or hosted sandbox can
+    reopen the outbox and retry without losing progress; the platform deduplicates event IDs.
+    """
+
+    def __init__(self, root: str | Path, run_id: str) -> None:
+        self.root = Path(root).expanduser().resolve() / run_id
+        self.root.mkdir(parents=True, exist_ok=True)
+        self.events_path = self.root / "harness-events.jsonl"
+        self.acked_path = self.root / "harness-events.acked.json"
+        self._lock = RLock()
+
+    def append(self, event: CanonicalEvent) -> None:
+        with self._lock, self.events_path.open("a", encoding="utf-8") as stream:
+            stream.write(event.model_dump_json(exclude_none=True) + "\n")
+            stream.flush()
+            os.fsync(stream.fileno())
+
+    def pending(self) -> list[CanonicalEvent]:
+        acknowledged = self.acknowledged()
+        if not self.events_path.exists():
+            return []
+        events: list[CanonicalEvent] = []
+        with self._lock, self.events_path.open(encoding="utf-8") as stream:
+            for number, line in enumerate(stream, start=1):
+                if not line.strip():
+                    continue
+                try:
+                    event = CanonicalEvent.model_validate_json(line)
+                except ValueError as exc:
+                    raise ValueError(
+                        f"event_outbox_corrupt: line {number}: {exc}"
+                    ) from exc
+                if event.event_id not in acknowledged:
+                    events.append(event)
+        return events
+
+    def acknowledged(self) -> set[str]:
+        if not self.acked_path.exists():
+            return set()
+        try:
+            value = json.loads(self.acked_path.read_text(encoding="utf-8"))
+        except (OSError, ValueError) as exc:
+            raise ValueError(f"event_acknowledgements_corrupt: {exc}") from exc
+        return {str(item) for item in value.get("event_ids", [])}
+
+    def acknowledge(self, event_ids: set[str]) -> None:
+        if not event_ids:
+            return
+        with self._lock:
+            all_ids = self.acknowledged() | event_ids
+            temporary = self.acked_path.with_suffix(".tmp")
+            temporary.write_text(
+                json.dumps({"event_ids": sorted(all_ids)}, separators=(",", ":"))
+                + "\n",
+                encoding="utf-8",
+            )
+            temporary.replace(self.acked_path)
+
+
+class BufferedEventSink:
+    """Write-through local sink with best-effort, retryable platform delivery."""
+
+    def __init__(
+        self,
+        outbox: EventOutbox,
+        transport: EventTransport | None = None,
+        *,
+        batch_size: int = 100,
+    ) -> None:
+        self.outbox = outbox
+        self.transport = transport
+        self.batch_size = max(1, batch_size)
+
+    def write(self, event: CanonicalEvent) -> None:
+        self.outbox.append(event)
+        if self.transport is not None:
+            try:
+                self.flush(limit=self.batch_size)
+            except Exception:
+                # Execution is authoritative; telemetry is retried from the durable outbox.
+                pass
+
+    def flush(self, *, limit: int | None = None) -> int:
+        if self.transport is None:
+            return 0
+        pending = self.outbox.pending()
+        if limit is not None:
+            pending = pending[:limit]
+        delivered = 0
+        for start in range(0, len(pending), self.batch_size):
+            batch = pending[start : start + self.batch_size]
+            accepted = self.transport.send(batch[0].run_id, batch)
+            expected = {event.event_id for event in batch}
+            # A transport may acknowledge a subset. Everything else remains pending.
+            acknowledged = expected & set(accepted)
+            self.outbox.acknowledge(acknowledged)
+            delivered += len(acknowledged)
+            if acknowledged != expected:
+                break
+        return delivered
+
+
+__all__ = ["BufferedEventSink", "EventOutbox", "EventTransport"]