contextmd 0.1.1__py3-none-any.whl

contextmd/__init__.py

@@ -0,0 +1,9 @@
+"""ContextMD - Markdown-Based Memory Layer for LLM APIs."""
+
+from contextmd.client import ContextMD
+from contextmd.config import ContextMDConfig
+from contextmd.memory.types import MemoryType
+from contextmd.session import Session
+
+__version__ = "0.1.0"
+__all__ = ["ContextMD", "ContextMDConfig", "Session", "MemoryType"]

contextmd/_version.py

@@ -0,0 +1,34 @@
+# file generated by setuptools-scm
+# don't change, don't track in version control
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple
+    from typing import Union
+
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+    COMMIT_ID = Union[str, None]
+else:
+    VERSION_TUPLE = object
+    COMMIT_ID = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+commit_id: COMMIT_ID
+__commit_id__: COMMIT_ID
+
+__version__ = version = '0.1.1'
+__version_tuple__ = version_tuple = (0, 1, 1)
+
+__commit_id__ = commit_id = None

contextmd/adapters/__init__.py

@@ -0,0 +1,6 @@
+"""Provider adapters for ContextMD."""
+
+from contextmd.adapters.base import ProviderAdapter
+from contextmd.adapters.registry import AdapterRegistry, detect_provider
+
+__all__ = ["ProviderAdapter", "AdapterRegistry", "detect_provider"]

contextmd/adapters/anthropic.py

@@ -0,0 +1,106 @@
+"""Anthropic provider adapter."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from contextmd.adapters.base import ProviderAdapter
+from contextmd.memory.types import Message, TokenUsage
+
+MODEL_CONTEXT_WINDOWS = {
+    # Claude 4.6 family (latest - February 2026)
+    "claude-opus-4-6": 200000,
+    "claude-sonnet-4-6": 200000,
+    # Claude 4.5 family
+    "claude-opus-4-5": 200000,
+    "claude-sonnet-4-5": 200000,
+    "claude-haiku-4-5": 200000,
+    # Claude 4.x family
+    "claude-opus-4-1": 200000,
+    "claude-opus-4": 200000,
+    "claude-sonnet-4": 200000,
+    # Claude 3.x family (still supported)
+    "claude-3-7-sonnet": 200000,
+    "claude-3-5-sonnet": 200000,
+    "claude-3-5-haiku": 200000,
+    "claude-3-haiku": 200000,
+}
+
+
+class AnthropicAdapter(ProviderAdapter):
+    """Adapter for Anthropic API."""
+
+    @property
+    def provider_name(self) -> str:
+        return "anthropic"
+
+    def inject_memory(self, request: dict[str, Any], memory_text: str) -> dict[str, Any]:
+        """Inject memory into the system parameter."""
+        if not memory_text:
+            return request
+
+        existing_system = request.get("system", "")
+
+        new_system: str | list[dict[str, str]]
+        if isinstance(existing_system, list):
+            new_system = [{"type": "text", "text": memory_text}] + existing_system
+        elif existing_system:
+            new_system = memory_text + str(existing_system)
+        else:
+            new_system = memory_text
+
+        return {**request, "system": new_system}
+
+    def extract_usage(self, response: Any) -> TokenUsage | None:
+        """Extract token usage from Anthropic response."""
+        usage = getattr(response, "usage", None)
+        if usage is None:
+            return None
+
+        input_tokens = getattr(usage, "input_tokens", 0)
+        output_tokens = getattr(usage, "output_tokens", 0)
+
+        return TokenUsage(
+            input_tokens=input_tokens,
+            output_tokens=output_tokens,
+            total_tokens=input_tokens + output_tokens,
+        )
+
+    def normalize_messages(self, response: Any) -> list[Message]:
+        """Normalize Anthropic response to Message objects."""
+        messages: list[Message] = []
+
+        content_blocks = getattr(response, "content", [])
+        text_parts: list[str] = []
+
+        for block in content_blocks:
+            if getattr(block, "type", None) == "text":
+                text_parts.append(getattr(block, "text", ""))
+
+        if text_parts:
+            messages.append(
+                Message(
+                    role="assistant",
+                    content="\n".join(text_parts),
+                )
+            )
+
+        return messages
+
+    def get_context_window_size(self, model: str) -> int:
+        """Get context window size for an Anthropic model."""
+        for model_prefix, size in MODEL_CONTEXT_WINDOWS.items():
+            if model.startswith(model_prefix):
+                return size
+        return 200000
+
+    def _extract_chunk_content(self, chunk: Any) -> str | None:
+        """Extract content from a streaming chunk."""
+        chunk_type = getattr(chunk, "type", None)
+
+        if chunk_type == "content_block_delta":
+            delta = getattr(chunk, "delta", None)
+            if delta and getattr(delta, "type", None) == "text_delta":
+                return getattr(delta, "text", None)
+
+        return None

contextmd/adapters/base.py

@@ -0,0 +1,118 @@
+"""Abstract base class for provider adapters."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import AsyncIterator, Iterator
+from typing import Any
+
+from contextmd.memory.types import Message, TokenUsage
+
+
+class ProviderAdapter(ABC):
+    """Abstract interface for LLM provider adapters."""
+
+    @property
+    @abstractmethod
+    def provider_name(self) -> str:
+        """Return the provider name (e.g., 'openai', 'anthropic', 'litellm')."""
+        ...
+
+    @abstractmethod
+    def inject_memory(self, request: dict[str, Any], memory_text: str) -> dict[str, Any]:
+        """Inject memory into the request.
+
+        Args:
+            request: The original request parameters.
+            memory_text: The memory content to inject.
+
+        Returns:
+            Modified request with memory injected into system prompt.
+        """
+        ...
+
+    @abstractmethod
+    def extract_usage(self, response: Any) -> TokenUsage | None:
+        """Extract token usage from the response.
+
+        Args:
+            response: The API response object.
+
+        Returns:
+            TokenUsage object or None if not available.
+        """
+        ...
+
+    @abstractmethod
+    def normalize_messages(self, response: Any) -> list[Message]:
+        """Normalize response messages to a common format.
+
+        Args:
+            response: The API response object.
+
+        Returns:
+            List of normalized Message objects.
+        """
+        ...
+
+    @abstractmethod
+    def get_context_window_size(self, model: str) -> int:
+        """Get the context window size for a model.
+
+        Args:
+            model: The model name.
+
+        Returns:
+            Context window size in tokens.
+        """
+        ...
+
+    def handle_streaming(
+        self,
+        stream: Iterator[Any] | AsyncIterator[Any],
+    ) -> tuple[Iterator[Any], list[str]]:
+        """Handle streaming responses by buffering content.
+
+        Args:
+            stream: The streaming response iterator.
+
+        Returns:
+            Tuple of (passthrough iterator, buffered content chunks).
+        """
+        buffered_chunks: list[str] = []
+
+        def passthrough() -> Iterator[Any]:
+            for chunk in stream:  # type: ignore
+                content = self._extract_chunk_content(chunk)
+                if content:
+                    buffered_chunks.append(content)
+                yield chunk
+
+        return passthrough(), buffered_chunks
+
+    async def handle_streaming_async(
+        self,
+        stream: AsyncIterator[Any],
+    ) -> tuple[AsyncIterator[Any], list[str]]:
+        """Handle async streaming responses by buffering content.
+
+        Args:
+            stream: The async streaming response iterator.
+
+        Returns:
+            Tuple of (passthrough async iterator, buffered content chunks).
+        """
+        buffered_chunks: list[str] = []
+
+        async def passthrough() -> AsyncIterator[Any]:
+            async for chunk in stream:
+                content = self._extract_chunk_content(chunk)
+                if content:
+                    buffered_chunks.append(content)
+                yield chunk
+
+        return passthrough(), buffered_chunks
+
+    def _extract_chunk_content(self, chunk: Any) -> str | None:
+        """Extract content from a streaming chunk. Override in subclasses."""
+        return None

contextmd/adapters/litellm.py

@@ -0,0 +1,151 @@
+"""LiteLLM provider adapter."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from contextmd.adapters.base import ProviderAdapter
+from contextmd.memory.types import Message, TokenUsage
+
+
+class LiteLLMAdapter(ProviderAdapter):
+    """Adapter for LiteLLM unified API.
+
+    LiteLLM provides a unified interface for 100+ LLM providers.
+    It uses OpenAI-compatible request/response format.
+    """
+
+    @property
+    def provider_name(self) -> str:
+        return "litellm"
+
+    def inject_memory(self, request: dict[str, Any], memory_text: str) -> dict[str, Any]:
+        """Inject memory into the messages array (OpenAI-compatible format)."""
+        if not memory_text:
+            return request
+
+        messages = list(request.get("messages", []))
+
+        if messages and messages[0].get("role") == "system":
+            messages[0] = {
+                **messages[0],
+                "content": memory_text + messages[0].get("content", ""),
+            }
+        else:
+            messages.insert(0, {"role": "system", "content": memory_text})
+
+        return {**request, "messages": messages}
+
+    def extract_usage(self, response: Any) -> TokenUsage | None:
+        """Extract token usage from LiteLLM response.
+
+        LiteLLM normalizes usage to OpenAI format.
+        """
+        usage = getattr(response, "usage", None)
+        if usage is None:
+            if isinstance(response, dict):
+                usage = response.get("usage")
+            if usage is None:
+                return None
+
+        if isinstance(usage, dict):
+            return TokenUsage(
+                input_tokens=usage.get("prompt_tokens", 0),
+                output_tokens=usage.get("completion_tokens", 0),
+                total_tokens=usage.get("total_tokens", 0),
+            )
+
+        return TokenUsage(
+            input_tokens=getattr(usage, "prompt_tokens", 0),
+            output_tokens=getattr(usage, "completion_tokens", 0),
+            total_tokens=getattr(usage, "total_tokens", 0),
+        )
+
+    def normalize_messages(self, response: Any) -> list[Message]:
+        """Normalize LiteLLM response to Message objects.
+
+        LiteLLM uses OpenAI-compatible response format.
+        """
+        messages: list[Message] = []
+
+        choices = getattr(response, "choices", None)
+        if choices is None and isinstance(response, dict):
+            choices = response.get("choices", [])
+
+        if choices:
+            for choice in choices:
+                if isinstance(choice, dict):
+                    msg = choice.get("message", {})
+                    messages.append(
+                        Message(
+                            role=msg.get("role", "assistant"),
+                            content=msg.get("content", "") or "",
+                            tool_calls=msg.get("tool_calls"),
+                        )
+                    )
+                else:
+                    msg = getattr(choice, "message", None)
+                    if msg:
+                        messages.append(
+                            Message(
+                                role=getattr(msg, "role", "assistant"),
+                                content=getattr(msg, "content", "") or "",
+                                tool_calls=getattr(msg, "tool_calls", None),
+                            )
+                        )
+
+        return messages
+
+    def get_context_window_size(self, model: str) -> int:
+        """Get context window size for a model via LiteLLM.
+
+        LiteLLM has built-in model info, but we provide sensible defaults.
+        """
+        try:
+            import litellm
+            model_info = litellm.get_model_info(model)
+            max_tokens = model_info.get("max_input_tokens", 128000)
+            return int(max_tokens) if max_tokens is not None else 128000
+        except Exception:
+            pass
+
+        model_lower = model.lower()
+
+        if "claude" in model_lower:
+            return 200000
+        elif "gpt-5" in model_lower:
+            return 400000
+        elif "gpt-4.1" in model_lower:
+            return 1047576
+        elif "gpt-4" in model_lower:
+            return 128000
+        elif "gemini" in model_lower:
+            return 1000000
+        elif "mistral" in model_lower:
+            return 32768
+        elif "llama" in model_lower:
+            return 128000
+        elif "o3" in model_lower or "o4" in model_lower:
+            return 200000
+
+        return 128000
+
+    def _extract_chunk_content(self, chunk: Any) -> str | None:
+        """Extract content from a streaming chunk."""
+        choices = getattr(chunk, "choices", None)
+        if choices is None and isinstance(chunk, dict):
+            choices = chunk.get("choices", [])
+
+        if choices:
+            choice = choices[0] if choices else None
+            if choice:
+                if isinstance(choice, dict):
+                    delta = choice.get("delta", {})
+                    content = delta.get("content")
+                    return str(content) if content is not None else None
+                else:
+                    delta = getattr(choice, "delta", None)
+                    if delta:
+                        return getattr(delta, "content", None)
+
+        return None

contextmd/adapters/openai.py

@@ -0,0 +1,110 @@
+"""OpenAI provider adapter."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from contextmd.adapters.base import ProviderAdapter
+from contextmd.memory.types import Message, TokenUsage
+
+MODEL_CONTEXT_WINDOWS = {
+    # GPT-5.x family (latest flagship models)
+    "gpt-5.2": 400000,
+    "gpt-5.2-pro": 400000,
+    "gpt-5.1": 400000,
+    "gpt-5": 400000,
+    "gpt-5-mini": 400000,
+    "gpt-5-nano": 400000,
+    "gpt-5.2-chat": 128000,
+    "gpt-5.1-codex": 400000,
+    "gpt-5.1-codex-mini": 400000,
+    # GPT-4.1 family
+    "gpt-4.1": 1047576,
+    "gpt-4.1-mini": 1047576,
+    "gpt-4.1-nano": 1047576,
+    # GPT-4o family (multimodal)
+    "gpt-4o": 128000,
+    "gpt-4o-mini": 128000,
+    # o-series reasoning models
+    "o1": 200000,
+    "o1-mini": 128000,
+    "o1-preview": 128000,
+    "o3": 200000,
+    "o3-mini": 200000,
+    "o3-pro": 200000,
+    "o4-mini": 200000,
+}
+
+
+class OpenAIAdapter(ProviderAdapter):
+    """Adapter for OpenAI API."""
+
+    @property
+    def provider_name(self) -> str:
+        return "openai"
+
+    def inject_memory(self, request: dict[str, Any], memory_text: str) -> dict[str, Any]:
+        """Inject memory into the system message."""
+        if not memory_text:
+            return request
+
+        messages = list(request.get("messages", []))
+
+        if messages and messages[0].get("role") == "system":
+            messages[0] = {
+                **messages[0],
+                "content": memory_text + messages[0].get("content", ""),
+            }
+        else:
+            messages.insert(0, {"role": "system", "content": memory_text})
+
+        return {**request, "messages": messages}
+
+    def extract_usage(self, response: Any) -> TokenUsage | None:
+        """Extract token usage from OpenAI response."""
+        usage = getattr(response, "usage", None)
+        if usage is None:
+            return None
+
+        return TokenUsage(
+            input_tokens=getattr(usage, "prompt_tokens", 0),
+            output_tokens=getattr(usage, "completion_tokens", 0),
+            total_tokens=getattr(usage, "total_tokens", 0),
+        )
+
+    def normalize_messages(self, response: Any) -> list[Message]:
+        """Normalize OpenAI response to Message objects."""
+        messages: list[Message] = []
+
+        choices = getattr(response, "choices", [])
+        for choice in choices:
+            msg = getattr(choice, "message", None)
+            if msg:
+                messages.append(
+                    Message(
+                        role=getattr(msg, "role", "assistant"),
+                        content=getattr(msg, "content", "") or "",
+                        tool_calls=getattr(msg, "tool_calls", None),
+                    )
+                )
+
+        return messages
+
+    def get_context_window_size(self, model: str) -> int:
+        """Get context window size for an OpenAI model."""
+        if model in MODEL_CONTEXT_WINDOWS:
+            return MODEL_CONTEXT_WINDOWS[model]
+        sorted_prefixes = sorted(MODEL_CONTEXT_WINDOWS.keys(), key=len, reverse=True)
+        for model_prefix in sorted_prefixes:
+            if model.startswith(model_prefix):
+                return MODEL_CONTEXT_WINDOWS[model_prefix]
+        return 128000
+
+    def _extract_chunk_content(self, chunk: Any) -> str | None:
+        """Extract content from a streaming chunk."""
+        choices = getattr(chunk, "choices", [])
+        if choices:
+            delta = getattr(choices[0], "delta", None)
+            if delta:
+                return getattr(delta, "content", None)
+        return None

contextmd/adapters/registry.py

@@ -0,0 +1,89 @@
+"""Provider adapter registry and detection."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from contextmd.adapters.base import ProviderAdapter
+
+
+class AdapterRegistry:
+    """Registry for provider adapters."""
+
+    _adapters: dict[str, type[ProviderAdapter]] = {}
+
+    @classmethod
+    def register(cls, name: str, adapter_class: type[ProviderAdapter]) -> None:
+        """Register an adapter class."""
+        cls._adapters[name] = adapter_class
+
+    @classmethod
+    def get(cls, name: str) -> type[ProviderAdapter] | None:
+        """Get an adapter class by name."""
+        return cls._adapters.get(name)
+
+    @classmethod
+    def create(cls, name: str) -> ProviderAdapter | None:
+        """Create an adapter instance by name."""
+        adapter_class = cls.get(name)
+        if adapter_class:
+            return adapter_class()
+        return None
+
+    @classmethod
+    def list_providers(cls) -> list[str]:
+        """List all registered provider names."""
+        return list(cls._adapters.keys())
+
+
+def _register_builtin_adapters() -> None:
+    """Register built-in adapters."""
+    from contextmd.adapters.anthropic import AnthropicAdapter
+    from contextmd.adapters.litellm import LiteLLMAdapter
+    from contextmd.adapters.openai import OpenAIAdapter
+
+    AdapterRegistry.register("openai", OpenAIAdapter)
+    AdapterRegistry.register("anthropic", AnthropicAdapter)
+    AdapterRegistry.register("litellm", LiteLLMAdapter)
+
+
+def detect_provider(client: Any) -> str | None:
+    """Detect the provider type from a client instance.
+
+    Args:
+        client: The LLM client instance.
+
+    Returns:
+        Provider name ('openai', 'anthropic', 'litellm') or None.
+    """
+    client_type = type(client).__name__
+    client_module = type(client).__module__
+
+    if "openai" in client_module.lower():
+        return "openai"
+
+    if "anthropic" in client_module.lower():
+        return "anthropic"
+
+    if "litellm" in client_module.lower():
+        return "litellm"
+
+    if client_type in ("OpenAI", "AsyncOpenAI"):
+        return "openai"
+
+    if client_type in ("Anthropic", "AsyncAnthropic"):
+        return "anthropic"
+
+    if hasattr(client, "completion") and hasattr(client, "acompletion"):
+        if "litellm" in str(getattr(client, "completion", "")):
+            return "litellm"
+
+    import types
+    if isinstance(client, types.ModuleType):
+        if client.__name__ == "litellm":
+            return "litellm"
+
+    return None
+
+
+_register_builtin_adapters()

contextmd/cli/__init__.py

@@ -0,0 +1,5 @@
+"""CLI for ContextMD."""
+
+from contextmd.cli.main import main
+
+__all__ = ["main"]