maivn 0.2.0__py3-none-any.whl

maivn/__init__.py

@@ -0,0 +1,265 @@
+"""Top-level SDK exports for Maivn.
+Re-exports clients, agents, decorators, logging, and configuration.
+Configuration mutation helpers are intentionally not exported to avoid external rewiring.
+"""
+
+from __future__ import annotations
+
+# MARK: - Shared Models
+from maivn_shared import (
+    HIPAA_SAFE_HARBOR_CATEGORIES,
+    MemoryAssetsConfig,
+    MemoryConfig,
+    MemoryInsightExtractionConfig,
+    MemoryLevel,
+    MemoryPersistenceMode,
+    MemoryResourceConfig,
+    MemoryRetrievalConfig,
+    MemorySharingScope,
+    MemorySkillConfig,
+    MemorySkillExtractionConfig,
+    PIIWhitelist,
+    PIIWhitelistEntry,
+    PrivateData,
+    RedactedMessage,
+    RedactionPreviewRequest,
+    RedactionPreviewResponse,
+    SessionExecutionConfig,
+    SessionOrchestrationConfig,
+    StructuredOutputConfig,
+    SwarmAgentConfig,
+    SwarmConfig,
+    SystemToolsConfig,
+)
+
+# MARK: - Version
+from .__version__ import __version__
+
+# MARK: - Core Classes
+from ._internal.api import (
+    Agent,
+    BaseScope,
+    Client,
+    ClientBuilder,
+    MCPAutoSetup,
+    MCPServer,
+    MCPSoftErrorHandling,
+    Swarm,
+)
+from ._internal.api.resource_models import (
+    MemoryInsight,
+    MemoryInsightOrigin,
+    MemoryInsightType,
+    MemoryPersistenceCeiling,
+    MemoryResource,
+    MemoryResourceBindingType,
+    MemoryResourceDetail,
+    MemoryResourceStatus,
+    MemorySkill,
+    MemorySkillOrigin,
+    MemorySkillStatus,
+    MemoryUnboundResourceCandidate,
+    OrganizationMemoryPolicy,
+    OrganizationMemoryPurgeResult,
+    ProjectMemoryResources,
+)
+
+# MARK: - Scheduling
+from ._internal.api.scheduling import (
+    AtSchedule,
+    CronInvocationBuilder,
+    CronSchedule,
+    IntervalSchedule,
+    JitterDistribution,
+    JitterSpec,
+    MisfirePolicy,
+    OverlapPolicy,
+    Retry,
+    RetryBackoff,
+    RunRecord,
+    RunStatus,
+    Schedule,
+    ScheduledJob,
+    list_jobs,
+    stop_all_jobs,
+)
+
+# MARK: - Interrupts
+from ._internal.core.services.interrupt_service import (
+    default_terminal_interrupt,
+    get_interrupt_service,
+    set_interrupt_service,
+)
+
+# MARK: - Decorators
+from ._internal.utils import (
+    compose_artifact_policy,
+    depends_on_agent,
+    depends_on_await_for,
+    depends_on_interrupt,
+    depends_on_private_data,
+    depends_on_reevaluate,
+    depends_on_tool,
+)
+
+# MARK: - Configuration
+from ._internal.utils.configuration import (
+    ConfigurationBuilder,
+    MaivnConfiguration,
+    get_configuration,
+)
+
+# MARK: - Logging
+# Logging must be importable before other modules to allow early configuration
+from ._internal.utils.logging import (
+    configure_logging,
+    get_logger,
+)
+from .events import (
+    APP_EVENT_CONTRACT_VERSION,
+    AppEvent,
+    BackpressurePolicy,
+    BridgeAudience,
+    BridgeRegistry,
+    EventBridge,
+    EventBridgeSecurityPolicy,
+    NormalizedEventForwardingState,
+    NormalizedStreamState,
+    RawSSEEvent,
+    UIEvent,
+    build_agent_assignment_payload,
+    build_assistant_chunk_payload,
+    build_enrichment_payload,
+    build_error_payload,
+    build_final_payload,
+    build_interrupt_required_payload,
+    build_session_start_payload,
+    build_status_message_payload,
+    build_system_tool_chunk_payload,
+    build_system_tool_complete_payload,
+    build_system_tool_start_payload,
+    build_tool_event_payload,
+    forward_normalized_event,
+    forward_normalized_stream,
+    normalize_stream,
+    normalize_stream_event,
+)
+
+# MARK: - Public API
+
+__all__ = [
+    # Version
+    "__version__",
+    # Logging
+    "configure_logging",
+    "get_logger",
+    # Event Contract
+    "APP_EVENT_CONTRACT_VERSION",
+    "AppEvent",
+    "BackpressurePolicy",
+    "BridgeAudience",
+    "BridgeRegistry",
+    "EventBridge",
+    "EventBridgeSecurityPolicy",
+    "NormalizedEventForwardingState",
+    "NormalizedStreamState",
+    "RawSSEEvent",
+    "UIEvent",
+    "build_agent_assignment_payload",
+    "build_assistant_chunk_payload",
+    "build_enrichment_payload",
+    "build_error_payload",
+    "build_final_payload",
+    "build_interrupt_required_payload",
+    "build_session_start_payload",
+    "build_status_message_payload",
+    "build_system_tool_chunk_payload",
+    "build_system_tool_complete_payload",
+    "build_system_tool_start_payload",
+    "build_tool_event_payload",
+    "forward_normalized_event",
+    "forward_normalized_stream",
+    "normalize_stream",
+    "normalize_stream_event",
+    # Decorators
+    "compose_artifact_policy",
+    "depends_on_agent",
+    "depends_on_await_for",
+    "depends_on_private_data",
+    "depends_on_interrupt",
+    "depends_on_reevaluate",
+    "depends_on_tool",
+    # Core Classes
+    "Agent",
+    "BaseScope",
+    "Client",
+    "ClientBuilder",
+    "MCPAutoSetup",
+    "MCPServer",
+    "MCPSoftErrorHandling",
+    "Swarm",
+    "OrganizationMemoryPolicy",
+    "OrganizationMemoryPurgeResult",
+    "MemoryPersistenceCeiling",
+    "MemoryResource",
+    "MemoryResourceDetail",
+    "MemoryResourceBindingType",
+    "MemoryResourceStatus",
+    "MemorySkill",
+    "MemorySkillOrigin",
+    "MemorySkillStatus",
+    "MemoryInsight",
+    "MemoryInsightType",
+    "MemoryInsightOrigin",
+    "MemoryUnboundResourceCandidate",
+    "ProjectMemoryResources",
+    # Shared Models
+    "HIPAA_SAFE_HARBOR_CATEGORIES",
+    "PIIWhitelist",
+    "PIIWhitelistEntry",
+    "PrivateData",
+    "MemoryConfig",
+    "MemoryAssetsConfig",
+    "MemoryInsightExtractionConfig",
+    "MemoryLevel",
+    "MemoryPersistenceMode",
+    "MemoryResourceConfig",
+    "MemoryRetrievalConfig",
+    "MemorySharingScope",
+    "MemorySkillConfig",
+    "MemorySkillExtractionConfig",
+    "SessionExecutionConfig",
+    "SessionOrchestrationConfig",
+    "StructuredOutputConfig",
+    "SwarmAgentConfig",
+    "SwarmConfig",
+    "SystemToolsConfig",
+    "RedactedMessage",
+    "RedactionPreviewRequest",
+    "RedactionPreviewResponse",
+    # Configuration
+    "ConfigurationBuilder",
+    "MaivnConfiguration",
+    "get_configuration",
+    # Interrupts
+    "default_terminal_interrupt",
+    "get_interrupt_service",
+    "set_interrupt_service",
+    # Scheduling
+    "AtSchedule",
+    "CronInvocationBuilder",
+    "CronSchedule",
+    "IntervalSchedule",
+    "JitterDistribution",
+    "JitterSpec",
+    "MisfirePolicy",
+    "OverlapPolicy",
+    "Retry",
+    "RetryBackoff",
+    "RunRecord",
+    "RunStatus",
+    "Schedule",
+    "ScheduledJob",
+    "list_jobs",
+    "stop_all_jobs",
+]

maivn/__version__.py

@@ -0,0 +1,10 @@
+"""Package version for the maivn SDK.
+Exposed via ``maivn.__version__`` for tooling and client diagnostics.
+"""
+
+# MARK: Version
+from __future__ import annotations
+
+__all__ = ["__version__"]
+
+__version__ = "0.2.0"

maivn/_internal/adapters/__init__.py

@@ -0,0 +1 @@
+"""Internal Adapters Package Exports."""

maivn/_internal/adapters/networking/__init__.py

@@ -0,0 +1,17 @@
+"""Networking infrastructure.
+Provides HTTP and SSE client implementations for orchestrator communication.
+"""
+
+from __future__ import annotations
+
+# MARK: - Imports
+from .http_client import HttpClient, HttpError
+from .sse_client import StreamingSSEClient
+
+# MARK: - Exports
+
+__all__ = [
+    "HttpClient",
+    "HttpError",
+    "StreamingSSEClient",
+]

maivn/_internal/adapters/networking/http_client.py

@@ -0,0 +1,41 @@
+"""HTTP client wrapper using maivn-core shared implementation.
+
+This module provides the HTTP client implementation using the shared
+maivn-core HttpClient for consistent behavior across services.
+"""
+
+from __future__ import annotations
+
+from maivn_shared import HttpClient as CoreHttpClient
+from maivn_shared import HttpError
+
+from maivn._internal.utils.configuration import get_configuration
+
+# MARK: - HttpClient
+
+
+class HttpClient(CoreHttpClient):
+    """HTTP client implementation using maivn-core shared client.
+
+    This class extends the core HttpClient with SDK-specific configuration.
+    """
+
+    # MARK: - Initialization
+
+    def __init__(self, *, timeout: float | None = None) -> None:
+        """Initialize the HTTP client with SDK configuration.
+
+        Args:
+            timeout: Default timeout for requests
+        """
+        config = get_configuration()
+        sdk_timeout = timeout if timeout is not None else config.server.timeout_seconds
+        super().__init__(timeout=sdk_timeout)
+
+
+# MARK: - Exports
+
+__all__ = [
+    "HttpClient",
+    "HttpError",
+]

maivn/_internal/adapters/networking/sse_client.py

@@ -0,0 +1,153 @@
+"""Server-Sent Events (SSE) client implementation.
+
+This module provides a production-ready SSE client using urllib for HTTP streaming.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from typing import IO, cast
+
+from maivn_shared import loads
+
+from maivn._internal.core import SSEClient, SSEEvent
+
+# MARK: - StreamingSSEClient
+
+
+class StreamingSSEClient(SSEClient):
+    """urllib-based SSE client for production use.
+
+    This client implements the SSE protocol for consuming server-sent event streams
+    over HTTP. It handles event parsing and yields structured SSEEvent objects.
+    """
+
+    # MARK: - Initialization
+
+    def __init__(self, *, timeout: float = 600.0) -> None:
+        """Initialize the SSE client.
+
+        Args:
+            timeout: Request timeout in seconds (default: 600.0)
+        """
+        self._timeout = timeout
+
+    # MARK: - Public Methods
+
+    def iter_events(
+        self,
+        url: str,
+        *,
+        headers: dict[str, str] | None = None,
+    ) -> Iterator[SSEEvent]:
+        """Iterate over server-sent events from the given URL.
+
+        Args:
+            url: The SSE endpoint URL to connect to
+            headers: Optional HTTP headers to include with the SSE request
+
+        Yields:
+            SSEEvent objects parsed from the event stream
+
+        Raises:
+            URLError: If the connection fails
+            TimeoutError: If the request times out
+        """
+        from urllib.request import Request, urlopen
+
+        self._validate_stream_url(url)
+        merged_headers: dict[str, str] = {}
+        if headers:
+            merged_headers = {
+                key: value for key, value in headers.items() if key.lower() != "accept"
+            }
+        merged_headers["Accept"] = "text/event-stream"
+        req = Request(url, headers=merged_headers)
+        try:
+            # _validate_stream_url rejects file: and custom schemes before urlopen.
+            with cast(
+                IO[bytes],
+                urlopen(req, timeout=self._timeout),  # noqa: S310  # nosec B310
+            ) as resp:
+                buf = b""
+                while True:
+                    chunk = resp.readline()
+                    if not chunk:
+                        raise RuntimeError(
+                            "SSE stream closed unexpectedly. The server may have stopped, "
+                            "the connection may have been interrupted, "
+                            "or the session may have ended."
+                        )
+                    buf += chunk
+                    if self._is_event_complete(buf):
+                        yield self._parse_event(buf)
+                        buf = b""
+        except Exception as exc:  # noqa: BLE001
+            raise RuntimeError(
+                "Failed to read SSE event stream. The server may be unreachable "
+                "or closed the connection."
+            ) from exc
+
+    # MARK: - Private Methods
+
+    @staticmethod
+    def _validate_stream_url(url: str) -> None:
+        """Reject local-file and custom-scheme URLs before urllib opens them."""
+        from urllib.parse import urlsplit
+
+        parsed = urlsplit(url)
+        if parsed.scheme not in {"http", "https"} or not parsed.netloc:
+            raise ValueError("SSE stream URL must be an absolute http:// or https:// URL")
+
+    def _is_event_complete(self, buf: bytes) -> bool:
+        """Check if the buffer contains a complete SSE event.
+
+        Args:
+            buf: The accumulated byte buffer
+
+        Returns:
+            True if the buffer ends with a double newline delimiter
+        """
+        return buf.endswith(b"\n\n") or buf.endswith(b"\r\n\r\n")
+
+    def _parse_event(self, buf: bytes) -> SSEEvent:
+        """Parse a complete SSE event from the buffer.
+
+        Args:
+            buf: The byte buffer containing a complete event
+
+        Returns:
+            Parsed SSEEvent object
+        """
+        lines = buf.decode("utf-8", errors="replace").splitlines()
+        event_name = "message"
+        data_lines: list[str] = []
+
+        for line in lines:
+            if line.startswith("event:"):
+                event_name = line.split(":", 1)[1].strip()
+            elif line.startswith("data:"):
+                data_lines.append(line.split(":", 1)[1].strip())
+
+        data = "\n".join(data_lines) if data_lines else "{}"
+        payload = self._parse_payload(data)
+        return SSEEvent(name=event_name, payload=payload)
+
+    def _parse_payload(self, data: str) -> dict:
+        """Parse the event data payload as JSON.
+
+        Args:
+            data: The raw data string from the event
+
+        Returns:
+            Parsed dictionary or fallback with raw data
+        """
+        if not data:
+            return {}
+        try:
+            return loads(data)
+        except Exception:
+            return {"raw": data}
+
+
+__all__ = ["StreamingSSEClient"]

maivn/_internal/adapters/repositories/__init__.py

@@ -0,0 +1,22 @@
+"""Infrastructure repository implementations.
+Provides in-memory repositories for agents, tools, and dependencies.
+Used as default wiring for scopes and orchestration.
+"""
+
+from __future__ import annotations
+
+# MARK: Repository Exports
+# MARK: - Agent Repository
+from .agent_repo import AgentRepo
+
+# MARK: - Dependency Repository
+from .dependency_repo import DependencyRepo
+
+# MARK: - Tool Repository
+from .tool_repo import ToolRepo
+
+__all__ = [
+    "AgentRepo",
+    "DependencyRepo",
+    "ToolRepo",
+]

maivn/_internal/adapters/repositories/agent_repo.py

@@ -0,0 +1,73 @@
+"""In-memory agent repository implementation.
+Stores agents by id and maintains a secondary name index for lookup.
+"""
+
+from __future__ import annotations
+
+# MARK: In-Memory Agent Repository
+from typing import TYPE_CHECKING
+
+from maivn._internal.core.interfaces.repositories import AgentRepoInterface
+
+if TYPE_CHECKING:
+    from maivn._internal.api.agent import Agent
+
+
+class AgentRepo(AgentRepoInterface):
+    """In-memory implementation of AgentRepoInterface."""
+
+    def __init__(self) -> None:
+        self.store: dict[str, Agent] = {}
+        self._name_index: dict[str, Agent] = {}
+
+    # MARK: - Private methods
+
+    def _get_agent_id(self, agent: Agent) -> str | None:
+        return getattr(agent, "id", None)
+
+    def _get_agent_name(self, agent: Agent) -> str | None:
+        return getattr(agent, "name", None)
+
+    def _add_to_name_index(self, agent: Agent) -> None:
+        name = self._get_agent_name(agent)
+        if name:
+            self._name_index[name] = agent
+
+    def _remove_from_name_index(self, agent: Agent) -> None:
+        name = self._get_agent_name(agent)
+        if name and name in self._name_index:
+            del self._name_index[name]
+
+    # MARK: - Agent methods
+
+    def add_agent(self, agent: Agent) -> None:
+        if agent is None:
+            return
+        agent_id = self._get_agent_id(agent)
+        if not agent_id or agent_id in self.store:
+            return
+        self.store[agent_id] = agent
+        self._add_to_name_index(agent)
+
+    def get_agent(self, agent_id: str) -> Agent | None:
+        return self.store.get(agent_id)
+
+    def get_agent_by_name(self, name: str) -> Agent | None:
+        return self._name_index.get(name)
+
+    def list_agents(self) -> list[Agent]:
+        return list(self.store.values())
+
+    def remove_agent(self, agent_id: str) -> None:
+        agent = self.store.pop(agent_id, None)
+        if agent:
+            self._remove_from_name_index(agent)
+
+    def update_agent(self, agent: Agent) -> None:
+        agent_id = self._get_agent_id(agent)
+        if not agent_id:
+            return
+        if agent_id in self.store:
+            self._remove_from_name_index(self.store[agent_id])
+        self.store[agent_id] = agent
+        self._add_to_name_index(agent)

maivn/_internal/adapters/repositories/dependency_repo.py

@@ -0,0 +1,91 @@
+"""In-memory dependency repository implementation.
+Stores dependency lists keyed by tool id.
+"""
+
+from __future__ import annotations
+
+# MARK: In-Memory Dependency Repository
+from maivn_shared import BaseDependency, InterruptDependency, dumps
+
+from maivn._internal.core.interfaces.repositories import DependencyRepoInterface
+
+
+class DependencyRepo(DependencyRepoInterface):
+    """In-memory implementation of DependencyRepoInterface."""
+
+    def __init__(self) -> None:
+        self.store: dict[str, list[BaseDependency]] = {}
+
+    # MARK: - Private Helpers
+
+    def _get_dependency_id(self, dependency: BaseDependency) -> str | None:
+        dep_type = getattr(dependency, "dependency_type", None)
+        arg_name = getattr(dependency, "arg_name", None)
+
+        if isinstance(dependency, InterruptDependency):
+            return dumps(
+                {
+                    "dependency_type": dep_type or "user",
+                    "arg_name": arg_name,
+                    "prompt": getattr(dependency, "prompt", None),
+                }
+            )
+
+        identifier = (
+            getattr(dependency, "tool_id", None)
+            or getattr(dependency, "agent_id", None)
+            or getattr(dependency, "data_key", None)
+            or getattr(dependency, "name", None)
+        )
+        if dep_type or arg_name or identifier:
+            return dumps(
+                {
+                    "dependency_type": dep_type,
+                    "arg_name": arg_name,
+                    "identifier": str(identifier) if identifier else None,
+                }
+            )
+
+        try:
+            return dumps(dependency.model_dump(mode="json"))
+        except Exception:
+            return str(dependency)
+
+    def _find_dependency_index(self, deps: list[BaseDependency], dependency_id: str) -> int | None:
+        for i, dep in enumerate(deps):
+            if self._get_dependency_id(dep) == dependency_id:
+                return i
+        return None
+
+    # MARK: - Dependency Methods
+
+    def add_dependency(self, tool_id: str, dependency: BaseDependency) -> None:
+        if not tool_id or dependency is None:
+            return
+        self.store.setdefault(tool_id, []).append(dependency)
+
+    def get_dependency(self, dependency_id: str) -> BaseDependency | None:
+        for deps in self.store.values():
+            for dep in deps:
+                if self._get_dependency_id(dep) == dependency_id:
+                    return dep
+        return None
+
+    def list_dependencies(self, tool_id: str) -> list[BaseDependency]:
+        return list(self.store.get(tool_id, []))
+
+    def remove_dependency(self, dependency_id: str) -> None:
+        for tool_id, deps in list(self.store.items()):
+            idx = self._find_dependency_index(deps, dependency_id)
+            if idx is not None:
+                deps.pop(idx)
+                if not deps:
+                    del self.store[tool_id]
+                return
+
+    def update_dependency(self, dependency_id: str, dependency: BaseDependency) -> None:
+        for deps in self.store.values():
+            idx = self._find_dependency_index(deps, dependency_id)
+            if idx is not None:
+                deps[idx] = dependency
+                return