Refactor CLI to use Python bridge for LLM operations

Architecture change:
- Go CLI is now a thin wrapper that spawns Python subprocess
- New /bridge/ module handles LLM provider calls and Memex tools
- Removed Go agent/client packages (moved logic to Python)

Bridge components:
- providers.py: Modular LLM provider abstraction (swappable backends)
- tools.py: Memex tools that call Go server endpoints
- query.py: Main entry point for subprocess invocation

This separates concerns: Go for CLI UX, Python for LLM ecosystem.

Author: systemshift

.gitignore

@@ -63,4 +63,5 @@ __pycache__/
 
 # Python venvs
 *_venv/
+venv/
 memex-cli

bridge/providers.py

@@ -0,0 +1,145 @@
+"""
+LLM Provider abstraction.
+
+Swap between OpenAI, Anthropic, or others without changing the rest of the code.
+"""
+
+import os
+import json
+from abc import ABC, abstractmethod
+from typing import Dict, Any, List, Generator, Callable
+from dataclasses import dataclass
+
+
+@dataclass
+class Tool:
+    """Tool definition for function calling"""
+    name: str
+    description: str
+    parameters: Dict[str, Any]
+
+
+@dataclass
+class ToolCall:
+    """A tool call request from the LLM"""
+    id: str
+    name: str
+    arguments: Dict[str, Any]
+
+
+@dataclass
+class Chunk:
+    """Stream chunk from LLM"""
+    type: str  # "text" | "tool_call" | "done" | "error"
+    text: str = ""
+    tool_call: ToolCall = None
+    error: str = ""
+
+
+class Provider(ABC):
+    """Abstract LLM provider"""
+
+    @abstractmethod
+    def stream(
+        self,
+        system: str,
+        messages: List[Dict],
+        tools: List[Tool]
+    ) -> Generator[Chunk, None, None]:
+        """Stream response with tool support"""
+        pass
+
+
+class OpenAIProvider(Provider):
+    """OpenAI provider (GPT-4, etc.)"""
+
+    def __init__(self, model: str = None):
+        from openai import OpenAI
+        self.client = OpenAI()
+        self.model = model or os.getenv("OPENAI_MODEL", "gpt-4o")
+
+    def stream(
+        self,
+        system: str,
+        messages: List[Dict],
+        tools: List[Tool]
+    ) -> Generator[Chunk, None, None]:
+
+        # Build messages
+        api_messages = [{"role": "system", "content": system}] if system else []
+        api_messages.extend(messages)
+
+        # Build tools
+        api_tools = [{
+            "type": "function",
+            "function": {
+                "name": t.name,
+                "description": t.description,
+                "parameters": t.parameters
+            }
+        } for t in tools] if tools else None
+
+        try:
+            stream = self.client.chat.completions.create(
+                model=self.model,
+                messages=api_messages,
+                tools=api_tools,
+                stream=True
+            )
+
+            # Accumulate tool calls
+            tool_calls: Dict[int, Dict] = {}
+
+            for chunk in stream:
+                delta = chunk.choices[0].delta
+
+                # Text
+                if delta.content:
+                    yield Chunk(type="text", text=delta.content)
+
+                # Tool calls (accumulate across chunks)
+                if delta.tool_calls:
+                    for tc in delta.tool_calls:
+                        idx = tc.index
+                        if idx not in tool_calls:
+                            tool_calls[idx] = {"id": "", "name": "", "args": ""}
+                        if tc.id:
+                            tool_calls[idx]["id"] = tc.id
+                        if tc.function:
+                            if tc.function.name:
+                                tool_calls[idx]["name"] = tc.function.name
+                            if tc.function.arguments:
+                                tool_calls[idx]["args"] += tc.function.arguments
+
+                # Finish
+                if chunk.choices[0].finish_reason == "tool_calls":
+                    for idx in sorted(tool_calls.keys()):
+                        tc = tool_calls[idx]
+                        try:
+                            args = json.loads(tc["args"]) if tc["args"] else {}
+                            yield Chunk(
+                                type="tool_call",
+                                tool_call=ToolCall(tc["id"], tc["name"], args)
+                            )
+                        except json.JSONDecodeError:
+                            pass
+                    tool_calls.clear()
+
+                elif chunk.choices[0].finish_reason == "stop":
+                    yield Chunk(type="done")
+
+        except Exception as e:
+            yield Chunk(type="error", error=str(e))
+
+
+def get_provider(name: str = None) -> Provider:
+    """Get provider by name or auto-detect from env"""
+    name = name or os.getenv("LLM_PROVIDER", "openai")
+
+    if name == "openai":
+        return OpenAIProvider()
+    # Add more providers here:
+    # elif name == "anthropic":
+    #     return AnthropicProvider()
+    else:
+        raise ValueError(f"Unknown provider: {name}")

bridge/query.py

@@ -0,0 +1,117 @@
+#!/usr/bin/env python3
+"""
+Bridge query processor.
+
+Usage:
+    python query.py "your question here"
+    echo "your question" | python query.py
+
+Streams response to stdout. Tool calls are shown as [tool_name: args].
+"""
+
+import sys
+import os
+import json
+
+# Add bridge dir to path for imports
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+from dotenv import load_dotenv
+load_dotenv()
+
+from providers import get_provider, Chunk, ToolCall
+from tools import TOOLS, execute
+
+SYSTEM_PROMPT = """You are a knowledge graph assistant for Memex.
+
+Help users find information by querying the graph. You have tools to search, traverse, and retrieve nodes.
+
+When answering:
+1. Use search to find relevant nodes
+2. Use traverse or get_links to explore relationships
+3. Synthesize findings into a clear response
+4. Cite node IDs when relevant
+
+Node types: Person, Company, Document, Task, Project, Message, Event
+
+Be concise. If you can't find something, say so."""
+
+
+def run(query: str, history: list = None):
+    """Run a query and stream output to stdout"""
+    provider = get_provider()
+
+    # Build messages
+    messages = history or []
+    messages.append({"role": "user", "content": query})
+
+    # Agent loop
+    max_turns = 10
+    for _ in range(max_turns):
+        text_buffer = ""
+        tool_calls = []
+
+        for chunk in provider.stream(SYSTEM_PROMPT, messages, TOOLS):
+            if chunk.type == "text":
+                print(chunk.text, end="", flush=True)
+                text_buffer += chunk.text
+
+            elif chunk.type == "tool_call":
+                tool_calls.append(chunk.tool_call)
+                # Show tool execution
+                print(f"\n[{chunk.tool_call.name}]", flush=True)
+
+            elif chunk.type == "error":
+                print(f"\nError: {chunk.error}", file=sys.stderr)
+                return
+
+            elif chunk.type == "done":
+                pass
+
+        # If tool calls, execute and continue
+        if tool_calls:
+            # Add assistant message
+            messages.append({
+                "role": "assistant",
+                "content": text_buffer or None,
+                "tool_calls": [{
+                    "id": tc.id,
+                    "type": "function",
+                    "function": {"name": tc.name, "arguments": json.dumps(tc.arguments)}
+                } for tc in tool_calls]
+            })
+
+            # Execute tools
+            for tc in tool_calls:
+                result = execute(tc.name, tc.arguments)
+                messages.append({
+                    "role": "tool",
+                    "tool_call_id": tc.id,
+                    "content": result
+                })
+
+            continue
+
+        # No tool calls - done
+        print()  # Final newline
+        return
+
+    print("\nMax turns reached", file=sys.stderr)
+
+
+def main():
+    # Get query from args or stdin
+    if len(sys.argv) > 1:
+        query = " ".join(sys.argv[1:])
+    else:
+        query = sys.stdin.read().strip()
+
+    if not query:
+        print("Usage: python query.py \"your question\"", file=sys.stderr)
+        sys.exit(1)
+
+    run(query)
+
+
+if __name__ == "__main__":
+    main()

bridge/requirements.txt

@@ -0,0 +1,4 @@
+# Bridge - LLM middleware for Memex CLI
+openai>=1.0.0
+httpx>=0.24.0
+python-dotenv>=1.0.0