karta-runtime 0.1.0__py3-none-any.whl

karta/__init__.py

@@ -0,0 +1,48 @@
+from karta.agent import Agent
+from karta.app import Karta
+from karta.gateway import (
+    Gateway,
+    GatewayDelivery,
+    GatewayEvent,
+    HttpGateway,
+    LocalGateway,
+    ParticipantRegistry,
+)
+from karta.hub import KartaHub
+from karta.instance import AgentInstance, InstanceManager, InstanceSession, InstanceStore
+from karta.participant import AIAgent, HumanAgent, Participant
+from karta.policies import PolicyViolationError
+from karta.registry import ProjectRegistry, PublishedProject
+from karta.response import Message, Part, Response, StreamEvent, Usage
+from karta.session import Session
+from karta.workspace import UserProjectView, WorkspaceManager
+
+__all__ = [
+    "AgentInstance",
+    "Karta",
+    "Agent",
+    "AIAgent",
+    "Gateway",
+    "GatewayDelivery",
+    "GatewayEvent",
+    "HttpGateway",
+    "HumanAgent",
+    "InstanceManager",
+    "InstanceSession",
+    "InstanceStore",
+    "KartaHub",
+    "LocalGateway",
+    "Message",
+    "Part",
+    "Participant",
+    "ParticipantRegistry",
+    "PolicyViolationError",
+    "ProjectRegistry",
+    "PublishedProject",
+    "Response",
+    "Session",
+    "StreamEvent",
+    "Usage",
+    "UserProjectView",
+    "WorkspaceManager",
+]

karta/__main__.py

@@ -0,0 +1,4 @@
+from karta.cli import main
+
+if __name__ == "__main__":
+    main()

karta/active_releases.py

@@ -0,0 +1,129 @@
+"""Active-release resolution for the data plane.
+
+When a session is created for a project URL, the data plane must learn
+WHICH materialized release to run. karta-web is authoritative: it owns
+the ``AgentProject#current_release`` pointer that the deploy/activate
+flow flips. This module fetches that pointer for an ``(org, project)``
+pair and caches it briefly so the hot path doesn't round-trip the
+control plane on every session create.
+
+Mirrors :mod:`karta.model_settings` in shape (cached control-plane GET,
+``OrgScopedTtlCache`` keyed by org first so push-invalidation matches).
+The returned :class:`ActiveRelease` carries the project's numeric id and
+version, which :mod:`karta.project_runtime` turns into a deterministic
+on-disk template path via :func:`karta.releases.template_path_for`.
+
+Nothing here is secret: a template path / commit sha / version is
+operational metadata already surfaced in dashboards, so no scrubbing.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+from urllib.parse import quote
+
+from karta import observability as obs
+from karta.cache import OrgScopedTtlCache, env_number
+from karta.control_plane import ControlPlaneUnavailable, control_plane_get
+
+logger = obs.get_logger("karta.active_releases")
+
+
+@dataclass(frozen=True)
+class ActiveRelease:
+    """The project's currently-active release, as resolved by karta-web."""
+
+    project_id: int
+    version: int
+    build_kind: str
+    template_path: Optional[str]
+    commit_sha: Optional[str]
+    status: Optional[str] = None
+    image_ref: Optional[str] = None
+
+
+# Keyed by (organization_id, project_ref) so invalidate_org matches on
+# the first tuple element. TTL is short by default: the cached value
+# carries the active version, so a longer window means a freshly
+# activated release keeps serving the OLD version until expiry. A new
+# session is cheap to mis-route only within this window; in-flight
+# sessions are pinned to their start version regardless (see
+# project_runtime). karta-web push-invalidates on activate when wired.
+_CACHE_TTL_SECONDS = env_number("KARTA_ACTIVE_RELEASE_CACHE_TTL", 10.0, float)
+_cache: OrgScopedTtlCache[ActiveRelease] = OrgScopedTtlCache(_CACHE_TTL_SECONDS)
+
+
+def reset_active_release_cache() -> None:
+    """Test/ops hook: drop all cached active-release entries."""
+    _cache.clear()
+
+
+def invalidate_active_release_for_org(organization_id: int) -> int:
+    """Drop every cached active-release entry for ``organization_id``.
+
+    Called when karta-web posts a CacheInvalidationJob after a release
+    is activated or rolled back. Returns the number of entries evicted.
+    """
+    return _cache.invalidate_org(organization_id)
+
+
+def fetch_active_release(
+    *,
+    organization_id: int,
+    project_ref: str,
+    control_plane_url: Optional[str] = None,
+    service_token: Optional[str] = None,
+) -> Optional[ActiveRelease]:
+    """Return the active release for ``(organization_id, project_ref)``.
+
+    ``project_ref`` is the project slug from the project URL. Returns
+    ``None`` when the project has no active release, is unknown, or the
+    control plane is unreachable. The two are distinguished by caching:
+    a definitive miss (404 / non-200) is negative-cached; an outage
+    (:class:`ControlPlaneUnavailable`) is not, so the next create retries.
+    """
+    key = (organization_id, project_ref)
+    hit, cached = _cache.get(key)
+    if hit:
+        return cached
+
+    path = f"/internal/projects/{quote(project_ref, safe='')}/active_release"
+    try:
+        payload = control_plane_get(
+            path,
+            params={"organization_id": organization_id},
+            control_plane_url=control_plane_url,
+            service_token=service_token,
+        )
+    except ControlPlaneUnavailable:
+        return None
+
+    if payload is None:
+        _cache.put(key, None)
+        return None
+
+    project_id = payload.get("project_id")
+    version = payload.get("version")
+    if not isinstance(project_id, int) or not isinstance(version, int):
+        # Malformed answer — treat as a definitive miss rather than
+        # constructing a half-formed release we can't resolve a path for.
+        logger.warning(
+            "active_release for org=%s project=%s missing project_id/version",
+            organization_id,
+            project_ref,
+        )
+        _cache.put(key, None)
+        return None
+
+    release = ActiveRelease(
+        project_id=project_id,
+        version=version,
+        build_kind=str(payload.get("build_kind") or "file_copy"),
+        template_path=(str(payload["template_path"]) if payload.get("template_path") else None),
+        commit_sha=(str(payload["commit_sha"]) if payload.get("commit_sha") else None),
+        status=(str(payload["status"]) if payload.get("status") else None),
+        image_ref=(str(payload["image_ref"]) if payload.get("image_ref") else None),
+    )
+    _cache.put(key, release)
+    return release

karta/agent.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, AsyncIterator, Dict, Optional
+
+from karta.harness.base import AgentDefinition
+from karta.response import Response, StreamEvent
+
+if TYPE_CHECKING:
+    from karta.app import Karta
+
+
+class Agent:
+    def __init__(self, app: "Karta", definition: AgentDefinition) -> None:
+        self._app = app
+        self.definition = definition
+
+    @property
+    def name(self) -> str:
+        return self.definition.name
+
+    async def send(
+        self,
+        text: str,
+        *,
+        metadata: Optional[Dict[str, Any]] = None,
+        thinking: bool = False,
+    ) -> Response:
+        return await self._app.send(text, metadata=metadata, agent=self, thinking=thinking)
+
+    def send_sync(
+        self,
+        text: str,
+        *,
+        metadata: Optional[Dict[str, Any]] = None,
+        thinking: bool = False,
+    ) -> Response:
+        return self._app.send_sync(text, metadata=metadata, agent=self, thinking=thinking)
+
+    async def stream(
+        self,
+        text: str,
+        *,
+        metadata: Optional[Dict[str, Any]] = None,
+        thinking: bool = False,
+    ) -> AsyncIterator[StreamEvent]:
+        async for event in self._app.stream(text, metadata=metadata, agent=self, thinking=thinking):
+            yield event
+
+    def stream_sync(
+        self,
+        text: str,
+        *,
+        metadata: Optional[Dict[str, Any]] = None,
+        thinking: bool = False,
+    ):
+        return self._app.stream_sync(text, metadata=metadata, agent=self, thinking=thinking)
+
+    def __repr__(self) -> str:
+        return f"Agent(name={self.name!r})"