openlcm 0.1.0__py3-none-any.whl

openlcm/__init__.py

@@ -0,0 +1,80 @@
+"""OpenLCM — Framework-agnostic Lossless Context Management SDK.
+
+One install, every provider::
+
+    pip install openlcm
+
+Quick start — pass any LiteLLM model string::
+
+    from openlcm import LCMEngine
+
+    # Anthropic
+    engine = LCMEngine(model="anthropic/claude-haiku-4-5-20251001")
+
+    # Azure OpenAI
+    engine = LCMEngine(model="azure/gpt-4o")
+
+    # AWS Bedrock
+    engine = LCMEngine(model="bedrock/anthropic.claude-3-5-sonnet-20241022-v2:0")
+
+    # Google Gemini
+    engine = LCMEngine(model="gemini/gemini-2.0-flash")
+
+    # Vertex AI
+    engine = LCMEngine(model="vertex_ai/gemini-pro")
+
+    # Ollama (local)
+    engine = LCMEngine(model="ollama/llama3.2", api_base="http://localhost:11434")
+
+    # WatsonX
+    engine = LCMEngine(model="watsonx/ibm/granite-13b-chat-v2")
+
+    # Custom OpenAI-compatible endpoint
+    engine = LCMEngine(model="openai/my-model", api_base="http://my-server/v1")
+
+Bind a session and compress each turn::
+
+    engine.bind_session("session-abc", context_length=200_000)
+    compressed = await engine.compress(messages)   # call before every LLM turn
+
+Already using a framework LLM? Pass it directly — no separate model config needed::
+
+    from langchain_anthropic import ChatAnthropic
+    from openlcm.adapters.langgraph import LCMCheckpointer
+
+    llm = ChatAnthropic(model="claude-3-haiku-20240307")  # your existing LLM
+    checkpointer = LCMCheckpointer(llm=llm)               # reuses it for summarization
+
+    # Works the same way for CrewAI, AutoGen, Google ADK:
+    LCMStorage(llm=my_crewai_llm)
+    LCMContext(llm=my_autogen_client)
+    LCMSessionService(llm=my_gemini_model)
+
+    # Or pass any callable to LCMEngine directly:
+    engine = LCMEngine(summarize_fn=llm)
+    engine = LCMEngine(summarize_fn=lambda prompt, max_tokens: llm.invoke(prompt).content)
+
+Live dashboard::
+
+    openlcm viz   # http://localhost:7842
+
+Advanced — bring your own backend (custom inference server, etc.)::
+
+    from openlcm.backends.base import SummaryBackend
+
+    class MyBackend(SummaryBackend):
+        async def summarize(self, prompt, max_tokens, model="", timeout=None):
+            ...
+
+    engine = LCMEngine(backend=MyBackend())
+
+Full provider list: https://docs.litellm.ai/docs/providers
+"""
+
+from .core.engine import LCMEngine
+from .core.config import LCMConfig
+from .backends.base import SummaryBackend
+from .backends.callable import CallableBackend
+
+__version__ = "0.1.0"
+__all__ = ["LCMEngine", "LCMConfig", "SummaryBackend", "CallableBackend"]

openlcm/adapters/__init__.py

@@ -0,0 +1,256 @@
+"""Framework adapters for OpenLCM.
+
+Two types of adapter live here:
+
+1. **Message converters** — translate message formats between frameworks and
+   LCM's internal dict format.  Use these when you manage the conversation
+   history yourself (raw SDK, custom agent loop, etc.).
+
+2. **Framework lifecycle adapters** — plug LCM into a framework's built-in
+   memory / checkpointing / context system.  Use these when you want LCM to
+   work *transparently* inside an existing framework graph or crew.
+
+──────────────────────────────────────────────────────────────────────────────
+Message converters  (``to_lcm`` / ``from_lcm``)
+──────────────────────────────────────────────────────────────────────────────
+
+OpenAI (and every OpenAI-compatible API)::
+
+    from openlcm.adapters.openai import OpenAIMessages
+
+    lcm_msgs = OpenAIMessages.to_lcm(openai_messages)
+    if engine.should_compress_preflight(lcm_msgs):
+        lcm_msgs     = await engine.compress(lcm_msgs)
+        openai_msgs  = OpenAIMessages.from_lcm(lcm_msgs)
+
+    # Compatible with: OpenAI, Groq, Together, Mistral, Perplexity, Fireworks,
+    #                  Azure OpenAI, Ollama, vLLM, LM Studio, OpenRouter, Anyscale
+
+Anthropic::
+
+    from openlcm.adapters.anthropic import AnthropicMessages
+
+    lcm_msgs           = AnthropicMessages.to_lcm(messages, system=system_prompt)
+    system_out, an_msgs = AnthropicMessages.from_lcm(lcm_msgs)
+    # Note: Anthropic returns (system_str, messages) because system is a separate param
+
+LangChain (any backend)::
+
+    from openlcm.adapters.langchain import LangChainMessages
+
+    lcm_msgs  = LangChainMessages.to_lcm(lc_messages)   # list[BaseMessage]
+    lc_msgs   = LangChainMessages.from_lcm(lcm_msgs)    # list[BaseMessage]
+
+    # Compatible with: langchain_openai, langchain_anthropic, langchain_google_genai,
+    #                  langchain_cohere, langchain_mistralai, langchain_groq,
+    #                  langchain_ollama, langchain_aws (Bedrock), langchain_together, …
+
+LlamaIndex::
+
+    from openlcm.adapters.llamaindex import LlamaIndexMessages
+
+    lcm_msgs = LlamaIndexMessages.to_lcm(chat_messages)  # list[ChatMessage]
+    li_msgs  = LlamaIndexMessages.from_lcm(lcm_msgs)
+
+    # Compatible with: llama_index.llms.openai, llama_index.llms.anthropic,
+    #                  llama_index.llms.gemini, llama_index.llms.ollama, …
+
+Haystack v2::
+
+    from openlcm.adapters.haystack import HaystackMessages
+
+    lcm_msgs = HaystackMessages.to_lcm(hs_messages)  # list[ChatMessage]
+    hs_msgs  = HaystackMessages.from_lcm(lcm_msgs)
+
+    # Compatible with: OpenAIChatGenerator, AnthropicChatGenerator,
+    #                  HuggingFaceAPIChatGenerator, AzureOpenAIChatGenerator, …
+
+Auto-detect the right converter from your message list::
+
+    from openlcm.adapters import auto_detect
+
+    converter = auto_detect(messages)
+    lcm_msgs  = converter.to_lcm(messages)
+
+──────────────────────────────────────────────────────────────────────────────
+Framework lifecycle adapters
+──────────────────────────────────────────────────────────────────────────────
+
+LangGraph — transparent checkpointing::
+
+    from openlcm.adapters.langgraph import LCMCheckpointer   # pip install openlcm[langgraph]
+
+    graph = StateGraph(MyState).compile(checkpointer=LCMCheckpointer(llm=my_llm))
+
+CrewAI — long-term memory storage::
+
+    from openlcm.adapters.crewai import LCMStorage           # pip install openlcm[crewai]
+
+    crew = Crew(..., long_term_memory=LongTermMemory(storage=LCMStorage(llm=my_llm)))
+
+AutoGen — model context::
+
+    from openlcm.adapters.autogen import LCMContext           # pip install openlcm[autogen]
+
+    agent = AssistantAgent("bot", model_client=client, model_context=LCMContext(llm=client))
+
+Google ADK — session service::
+
+    from openlcm.adapters.google_adk import LCMSessionService  # pip install openlcm[google-adk]
+
+    runner = Runner(agent=my_agent, session_service=LCMSessionService(llm=model))
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+# Top-level imports so `from openlcm.adapters import X` works directly.
+# Each import is wrapped so the package loads even if a framework isn't installed.
+try:
+    from .openai import OpenAIMessages
+except ImportError:
+    OpenAIMessages = None  # type: ignore[assignment,misc]
+
+try:
+    from .anthropic import AnthropicMessages
+except ImportError:
+    AnthropicMessages = None  # type: ignore[assignment,misc]
+
+try:
+    from .langchain import LangChainMessages
+except ImportError:
+    LangChainMessages = None  # type: ignore[assignment,misc]
+
+try:
+    from .llamaindex import LlamaIndexMessages
+except ImportError:
+    LlamaIndexMessages = None  # type: ignore[assignment,misc]
+
+try:
+    from .haystack import HaystackMessages
+except ImportError:
+    HaystackMessages = None  # type: ignore[assignment,misc]
+
+try:
+    from .gemini import GeminiMessages
+except ImportError:
+    GeminiMessages = None  # type: ignore[assignment,misc]
+
+try:
+    from .autogen import AutoGenMessages, LCMContext
+except ImportError:
+    AutoGenMessages = None  # type: ignore[assignment,misc]
+    LCMContext = None  # type: ignore[assignment,misc]
+
+try:
+    from .langgraph import LCMCheckpointer
+except ImportError:
+    LCMCheckpointer = None  # type: ignore[assignment,misc]
+
+try:
+    from .crewai import LCMStorage
+except ImportError:
+    LCMStorage = None  # type: ignore[assignment,misc]
+
+try:
+    from .google_adk import LCMSessionService, lcm_compress_callback
+except ImportError:
+    LCMSessionService = None  # type: ignore[assignment,misc]
+    lcm_compress_callback = None  # type: ignore[assignment,misc]
+
+
+def auto_detect(messages: list) -> Any:
+    """Return the right message converter for the given message list.
+
+    Inspects the first non-empty element and returns the appropriate converter
+    class (with static ``to_lcm`` / ``from_lcm`` methods).
+
+    Supported detection:
+    - LangChain ``BaseMessage`` subclasses → ``LangChainMessages``
+    - Anthropic content-block dicts (``type: tool_use``) → ``AnthropicMessages``
+    - Haystack ``ChatMessage`` objects → ``HaystackMessages``
+    - LlamaIndex ``ChatMessage`` objects → ``LlamaIndexMessages``
+    - OpenAI dicts (``tool_calls`` key / plain role+content) → ``OpenAIMessages``
+
+    Falls back to ``OpenAIMessages`` if the format cannot be determined.
+
+    Args:
+        messages: The conversation list whose format you want to detect.
+
+    Returns:
+        A converter class with static ``to_lcm()`` and ``from_lcm()`` methods.
+
+    Example::
+
+        from openlcm.adapters import auto_detect
+
+        conv = openai_client.chat.completions.create(...).choices[0].message
+        converter = auto_detect(my_messages)
+        lcm = converter.to_lcm(my_messages)
+    """
+    if not messages:
+        from .openai import OpenAIMessages
+        return OpenAIMessages
+
+    first = next((m for m in messages if m is not None), None)
+    if first is None:
+        from .openai import OpenAIMessages
+        return OpenAIMessages
+
+    # ── LangChain BaseMessage ─────────────────────────────────────────────────
+    try:
+        from langchain_core.messages import BaseMessage
+        if isinstance(first, BaseMessage):
+            from .langchain import LangChainMessages
+            return LangChainMessages
+    except ImportError:
+        pass
+
+    # ── Haystack ChatMessage ──────────────────────────────────────────────────
+    try:
+        from haystack.dataclasses import ChatMessage as HaystackCM
+        if isinstance(first, HaystackCM):
+            from .haystack import HaystackMessages
+            return HaystackMessages
+    except ImportError:
+        pass
+
+    # ── LlamaIndex ChatMessage ────────────────────────────────────────────────
+    try:
+        from llama_index.core.llms import ChatMessage as LlamaCM
+        if isinstance(first, LlamaCM):
+            from .llamaindex import LlamaIndexMessages
+            return LlamaIndexMessages
+    except ImportError:
+        pass
+
+    # ── Anthropic content-block style ─────────────────────────────────────────
+    if isinstance(first, dict):
+        content = first.get("content", "")
+        if isinstance(content, list) and content:
+            block = content[0]
+            if isinstance(block, dict) and block.get("type") in ("text", "tool_use", "tool_result", "image"):
+                from .anthropic import AnthropicMessages
+                return AnthropicMessages
+
+    # ── Default: OpenAI dict format ───────────────────────────────────────────
+    from .openai import OpenAIMessages
+    return OpenAIMessages
+
+
+__all__ = [
+    # Auto-detection
+    "auto_detect",
+    # Message converters
+    "OpenAIMessages",
+    "AnthropicMessages",
+    "LangChainMessages",
+    "LlamaIndexMessages",
+    "HaystackMessages",
+    # Framework lifecycle adapters
+    "LCMCheckpointer",
+    "LCMStorage",
+    "LCMContext",
+    "LCMSessionService",
+]

openlcm/adapters/anthropic.py

@@ -0,0 +1,283 @@
+"""Anthropic message converter for LCM.
+
+Handles Anthropic Claude's message format, including multi-part content blocks,
+tool_use / tool_result pairs, and the separate system parameter.
+
+Install: pip install anthropic
+
+Quick start::
+
+    import anthropic
+    from openlcm import LCMEngine
+    from openlcm.adapters.anthropic import AnthropicMessages
+
+    client = anthropic.AsyncAnthropic()
+    engine = LCMEngine(model="anthropic/claude-haiku-4-5-20251001")
+    engine.bind_session("my-session", context_length=200_000)
+
+    system = "You are a helpful assistant."
+    conv   = []   # only user / assistant messages (no system in Anthropic conv list)
+
+    async def chat(user_msg: str) -> str:
+        conv.append({"role": "user", "content": user_msg})
+
+        # Anthropic keeps system separate — AnthropicMessages handles that
+        lcm_msgs = AnthropicMessages.to_lcm(conv, system=system)
+
+        if engine.should_compress_preflight(lcm_msgs):
+            lcm_msgs = await engine.compress(lcm_msgs)
+            system_out, conv[:] = AnthropicMessages.from_lcm(lcm_msgs)
+            # system_out is the same system string passed in (preserved through LCM)
+
+        resp = await client.messages.create(
+            model="claude-haiku-4-5-20251001",
+            max_tokens=4096,
+            system=system,
+            messages=conv,
+            tools=MY_TOOLS,
+        )
+
+        # Append assistant message from response
+        conv.append({"role": "assistant", "content": resp.content})
+        return next((b.text for b in resp.content if hasattr(b, "text")), "")
+
+Tool-calling::
+
+    # After the model returns tool_use blocks, execute them and append results:
+    for block in resp.content:
+        if block.type == "tool_use":
+            result = run_tool(block.name, block.input)
+            conv.append({
+                "role": "user",
+                "content": [{
+                    "type":        "tool_result",
+                    "tool_use_id": block.id,
+                    "content":     [{"type": "text", "text": json.dumps(result)}],
+                }],
+            })
+    # Then call chat() again.
+
+Notes
+-----
+- Anthropic does NOT use a ``system`` role in the messages list.  Pass it via
+  ``AnthropicMessages.to_lcm(conv, system="...")`` and recover it with the
+  second element of ``AnthropicMessages.from_lcm()``'s return value.
+- ``from_lcm()`` returns ``(system_str, messages_list)`` — a 2-tuple — because
+  the Anthropic API requires system as a separate top-level parameter.
+- Tool results in Anthropic go back as user-role messages with ``tool_result``
+  content blocks.  The converter handles this automatically.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+
+def _text_from_block(block: Any) -> str:
+    """Extract plain text from an Anthropic content block (dict or SDK object)."""
+    if isinstance(block, dict):
+        return block.get("text", "")
+    return getattr(block, "text", "") or ""
+
+
+def _block_type(block: Any) -> str:
+    if isinstance(block, dict):
+        return block.get("type", "")
+    return getattr(block, "type", "") or ""
+
+
+class AnthropicMessages:
+    """Convert between Anthropic SDK message format and LCM internal format.
+
+    All methods are static — no instantiation needed::
+
+        lcm                  = AnthropicMessages.to_lcm(messages, system="You are...")
+        system_str, messages = AnthropicMessages.from_lcm(lcm_messages)
+
+    LCM internal format
+    -------------------
+    See ``openlcm.adapters.openai.OpenAIMessages`` for the canonical definition.
+    Anthropic-specific mappings:
+
+    - ``tool_use`` content block  → assistant message with JSON ``tool_calls``
+    - ``tool_result`` user block  → ``{"role":"tool", ...}`` message
+    - Multi-part text blocks      → joined with newline into a single string
+    - System message extracted to the ``system=`` kwarg of ``to_lcm()``
+    """
+
+    @staticmethod
+    def to_lcm(messages: list, system: str = "") -> list[dict]:
+        """Convert Anthropic messages to LCM internal format.
+
+        Args:
+            messages: The ``messages`` list passed to ``client.messages.create()``.
+                      Each entry is either a dict or an Anthropic SDK Message object.
+            system:   The ``system`` parameter from ``client.messages.create()``.
+                      If provided, it is prepended as a ``{"role":"system"}`` entry.
+
+        Returns:
+            LCM internal message list.
+        """
+        result: list[dict] = []
+
+        if system:
+            result.append({"role": "system", "content": str(system)})
+
+        for m in messages:
+            role = (m.get("role") if isinstance(m, dict) else getattr(m, "role", "user")) or "user"
+            content_raw = m.get("content") if isinstance(m, dict) else getattr(m, "content", "")
+
+            # ── Simple string content ────────────────────────────────────────
+            if isinstance(content_raw, str):
+                result.append({"role": str(role), "content": content_raw})
+                continue
+
+            # ── SDK Message / ContentBlock objects ───────────────────────────
+            if not isinstance(content_raw, list):
+                # e.g. Anthropic SDK response object — try to get .content
+                content_raw = getattr(content_raw, "content", []) or []
+
+            # ── List of content blocks ───────────────────────────────────────
+            if role == "assistant":
+                text_parts: list[str] = []
+                tool_calls: list[dict] = []
+
+                for block in content_raw:
+                    btype = _block_type(block)
+                    if btype == "text":
+                        text_parts.append(_text_from_block(block))
+                    elif btype == "tool_use":
+                        bid   = (block.get("id")    if isinstance(block, dict) else getattr(block, "id",    "")) or ""
+                        bname = (block.get("name")  if isinstance(block, dict) else getattr(block, "name",  "")) or ""
+                        binp  = (block.get("input") if isinstance(block, dict) else getattr(block, "input", {})) or {}
+                        tool_calls.append({"id": bid, "name": bname, "args": dict(binp), "type": "function"})
+
+                if tool_calls:
+                    content_str = json.dumps(
+                        {"text": "\n".join(text_parts), "tool_calls": tool_calls},
+                        ensure_ascii=False,
+                    )
+                else:
+                    content_str = "\n".join(text_parts)
+                result.append({"role": "assistant", "content": content_str})
+
+            elif role == "user":
+                text_parts = []
+                tool_results: list[dict] = []
+
+                for block in content_raw:
+                    btype = _block_type(block)
+                    if btype == "text":
+                        text_parts.append(_text_from_block(block))
+                    elif btype == "tool_result":
+                        tr_id   = (block.get("tool_use_id") if isinstance(block, dict) else getattr(block, "tool_use_id", "")) or ""
+                        tr_cont = (block.get("content")     if isinstance(block, dict) else getattr(block, "content",     "")) or ""
+                        # content may itself be a list of text blocks
+                        if isinstance(tr_cont, list):
+                            tr_text = "\n".join(
+                                _text_from_block(b) for b in tr_cont if _block_type(b) == "text"
+                            )
+                        elif isinstance(tr_cont, str):
+                            tr_text = tr_cont
+                        else:
+                            tr_text = str(tr_cont)
+                        tool_results.append({
+                            "role":         "tool",
+                            "content":      tr_text,
+                            "tool_call_id": tr_id,
+                            "name":         "",
+                        })
+
+                # Tool results come first; any remaining text becomes a user message
+                result.extend(tool_results)
+                if text_parts:
+                    result.append({"role": "user", "content": "\n".join(text_parts)})
+
+            else:
+                # system role inside messages list (uncommon but handle it)
+                text = "\n".join(
+                    _text_from_block(b) for b in content_raw if _block_type(b) == "text"
+                ) or str(content_raw)
+                result.append({"role": str(role), "content": text})
+
+        return result
+
+    @staticmethod
+    def from_lcm(messages: list[dict]) -> tuple[str, list[dict]]:
+        """Convert LCM internal format to Anthropic-ready messages.
+
+        Args:
+            messages: LCM internal message list (from ``engine.compress()``).
+
+        Returns:
+            ``(system_str, anthropic_messages)`` where:
+            - ``system_str``        is the value for ``client.messages.create(system=...)``.
+            - ``anthropic_messages`` is the value for ``client.messages.create(messages=...)``.
+
+        Usage::
+
+            system, msgs = AnthropicMessages.from_lcm(lcm_messages)
+            resp = await client.messages.create(system=system, messages=msgs, ...)
+        """
+        system = ""
+        result: list[dict] = []
+        pending_tool_results: list[dict] = []
+
+        for m in messages:
+            role    = (m.get("role") or "user").lower()
+            content = m.get("content", "")
+
+            # ── system ───────────────────────────────────────────────────────
+            if role == "system":
+                system = content
+                continue
+
+            # Flush accumulated tool_result blocks when a non-tool message arrives
+            if pending_tool_results and role != "tool":
+                result.append({"role": "user", "content": pending_tool_results})
+                pending_tool_results = []
+
+            # ── assistant ────────────────────────────────────────────────────
+            if role == "assistant":
+                try:
+                    parsed = json.loads(content)
+                    if isinstance(parsed, dict) and "tool_calls" in parsed:
+                        blocks: list[dict] = []
+                        text = parsed.get("text", "")
+                        if text:
+                            blocks.append({"type": "text", "text": text})
+                        for tc in parsed["tool_calls"]:
+                            blocks.append({
+                                "type":  "tool_use",
+                                "id":    tc.get("id", ""),
+                                "name":  tc.get("name", ""),
+                                "input": tc.get("args", {}),
+                            })
+                        result.append({"role": "assistant", "content": blocks})
+                        continue
+                except (ValueError, TypeError):
+                    pass
+                result.append({"role": "assistant", "content": content})
+
+            # ── tool result ──────────────────────────────────────────────────
+            elif role == "tool":
+                # Anthropic wraps tool_result blocks inside a user-role message
+                pending_tool_results.append({
+                    "type":        "tool_result",
+                    "tool_use_id": m.get("tool_call_id", ""),
+                    "content":     [{"type": "text", "text": content}],
+                })
+
+            # ── user ─────────────────────────────────────────────────────────
+            elif role == "user":
+                result.append({"role": "user", "content": content})
+
+            else:
+                result.append({"role": role, "content": content})
+
+        # Flush any remaining tool_results
+        if pending_tool_results:
+            result.append({"role": "user", "content": pending_tool_results})
+
+        return system, result