dreamer-server 0.1.0__py3-none-any.whl

dreamer/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

dreamer/api/__init__.py

@@ -0,0 +1,152 @@
+"""Public framework interfaces.
+
+Stable surface for component authors: Protocols, capability Protocols,
+data types, errors, and the `@implements` decorator. Everything in
+`dreamer.api.*` is the externally consumable contract.
+"""
+
+from dreamer.api.audit import AuditSink
+from dreamer.api.auth import AuthBackend, Tenancy
+from dreamer.api.capabilities import (
+    Lifecycle,
+    Middlewares,
+    Routes,
+    Transactional,
+)
+from dreamer.api.compat import SUPPORTED_PROTOCOL_VERSIONS, implements
+from dreamer.api.dream import ContextPhaseRunner, DreamGate, LTMPhaseRunner
+from dreamer.api.errors import (
+    AuthError,
+    ConfigError,
+    DreamerError,
+    DreamFailedError,
+    LeaseHeldError,
+    ProtocolComplianceError,
+    TenantDataError,
+    ValidationError,
+    WorkspaceError,
+)
+from dreamer.api.hooks import (
+    DreamFailedHook,
+    DreamProgressHook,
+    PostContextUpdateHook,
+    PostDreamHook,
+    PostLTMUpdateHook,
+    PostMemorySubmitHook,
+    PreContextUpdateHook,
+    PreDreamHook,
+    PreLTMUpdateHook,
+    PreMemorySubmitHook,
+)
+from dreamer.api.jobs import DreamJob, JobQueue
+from dreamer.api.rate_limit import RateLimitDecision, RateLimiter
+from dreamer.api.secrets import SecretResolver, SecretRotationHook, SecretValue
+from dreamer.api.stores import (
+    ContextPendingStore,
+    ContextReader,
+    ContextStore,
+    DreamLeaseStore,
+    LTMStore,
+    MCPTool,
+    STMSerializer,
+    STMStore,
+)
+from dreamer.api.tenants import (
+    TenantConfigProvider,
+    TenantData,
+    TenantLifecycle,
+    TenantRegistry,
+    TenantScope,
+)
+from dreamer.api.triggers import Trigger
+from dreamer.api.types import (
+    DEFAULT_TENANT_ID,
+    AuditEvent,
+    Diff,
+    DreamLease,
+    FileViewable,
+    GateDecision,
+    GraphViewable,
+    Memory,
+    MemoryBatch,
+    MemoryType,
+    Principal,
+    RecordViewable,
+    TenantConfig,
+    TenantId,
+    UsageEvent,
+    Workspace,
+)
+from dreamer.api.usage import UsageSink
+
+__all__ = [
+    "DEFAULT_TENANT_ID",
+    "SUPPORTED_PROTOCOL_VERSIONS",
+    "AuditEvent",
+    "AuditSink",
+    "AuthBackend",
+    "AuthError",
+    "ConfigError",
+    "ContextPendingStore",
+    "ContextPhaseRunner",
+    "ContextReader",
+    "ContextStore",
+    "Diff",
+    "DreamFailedError",
+    "DreamFailedHook",
+    "DreamGate",
+    "DreamJob",
+    "DreamLease",
+    "DreamLeaseStore",
+    "DreamProgressHook",
+    "DreamerError",
+    "FileViewable",
+    "GateDecision",
+    "GraphViewable",
+    "JobQueue",
+    "LTMPhaseRunner",
+    "LTMStore",
+    "LeaseHeldError",
+    "Lifecycle",
+    "MCPTool",
+    "Memory",
+    "MemoryBatch",
+    "MemoryType",
+    "Middlewares",
+    "PostContextUpdateHook",
+    "PostDreamHook",
+    "PostLTMUpdateHook",
+    "PostMemorySubmitHook",
+    "PreContextUpdateHook",
+    "PreDreamHook",
+    "PreLTMUpdateHook",
+    "PreMemorySubmitHook",
+    "Principal",
+    "ProtocolComplianceError",
+    "RateLimitDecision",
+    "RateLimiter",
+    "RecordViewable",
+    "Routes",
+    "STMSerializer",
+    "STMStore",
+    "SecretResolver",
+    "SecretRotationHook",
+    "SecretValue",
+    "Tenancy",
+    "TenantConfig",
+    "TenantConfigProvider",
+    "TenantData",
+    "TenantDataError",
+    "TenantId",
+    "TenantLifecycle",
+    "TenantRegistry",
+    "TenantScope",
+    "Transactional",
+    "Trigger",
+    "UsageEvent",
+    "UsageSink",
+    "ValidationError",
+    "Workspace",
+    "WorkspaceError",
+    "implements",
+]

dreamer/api/audit.py

@@ -0,0 +1,22 @@
+"""AuditSink Protocol + re-export of AuditEvent."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, ClassVar, Protocol, runtime_checkable
+
+from dreamer.api.types import AuditEvent
+
+if TYPE_CHECKING:
+    from dreamer.api.contexts import AuditContext
+
+
+@runtime_checkable
+class AuditSink(Protocol):
+    """Append-only event trail. Distinct from `UsageSink` (compliance, not billing)."""
+
+    multi_tenant: ClassVar[bool] = False
+
+    async def record(self, event: AuditEvent, *, ctx: AuditContext) -> None: ...
+
+
+__all__ = ["AuditEvent", "AuditSink"]

dreamer/api/auth.py

@@ -0,0 +1,37 @@
+"""AuthBackend and Tenancy Protocols."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, ClassVar, Protocol, runtime_checkable
+
+from dreamer.api.types import Principal, TenantId
+
+if TYPE_CHECKING:
+    from starlette.requests import Request
+
+    from dreamer.api.contexts import AuthContext, TenancyContext
+
+
+@runtime_checkable
+class AuthBackend(Protocol):
+    """Authenticates a request and produces a Principal.
+
+    Backends MAY also expose Routes and/or Middlewares capabilities (login flows,
+    session middleware). Simple bearer-token impls only implement `authenticate`.
+    """
+
+    multi_tenant: ClassVar[bool] = False
+
+    async def authenticate(self, request: Request, *, ctx: AuthContext) -> Principal: ...
+
+
+@runtime_checkable
+class Tenancy(Protocol):
+    """Override point for deriving tenant id from principal."""
+
+    multi_tenant: ClassVar[bool] = False
+
+    async def tenant_for(self, principal: Principal, *, ctx: TenancyContext) -> TenantId: ...
+
+
+__all__ = ["AuthBackend", "Tenancy"]

dreamer/api/capabilities.py

@@ -0,0 +1,78 @@
+"""Optional capability Protocols.
+
+These are *additional* Protocols that any component may implement. The runtime
+probes via `isinstance(component, Capability)` (works because they're
+`@runtime_checkable`) and uses them if present.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, ClassVar, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from starlette.applications import Starlette
+    from starlette.middleware import Middleware
+
+    from dreamer.api.contexts import (
+        LifecycleContext,
+        MiddlewaresContext,
+        RoutesContext,
+        TxBeginContext,
+        TxCommitContext,
+        TxPrepareContext,
+        TxRollbackContext,
+    )
+
+
+TxHandle = Any
+
+
+@runtime_checkable
+class Lifecycle(Protocol):
+    """Component lifecycle hooks dispatched at server start/stop."""
+
+    multi_tenant: ClassVar[bool] = False
+
+    async def start(self, *, ctx: LifecycleContext) -> None: ...
+    async def stop(self, *, ctx: LifecycleContext) -> None: ...
+
+
+@runtime_checkable
+class Routes(Protocol):
+    """Mount HTTP routes on the Starlette app at server boot."""
+
+    multi_tenant: ClassVar[bool] = False
+
+    def register_routes(self, app: Starlette, *, ctx: RoutesContext) -> None: ...
+
+
+@runtime_checkable
+class Middlewares(Protocol):
+    """Provide ASGI middleware factories to install at server boot."""
+
+    multi_tenant: ClassVar[bool] = False
+
+    def middlewares(self, *, ctx: MiddlewaresContext) -> list[Middleware]: ...
+
+
+@runtime_checkable
+class Transactional(Protocol):
+    """Optional. When present on both `LTMStore` and `ContextStore`, the
+    orchestrator will use a two-phase commit across the dream's LTM and Context
+    updates."""
+
+    multi_tenant: ClassVar[bool] = False
+
+    async def begin(self, *, ctx: TxBeginContext) -> TxHandle: ...
+    async def prepare(self, tx: TxHandle, *, ctx: TxPrepareContext) -> bool: ...
+    async def commit(self, tx: TxHandle, *, ctx: TxCommitContext) -> None: ...
+    async def rollback(self, tx: TxHandle, *, ctx: TxRollbackContext) -> None: ...
+
+
+__all__ = [
+    "Lifecycle",
+    "Middlewares",
+    "Routes",
+    "Transactional",
+    "TxHandle",
+]

dreamer/api/compat.py

@@ -0,0 +1,139 @@
+"""`@implements(protocol, version)` decorator + `SUPPORTED_PROTOCOL_VERSIONS`.
+
+A class decorated with `@implements(P, version=N)` records the declaration on
+the class itself in the `__dreamer_protocols__: dict[type, int]` attribute.
+Multiple `@implements` decorators accumulate (one class can implement many
+Protocols at once).
+
+The framework's compatibility window per Protocol is read from
+`SUPPORTED_PROTOCOL_VERSIONS` during startup compliance checks.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import TypeVar
+
+from dreamer.api.audit import AuditSink
+from dreamer.api.auth import AuthBackend, Tenancy
+from dreamer.api.capabilities import (
+    Lifecycle,
+    Middlewares,
+    Routes,
+    Transactional,
+)
+from dreamer.api.dream import (
+    ContextPhaseRunner,
+    DreamGate,
+    LTMPhaseRunner,
+)
+from dreamer.api.hooks import (
+    DreamFailedHook,
+    DreamProgressHook,
+    PostContextUpdateHook,
+    PostDreamHook,
+    PostLTMUpdateHook,
+    PostMemorySubmitHook,
+    PreContextUpdateHook,
+    PreDreamHook,
+    PreLTMUpdateHook,
+    PreMemorySubmitHook,
+)
+from dreamer.api.jobs import JobQueue
+from dreamer.api.rate_limit import RateLimiter
+from dreamer.api.secrets import SecretResolver, SecretRotationHook
+from dreamer.api.stores import (
+    ContextPendingStore,
+    ContextReader,
+    ContextStore,
+    DreamLeaseStore,
+    LTMStore,
+    MCPTool,
+    STMSerializer,
+    STMStore,
+)
+from dreamer.api.tenants import (
+    TenantConfigProvider,
+    TenantData,
+    TenantLifecycle,
+    TenantRegistry,
+)
+from dreamer.api.triggers import Trigger
+from dreamer.api.types import (
+    FileViewable,
+    GraphViewable,
+    RecordViewable,
+    Workspace,
+)
+from dreamer.api.usage import UsageSink
+
+T = TypeVar("T", bound=type)
+
+
+def implements(protocol: type, *, version: int) -> Callable[[T], T]:
+    """Decorator: declare that a class implements `protocol` at `version`.
+
+    Stores the declaration on the class itself in
+    `__dreamer_protocols__: dict[type, int]`. Multiple `@implements` decorators
+    on the same class accumulate (one class may implement many Protocols).
+    """
+
+    def deco(cls: T) -> T:
+        existing: dict[type, int] = dict(getattr(cls, "__dreamer_protocols__", {}))
+        existing[protocol] = version
+        cls.__dreamer_protocols__ = existing  # type: ignore[attr-defined]
+        return cls
+
+    return deco
+
+
+SUPPORTED_PROTOCOL_VERSIONS: dict[type, frozenset[int]] = {
+    AuthBackend: frozenset({1}),
+    Tenancy: frozenset({1}),
+    STMStore: frozenset({1}),
+    LTMStore: frozenset({1}),
+    ContextPendingStore: frozenset({1}),
+    ContextStore: frozenset({1}),
+    DreamLeaseStore: frozenset({1}),
+    LTMPhaseRunner: frozenset({1}),
+    ContextPhaseRunner: frozenset({1}),
+    Trigger: frozenset({1}),
+    PreMemorySubmitHook: frozenset({1}),
+    PostMemorySubmitHook: frozenset({1}),
+    PreDreamHook: frozenset({1}),
+    PostDreamHook: frozenset({1}),
+    PreLTMUpdateHook: frozenset({1}),
+    PostLTMUpdateHook: frozenset({1}),
+    PreContextUpdateHook: frozenset({1}),
+    PostContextUpdateHook: frozenset({1}),
+    DreamFailedHook: frozenset({1}),
+    Lifecycle: frozenset({1}),
+    Routes: frozenset({1}),
+    Middlewares: frozenset({1}),
+    Transactional: frozenset({1}),
+    Workspace: frozenset({1}),
+    FileViewable: frozenset({1}),
+    RecordViewable: frozenset({1}),
+    GraphViewable: frozenset({1}),
+    TenantRegistry: frozenset({1}),
+    TenantConfigProvider: frozenset({1}),
+    TenantLifecycle: frozenset({1}),
+    TenantData: frozenset({1}),
+    JobQueue: frozenset({1}),
+    SecretResolver: frozenset({1}),
+    SecretRotationHook: frozenset({1}),
+    UsageSink: frozenset({1}),
+    AuditSink: frozenset({1}),
+    RateLimiter: frozenset({1}),
+    MCPTool: frozenset({1}),
+    STMSerializer: frozenset({1}),
+    ContextReader: frozenset({1}),
+    DreamGate: frozenset({1}),
+    DreamProgressHook: frozenset({1}),
+}
+
+
+__all__ = [
+    "SUPPORTED_PROTOCOL_VERSIONS",
+    "implements",
+]