mark-sdk 0.2.0a5__py3-none-any.whl

mark/__init__.py

@@ -0,0 +1,173 @@
+"""Local-first MARK runtime SDK."""
+
+from mark._version import __version__
+from mark.agent import AgentResult, MarkAgent
+from mark.context import ContextBundle, ContextBuilder
+from mark.embeddings import CachedEmbeddingProvider, EmbeddingProvider, HashEmbeddingProvider
+from mark.index import VectorIndex, VectorSearchResult
+from mark.intelligence import (
+    ContextualCompressor,
+    KeywordQueryExpander,
+    LLMContextualCompressor,
+    LLMQueryExpander,
+    NoopCompressor,
+    NoopQueryExpander,
+    QueryExpander,
+    RetrievalPipeline,
+    RetrievalPolicy,
+    RetrievalResult,
+    SessionFilter,
+    SimpleWindowCompressor,
+)
+from mark.memory import (
+    BlockChain,
+    BlockGraph,
+    BlockVerification,
+    BusMessage,
+    BusSnapshot,
+    BusSubscription,
+    ChainVerification,
+    ClusterResult,
+    ConversationMemory,
+    DeduplicationConsolidator,
+    DeduplicationResult,
+    GlobalMemoryBus,
+    GraphNeighborhood,
+    MarkMemory,
+    MarkRuntime,
+    MemoryBlock,
+    MemoryManager,
+    MemoryRecord,
+    MemoryState,
+    MemoryWriteRejection,
+    ObserveEvent,
+    ObserveResult,
+    PublisherTrust,
+    SimpleMemory,
+    SimpleBlock,
+    TrustAwareGlobalMemoryBus,
+)
+from mark.governance import (
+    AuditEntry,
+    ConsolidationGate,
+    ConsolidationGateResult,
+    ContentSanitizer,
+    DuplicateHashGate,
+    FailureFilter,
+    GateResult,
+    GovernanceAuditLog,
+    ValidationGate,
+)
+from mark.intelligence import (
+    DeterministicExtractor,
+    ExtractionMerger,
+    ExtractionResult,
+    ExtractedEntity,
+    ExtractedRelation,
+    LLMStructuredExtractor,
+    StructuredExtraction,
+)
+from mark.media import CharacterMemory, LocationMemory, ObjectMemory, SessionMemory, WorldBibleMemory
+from mark.plugins import HOOK_OBSERVE_EVENT
+from mark.policies import PolicyDecision, PolicyRegistry
+from mark.runtime import Mark, MarkConfig
+from mark.skills import AgentPersona, SkillRegistry
+from mark.store import LocalMemoryStore, SessionActivityLog
+from mark.types import BlockLink, BlockStatus
+from mark.types.llm import LLMProvider
+from mark.observability import EventReplayer, LocalTracer, RuntimeEvent, RuntimeEventLog, SessionTrace
+from mark.sync import CloudSync, SyncDelta, SyncMode, SyncOptions, SyncStats
+
+__all__ = [
+    "AgentResult",
+    "AgentPersona",
+    "AuditEntry",
+    "BlockChain",
+    "BlockGraph",
+    "BlockLink",
+    "BlockStatus",
+    "BlockVerification",
+    "ChainVerification",
+    "BusMessage",
+    "BusSnapshot",
+    "BusSubscription",
+    "CachedEmbeddingProvider",
+    "CharacterMemory",
+    "ClusterResult",
+    "ConsolidationGate",
+    "ConsolidationGateResult",
+    "ContentSanitizer",
+    "ConversationMemory",
+    "ContextBuilder",
+    "ContextBundle",
+    "ContextualCompressor",
+    "DeduplicationConsolidator",
+    "DeduplicationResult",
+    "DeterministicExtractor",
+    "DuplicateHashGate",
+    "CloudSync",
+    "EmbeddingProvider",
+    "EventReplayer",
+    "FailureFilter",
+    "GateResult",
+    "GovernanceAuditLog",
+    "ExtractionMerger",
+    "ExtractionResult",
+    "ExtractedEntity",
+    "ExtractedRelation",
+    "GlobalMemoryBus",
+    "GraphNeighborhood",
+    "HashEmbeddingProvider",
+    "HOOK_OBSERVE_EVENT",
+    "KeywordQueryExpander",
+    "LLMContextualCompressor",
+    "LLMProvider",
+    "LLMQueryExpander",
+    "LLMStructuredExtractor",
+    "LocalMemoryStore",
+    "LocalTracer",
+    "LocationMemory",
+    "Mark",
+    "MarkAgent",
+    "MarkConfig",
+    "MarkMemory",
+    "MarkRuntime",
+    "MemoryBlock",
+    "MemoryManager",
+    "MemoryRecord",
+    "MemoryState",
+    "MemoryWriteRejection",
+    "NoopCompressor",
+    "NoopQueryExpander",
+    "ObjectMemory",
+    "ObserveEvent",
+    "ObserveResult",
+    "PolicyDecision",
+    "PolicyRegistry",
+    "PublisherTrust",
+    "QueryExpander",
+    "RetrievalPipeline",
+    "RuntimeEvent",
+    "RuntimeEventLog",
+    "RetrievalPolicy",
+    "RetrievalResult",
+    "SessionActivityLog",
+    "SessionTrace",
+    "SyncMode",
+    "SyncDelta",
+    "SyncOptions",
+    "SyncStats",
+    "SessionFilter",
+    "SessionMemory",
+    "SimpleBlock",
+    "SimpleMemory",
+    "SimpleWindowCompressor",
+    "StructuredExtraction",
+    "SkillRegistry",
+    "TrustAwareGlobalMemoryBus",
+    "ValidationGate",
+    "VectorIndex",
+    "VectorSearchResult",
+    "WorldBibleMemory",
+    "__version__",
+]

mark/_version.py

@@ -0,0 +1,3 @@
+"""Package version metadata."""
+
+__version__ = "0.2.0a5"

mark/adapters/__init__.py

@@ -0,0 +1,9 @@
+"""Optional framework adapters bundled with mark-sdk.
+
+The adapter namespace is MIT framework glue. It must call public MARK APIs and
+must not implement proprietary MARK Cloud intelligence.
+"""
+
+from mark.adapters.backend import BackendResult, LocalMarkBackend, MarkBackend
+
+__all__ = ["BackendResult", "LocalMarkBackend", "MarkBackend"]

mark/adapters/backend.py

@@ -0,0 +1,131 @@
+"""Framework-neutral backend protocol for MARK adapters."""
+
+from __future__ import annotations
+
+import inspect
+from dataclasses import dataclass, field
+from typing import Any, Protocol
+
+
+@dataclass(frozen=True)
+class BackendResult:
+    """Small framework-neutral result envelope used by adapter helpers."""
+
+    ok: bool
+    value: Any = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+    error: str | None = None
+
+
+class MarkBackend(Protocol):
+    """Public backend protocol implemented by local and cloud MARK adapters."""
+
+    async def retrieve(self, query: str, **options: Any) -> BackendResult:
+        """Retrieve memory relevant to the query."""
+        ...
+    async def write(self, content: str, **options: Any) -> BackendResult:
+        """Write content into memory."""
+        ...
+    async def observe(self, content: str, **options: Any) -> BackendResult:
+        """Record an observation through the backend."""
+        ...
+    async def compress(self, query: str, candidates: list[Any], **options: Any) -> BackendResult:
+        """Reduce candidate fragments to query-relevant evidence."""
+        ...
+    async def heal_gap(self, query: str, **options: Any) -> BackendResult:
+        """Attempt explicit gap healing for the query."""
+        ...
+    async def list_sessions(self, agent_id: str, **options: Any) -> BackendResult:
+        """Return known session ids for the agent."""
+        ...
+    async def feedback(self, **payload: Any) -> BackendResult:
+        """Submit a feedback signal."""
+        ...
+
+
+class LocalMarkBackend:
+    """Adapter backend over local ``mark.Mark`` or ``mark.MarkRuntime`` objects."""
+
+    def __init__(self, mark: Any, *, default_agent_id: str = "__mark__") -> None:
+        self.mark = mark
+        self.default_agent_id = default_agent_id
+
+    async def retrieve(self, query: str, **options: Any) -> BackendResult:
+        """Retrieve memory relevant to the query."""
+        try:
+            memory = self._memory(options.pop("agent_id", self.default_agent_id))
+            options.pop("blocks", None)  # MarkMemory.retrieve_sync does not accept blocks
+            if hasattr(memory, "retrieve_sync"):
+                result = memory.retrieve_sync(query, **options)
+                return BackendResult(True, result)
+            result = self.mark.memory.retrieve(query, **options)
+            return BackendResult(True, result)
+        except Exception as exc:
+            return BackendResult(False, error=str(exc))
+
+    async def write(self, content: str, **options: Any) -> BackendResult:
+        """Write content into memory."""
+        try:
+            memory = self._memory(options.pop("agent_id", self.default_agent_id))
+            if hasattr(memory, "store_sync"):
+                fragment_id = memory.store_sync(content, **options)
+                return BackendResult(True, fragment_id, {"fragment_id": fragment_id})
+            block = self.mark.memory.block(options.pop("block", "adapter"))
+            record = block.write(content, **options)
+            return BackendResult(True, record, {"record_id": getattr(record, "id", "")})
+        except Exception as exc:
+            return BackendResult(False, error=str(exc))
+
+    async def observe(self, content: str, **options: Any) -> BackendResult:
+        """Record an observation through the backend."""
+        try:
+            agent_id = options.pop("agent_id", self.default_agent_id)
+            if hasattr(self.mark, "observe"):
+                result = self.mark.observe(content, agent_id=agent_id, **options)
+            else:
+                result = self._memory(agent_id).observe(content, **options)
+            return BackendResult(True, result, {"fragment_id": getattr(result, "fragment_id", "")})
+        except Exception as exc:
+            return BackendResult(False, error=str(exc))
+
+    async def compress(self, query: str, candidates: list[Any], **options: Any) -> BackendResult:
+        # Local compression is performed during retrieve(compress=True). This method
+        # exists so framework adapters can share a protocol with cloud backends.
+        """Reduce candidate fragments to query-relevant evidence."""
+        return BackendResult(True, candidates, {"local_passthrough": True, "query": query, **options})
+
+    async def heal_gap(self, query: str, **options: Any) -> BackendResult:
+        """Attempt explicit gap healing for the query."""
+        options["heal_gaps"] = True
+        return await self.retrieve(query, **options)
+
+    async def list_sessions(self, agent_id: str, **options: Any) -> BackendResult:
+        """Return known session ids for the agent."""
+        try:
+            memory = self._memory(agent_id)
+            if hasattr(memory, "list_sessions"):
+                return BackendResult(True, memory.list_sessions())
+            return BackendResult(True, [])
+        except Exception as exc:
+            return BackendResult(False, error=str(exc))
+
+    async def feedback(self, **payload: Any) -> BackendResult:
+        """Submit a feedback signal."""
+        try:
+            if hasattr(self.mark, "memory") and hasattr(self.mark.memory, "feedback"):
+                feedback = self.mark.memory.feedback
+                params = inspect.signature(feedback).parameters
+                if all(key in params for key in payload):
+                    feedback(**payload)
+                    return BackendResult(True, payload)
+                return BackendResult(True, payload, {"skipped": "incompatible_feedback_signature"})
+            return BackendResult(True, payload, {"skipped": "feedback_unavailable"})
+        except Exception as exc:
+            return BackendResult(False, error=str(exc))
+
+    def _memory(self, agent_id: str) -> Any:
+        if hasattr(self.mark, "runtime") and hasattr(self.mark.runtime, "memory"):
+            return self.mark.runtime.memory(agent_id)
+        if hasattr(self.mark, "memory") and callable(self.mark.memory):
+            return self.mark.memory(agent_id)
+        return self.mark.memory

mark/adapters/langchain/__init__.py

@@ -0,0 +1,15 @@
+"""LangChain adapters for MARK.
+
+Install optional dependencies with ``pip install "mark-sdk[langchain]"``.
+"""
+
+from mark.adapters.langchain.middleware import MarkAgentMiddleware, MarkMemoryMiddleware
+
+__all__ = ["MarkAgentMiddleware", "MarkMemoryMiddleware", "create_mark_tools"]
+
+
+def create_mark_tools(*args, **kwargs):
+    """Create LangChain tools backed by a MARK backend."""
+    from mark.adapters.langchain.tools import create_mark_tools as _create_mark_tools
+
+    return _create_mark_tools(*args, **kwargs)