agentlings 0.2.0__py3-none-any.whl

agentlings/core/telemetry.py

@@ -0,0 +1,181 @@
+"""OpenTelemetry setup and instrumentation for the agent lifecycle."""
+
+from __future__ import annotations
+
+import logging
+from contextlib import contextmanager
+from typing import Any, Generator
+
+from agentlings.config import TelemetryConfig
+
+logger = logging.getLogger(__name__)
+
+_tracer: Any = None
+_meter: Any = None
+_initialized = False
+
+
+def init_telemetry(config: TelemetryConfig) -> None:
+    """Configure OpenTelemetry tracer and meter providers.
+
+    No-op if telemetry is disabled or already initialized.
+
+    Args:
+        config: Telemetry configuration from the agent YAML.
+    """
+    global _tracer, _meter, _initialized
+
+    if _initialized or not config.enabled:
+        return
+
+    try:
+        from opentelemetry import metrics, trace
+        from opentelemetry.exporter.otlp.proto.http.metric_exporter import OTLPMetricExporter
+        from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+        from opentelemetry.sdk.metrics import MeterProvider
+        from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader
+        from opentelemetry.sdk.resources import Resource
+        from opentelemetry.sdk.trace import TracerProvider
+        from opentelemetry.sdk.trace.export import BatchSpanProcessor
+
+        resource = Resource.create({"service.name": config.service_name})
+
+        headers = config.headers or {}
+
+        if config.protocol == "grpc":
+            from opentelemetry.exporter.otlp.proto.grpc.metric_exporter import (
+                OTLPMetricExporter as GrpcMetricExporter,
+            )
+            from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import (
+                OTLPSpanExporter as GrpcSpanExporter,
+            )
+            span_exporter = GrpcSpanExporter(
+                endpoint=config.endpoint,
+                insecure=config.insecure,
+                headers=headers or None,
+            )
+            metric_exporter = GrpcMetricExporter(
+                endpoint=config.endpoint,
+                insecure=config.insecure,
+                headers=headers or None,
+            )
+        else:
+            span_exporter = OTLPSpanExporter(
+                endpoint=f"{config.endpoint}/v1/traces",
+                headers=headers or None,
+            )
+            metric_exporter = OTLPMetricExporter(
+                endpoint=f"{config.endpoint}/v1/metrics",
+                headers=headers or None,
+            )
+
+        tracer_provider = TracerProvider(resource=resource)
+        tracer_provider.add_span_processor(BatchSpanProcessor(span_exporter))
+        trace.set_tracer_provider(tracer_provider)
+
+        metric_reader = PeriodicExportingMetricReader(metric_exporter)
+        meter_provider = MeterProvider(resource=resource, metric_readers=[metric_reader])
+        metrics.set_meter_provider(meter_provider)
+
+        _tracer = trace.get_tracer("agentling")
+        _meter = metrics.get_meter("agentling")
+        _initialized = True
+
+        logger.info(
+            "telemetry initialized: endpoint=%s, protocol=%s",
+            config.endpoint, config.protocol,
+        )
+    except ImportError:
+        logger.warning(
+            "opentelemetry packages not installed, telemetry disabled — "
+            "install with: pip install opentelemetry-api opentelemetry-sdk opentelemetry-exporter-otlp"
+        )
+    except Exception:
+        logger.exception("failed to initialize telemetry")
+
+
+def get_tracer() -> Any:
+    """Return the configured tracer, or a no-op proxy if telemetry is not initialized."""
+    if _tracer is not None:
+        return _tracer
+
+    try:
+        from opentelemetry import trace
+        return trace.get_tracer("agentling")
+    except ImportError:
+        return _NoOpTracer()
+
+
+def get_meter() -> Any:
+    """Return the configured meter, or a no-op proxy if telemetry is not initialized."""
+    if _meter is not None:
+        return _meter
+
+    try:
+        from opentelemetry import metrics
+        return metrics.get_meter("agentling")
+    except ImportError:
+        return _NoOpMeter()
+
+
+@contextmanager
+def otel_span(name: str, attributes: dict[str, Any] | None = None) -> Generator[Any, None, None]:
+    """Context manager that creates a traced span.
+
+    Args:
+        name: Span name (e.g. ``"agentling.loop.process_message"``).
+        attributes: Span attributes to set on creation.
+
+    Yields:
+        The span object (or a no-op if telemetry is disabled).
+    """
+    tracer = get_tracer()
+    with tracer.start_as_current_span(name) as span:
+        if attributes:
+            for k, v in attributes.items():
+                span.set_attribute(k, v)
+        yield span
+
+
+sleep_span = otel_span
+
+
+class _NoOpSpan:
+    def set_attribute(self, key: str, value: Any) -> None:
+        pass
+
+    def add_event(self, name: str, attributes: dict[str, Any] | None = None) -> None:
+        pass
+
+    def __enter__(self) -> _NoOpSpan:
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        pass
+
+
+class _NoOpTracer:
+    def start_as_current_span(self, name: str, **kwargs: Any) -> _NoOpSpan:
+        return _NoOpSpan()
+
+    def start_span(self, name: str, **kwargs: Any) -> _NoOpSpan:
+        return _NoOpSpan()
+
+
+class _NoOpMeter:
+    def create_histogram(self, name: str, **kwargs: Any) -> _NoOpInstrument:
+        return _NoOpInstrument()
+
+    def create_counter(self, name: str, **kwargs: Any) -> _NoOpInstrument:
+        return _NoOpInstrument()
+
+    def create_up_down_counter(self, name: str, **kwargs: Any) -> _NoOpInstrument:
+        return _NoOpInstrument()
+
+
+class _NoOpInstrument:
+    def record(self, value: Any, attributes: dict[str, Any] | None = None) -> None:
+        pass
+
+    def add(self, value: Any, attributes: dict[str, Any] | None = None) -> None:
+        pass

agentlings/log.py

@@ -0,0 +1,23 @@
+"""Console-first logging configuration.
+
+Format: ``datetime - level - path - message``, output to stderr.
+"""
+
+import logging
+import sys
+
+
+def setup_logging(level: str = "INFO") -> None:
+    """Configure the root logger with the agentlings format.
+
+    Args:
+        level: Log level name (e.g. ``"INFO"``, ``"DEBUG"``).
+    """
+    handler = logging.StreamHandler(sys.stderr)
+    handler.setFormatter(
+        logging.Formatter("%(asctime)s - %(levelname)s - %(name)s - %(message)s")
+    )
+
+    root = logging.getLogger()
+    root.setLevel(getattr(logging, level.upper(), logging.INFO))
+    root.addHandler(handler)

agentlings/migrations/__init__.py

@@ -0,0 +1,37 @@
+"""Forward-only data-layout migrations applied by ``agentling upgrade``.
+
+Each migration is a module exporting:
+
+- ``ID: str`` — a stable identifier (typically the module name)
+- ``DESCRIPTION: str`` — one-line human-readable summary
+- ``apply(data_dir: Path) -> None`` — idempotent transformation
+
+Migrations are discovered at import time and ordered by their numeric prefix.
+"""
+
+from __future__ import annotations
+
+import importlib
+import pkgutil
+from pathlib import Path
+from typing import Protocol
+
+
+class Migration(Protocol):
+    ID: str
+    DESCRIPTION: str
+
+    def apply(self, data_dir: Path) -> None: ...
+
+
+def discover() -> list[Migration]:
+    """Return all migration modules in this package, ordered by ID."""
+    migrations: list[Migration] = []
+    for info in pkgutil.iter_modules(__path__):
+        if info.name.startswith("_"):
+            continue
+        module = importlib.import_module(f"{__name__}.{info.name}")
+        if hasattr(module, "ID") and hasattr(module, "apply"):
+            migrations.append(module)  # type: ignore[arg-type]
+    migrations.sort(key=lambda m: m.ID)
+    return migrations

agentlings/migrations/m0001_seed.py

@@ -0,0 +1,17 @@
+"""Seed migration — establishes the migration log without changing data.
+
+Acts as a no-op so the runner has at least one migration to find on a fresh
+install. Real schema migrations land alongside this one as future framework
+versions ship.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+ID = "0001_seed"
+DESCRIPTION = "Initialise migration log"
+
+
+def apply(data_dir: Path) -> None:  # noqa: ARG001
+    return None

agentlings/protocol/__init__.py

@@ -0,0 +1 @@
+"""Protocol adapters for A2A and MCP, plus Agent Card generation."""

agentlings/protocol/a2a.py

@@ -0,0 +1,220 @@
+"""A2A protocol executor bridging incoming requests into the task engine.
+
+SendMessage spawns a task in the shared engine and awaits up to
+``AGENT_TASK_AWAIT_SECONDS``. If the task completes in the await window, the
+final response is returned as a plain agent ``Message``. Otherwise a native
+A2A ``Task`` object (``status.state == working``) is enqueued so the caller
+can poll via ``GetTask`` — those GetTask calls are routed back to our engine
+by ``EngineTaskStore`` so the SDK's answers always reflect live state.
+
+Cancellation (``CancelTask``) hits the engine's cancel path by task id.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+
+from a2a.helpers.proto_helpers import new_text_message
+from a2a.server.agent_execution import AgentExecutor
+from a2a.server.agent_execution.context import RequestContext
+from a2a.server.events import EventQueue
+from a2a.types import Message, Role
+
+from agentlings.config import AgentConfig
+from agentlings.core.loop import MessageLoop
+from agentlings.core.task import (
+    ContextBusyError,
+    TaskNotFoundError,
+    TaskState,
+    TaskStatus,
+)
+from agentlings.protocol.a2a_task_store import task_state_to_a2a_task
+
+logger = logging.getLogger(__name__)
+
+
+def _agent_text_message(
+    text: str,
+    *,
+    context_id: str | None = None,
+    task_id: str | None = None,
+) -> Message:
+    """Build an agent-role ``Message`` proto carrying a single text part.
+
+    Replaces the removed ``a2a.utils.new_agent_text_message`` helper. The
+    proto ``Message`` requires a ``message_id`` and has no field presence on
+    string fields, so empty-string defaults are used when ids are unset.
+    """
+    return new_text_message(
+        text,
+        context_id=context_id or "",
+        task_id=task_id or "",
+        role=Role.ROLE_AGENT,
+    )
+
+
+class AgentlingExecutor(AgentExecutor):
+    """Executes A2A requests by forwarding user input through the shared task engine."""
+
+    def __init__(self, loop: MessageLoop, config: AgentConfig) -> None:
+        self._loop = loop
+        self._engine = loop.engine
+        self._await_seconds = float(config.agent_task_await_seconds)
+
+    async def execute(
+        self, context: RequestContext, event_queue: EventQueue
+    ) -> None:
+        """Process an incoming A2A request and enqueue the agent's response.
+
+        Enqueues either a ``Message`` (fast path, completed) or a native
+        ``Task`` object (slow path, still working) depending on whether the
+        task finished within the configured await window.
+        """
+        user_text = context.get_user_input()
+        context_id = context.context_id
+        # The A2A SDK generates a task_id for every inbound SendMessage. We
+        # must use that same id inside the engine so GetTask lookups (routed
+        # through EngineTaskStore) and the Task object we enqueue all agree.
+        sdk_task_id = context.task_id
+
+        logger.debug(
+            "a2a execute: context_id=%s task_id=%s text=%r",
+            context_id,
+            sdk_task_id,
+            (user_text or "")[:100],
+        )
+
+        try:
+            state = await self._engine.spawn(
+                message=user_text,
+                context_id=context_id,
+                via="a2a",
+                await_seconds=self._await_seconds,
+                task_id=sdk_task_id,
+            )
+        except ContextBusyError as e:
+            # Surface as a plain agent message — there is no live Task on this
+            # context that the caller can latch onto (it's someone else's).
+            await event_queue.enqueue_event(
+                _agent_text_message(
+                    _format_busy(e),
+                    context_id=context_id,
+                )
+            )
+            await event_queue.close()
+            return
+        except Exception:  # noqa: BLE001
+            logger.exception("error processing A2A message")
+            await event_queue.enqueue_event(
+                _agent_text_message(
+                    "Internal error processing request.",
+                    context_id=context_id,
+                )
+            )
+            await event_queue.close()
+            return
+
+        if state.status == TaskStatus.COMPLETED:
+            # Fast path — return the final response text as a Message event.
+            response_text = _extract_text(state.content)
+            await event_queue.enqueue_event(
+                _agent_text_message(
+                    response_text,
+                    context_id=state.context_id,
+                    task_id=state.task_id,
+                )
+            )
+        else:
+            # Slow path or terminal-with-error — enqueue a native A2A Task so
+            # the client's GetTask/CancelTask flows reach our engine.
+            a2a_task = task_state_to_a2a_task(state)
+            await event_queue.enqueue_event(a2a_task)
+
+        logger.debug(
+            "a2a response: context_id=%s status=%s task_id=%s",
+            state.context_id, state.status.value, state.task_id,
+        )
+        await event_queue.close()
+
+    async def cancel(
+        self, context: RequestContext, event_queue: EventQueue
+    ) -> None:
+        """Handle A2A ``CancelTask`` by routing to the engine's cancel path.
+
+        ``RequestContext.task_id`` is populated from the inbound request,
+        which (for our clients) is the engine's task_id — the Task object
+        enqueued on the slow path carries that id directly.
+        """
+        task_id = context.task_id
+        if not task_id:
+            await event_queue.enqueue_event(
+                _agent_text_message(
+                    "CancelTask requires a task_id.",
+                    context_id=context.context_id,
+                )
+            )
+            await event_queue.close()
+            return
+
+        try:
+            state = await self._engine.cancel(task_id=task_id)
+        except TaskNotFoundError:
+            await event_queue.enqueue_event(
+                _agent_text_message(
+                    f"Task {task_id} not found.",
+                    context_id=context.context_id,
+                )
+            )
+            await event_queue.close()
+            return
+        except Exception:  # noqa: BLE001
+            logger.exception("cancel failed for task %s", task_id)
+            await event_queue.enqueue_event(
+                _agent_text_message(
+                    "Internal error during cancel.",
+                    context_id=context.context_id,
+                )
+            )
+            await event_queue.close()
+            return
+
+        # Enqueue the updated Task so the SDK relays the cancelled state.
+        await event_queue.enqueue_event(task_state_to_a2a_task(state))
+        await event_queue.close()
+
+
+def _format_busy(e: ContextBusyError) -> str:
+    envelope = {
+        "status": "busy",
+        "error": "context_busy",
+        "contextId": e.context_id,
+        "activeTaskId": e.active_task_id,
+        "message": (
+            f"Context {e.context_id} is busy with task {e.active_task_id}. "
+            "Retry shortly."
+        ),
+    }
+    return json.dumps(envelope)
+
+
+def _extract_text(content: list[dict]) -> str:
+    parts = []
+    for block in content:
+        if block.get("type") == "text":
+            parts.append(block.get("text", ""))
+    return "\n".join(parts)
+
+
+def _format_state(state: TaskState, await_seconds: float) -> str:
+    """Legacy helper kept for backwards compatibility in tests."""
+    if state.status == TaskStatus.COMPLETED:
+        return _extract_text(state.content)
+    envelope = {
+        "status": state.status.value,
+        "taskId": state.task_id,
+        "contextId": state.context_id,
+    }
+    if state.error:
+        envelope["error"] = state.error
+    return json.dumps(envelope)

agentlings/protocol/a2a_task_store.py

@@ -0,0 +1,150 @@
+"""Bridge from the A2A SDK's ``TaskStore`` interface to our ``TaskEngine``.
+
+The A2A SDK's ``DefaultRequestHandler`` consults an injected ``TaskStore``
+when a client calls ``GetTask``. Rather than duplicate state in an
+``InMemoryTaskStore``, this bridge delegates every lookup to the engine so
+the SDK's answers always reflect live state.
+
+- ``get(task_id)`` → polls the engine, translates ``TaskState`` → ``a2a.Task``.
+- ``save(task)`` is a no-op; the engine is authoritative.
+- ``delete(task_id)`` is a no-op; retention follows the engine's lifecycle.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from a2a.server.context import ServerCallContext
+from a2a.server.tasks.task_store import TaskStore
+from a2a.types import (
+    ListTasksRequest,
+    ListTasksResponse,
+    Message,
+    Part,
+    Role,
+    Task,
+    TaskState as A2ATaskState,
+    TaskStatus as A2ATaskStatus,
+)
+
+from agentlings.core.task import (
+    TaskEngine,
+    TaskNotFoundError,
+    TaskState,
+    TaskStatus,
+)
+
+logger = logging.getLogger(__name__)
+
+
+_STATE_MAP: dict[TaskStatus, int] = {
+    TaskStatus.WORKING: A2ATaskState.TASK_STATE_WORKING,
+    TaskStatus.CANCELLING: A2ATaskState.TASK_STATE_WORKING,
+    TaskStatus.COMPLETED: A2ATaskState.TASK_STATE_COMPLETED,
+    TaskStatus.FAILED: A2ATaskState.TASK_STATE_FAILED,
+    TaskStatus.CANCELLED: A2ATaskState.TASK_STATE_CANCELED,
+}
+
+
+def task_state_to_a2a_task(state: TaskState) -> Task:
+    """Render an engine ``TaskState`` as an A2A ``Task`` for the wire.
+
+    Completed tasks carry their final assistant message in ``history`` so
+    ``GetTask`` responses are self-contained — the client doesn't need a
+    separate call to retrieve the result.
+    """
+    history: list[Message] = []
+    if state.status == TaskStatus.COMPLETED and state.content:
+        text = _extract_text(state.content)
+        if text:
+            history.append(
+                Message(
+                    role=Role.ROLE_AGENT,
+                    parts=[Part(text=text)],
+                    context_id=state.context_id,
+                    task_id=state.task_id,
+                    message_id=f"{state.task_id}-final",
+                )
+            )
+
+    status_kwargs: dict[str, Any] = {"state": _STATE_MAP[state.status]}
+    if state.error and state.status in (TaskStatus.FAILED, TaskStatus.CANCELLED):
+        status_kwargs["message"] = Message(
+            role=Role.ROLE_AGENT,
+            parts=[Part(text=state.error)],
+            context_id=state.context_id,
+            task_id=state.task_id,
+            message_id=f"{state.task_id}-status",
+        )
+
+    return Task(
+        id=state.task_id,
+        context_id=state.context_id,
+        status=A2ATaskStatus(**status_kwargs),
+        history=history,
+    )
+
+
+def _extract_text(content: list[dict[str, Any]]) -> str:
+    parts = []
+    for block in content:
+        if block.get("type") == "text":
+            parts.append(block.get("text", ""))
+    return "\n".join(parts)
+
+
+class EngineTaskStore(TaskStore):
+    """A2A SDK ``TaskStore`` backed by our ``TaskEngine``.
+
+    GetTask requests reaching the SDK's ``DefaultRequestHandler`` are routed
+    through this store. The handler calls ``get`` and returns the resulting
+    ``Task`` to the client.
+    """
+
+    def __init__(self, engine: TaskEngine) -> None:
+        self._engine = engine
+
+    async def get(
+        self, task_id: str, context: ServerCallContext | None = None
+    ) -> Task | None:
+        """Translate ``engine.poll(task_id)`` into an A2A ``Task``.
+
+        Returns ``None`` if the engine has no record of the task (so the SDK
+        produces its own ``task_not_found`` error).
+        """
+        try:
+            state = await self._engine.poll(task_id=task_id, wait_seconds=0)
+        except TaskNotFoundError:
+            return None
+        except Exception:  # noqa: BLE001
+            logger.exception("EngineTaskStore.get failed for task %s", task_id)
+            return None
+        return task_state_to_a2a_task(state)
+
+    async def save(
+        self, task: Task, context: ServerCallContext | None = None
+    ) -> None:
+        """No-op. The engine is the source of truth; SDK saves are advisory."""
+        logger.debug("EngineTaskStore.save ignored for task %s", task.id)
+
+    async def delete(
+        self, task_id: str, context: ServerCallContext | None = None
+    ) -> None:
+        """No-op. Retention follows the engine's lifecycle, not SDK calls."""
+        logger.debug("EngineTaskStore.delete ignored for task %s", task_id)
+
+    async def list(
+        self,
+        params: ListTasksRequest,
+        context: ServerCallContext | None = None,
+    ) -> ListTasksResponse:
+        """Return an empty listing — the engine doesn't expose a task index.
+
+        The SDK's ``ListTasks`` RPC is optional; agentling doesn't advertise
+        the capability, so callers shouldn't invoke this. We return an empty
+        response rather than raise so the handler stays well-behaved if a
+        request slips through.
+        """
+        logger.debug("EngineTaskStore.list returning empty response")
+        return ListTasksResponse()