agentram 0.1.0 → 0.1.2

package/agentram/mcp_server.py

@@ -11,9 +11,10 @@ from typing import Any
 from .adapter import HeuristicMemoryAdapter
 from .config import default_ram_root
 from .merger import MemoryMerger
+from .orchestration import AgentModelEndpoint, CodingOrchestrationRequest, MultiModelCodingOrchestrator
 from .retriever import MemoryRetriever
 from .schema import Event, EventType
-from .storage import JsonGoalStore, JsonMemoryStore, JsonlEventLog, ensure_ram_storage
+from .storage import JsonAgentProfileStore, JsonGoalStore, JsonMemoryStore, JsonlEventLog, ensure_ram_storage
 
 JSONRPC_VERSION = "2.0"
 SERVER_NAME = "agentram"
@@ -43,6 +44,10 @@ class McpContext:
     def goal_store(self) -> JsonGoalStore:
         return JsonGoalStore(self.ram_root / "goal_state.json")
 
+    @property
+    def profile_store(self) -> JsonAgentProfileStore:
+        return JsonAgentProfileStore(self.ram_root / "agent_profile.json")
+
     @property
     def merger(self) -> MemoryMerger:
         return MemoryMerger(self.memory_store)
@@ -220,6 +225,60 @@ def tools_list() -> dict[str, Any]:
                     },
                 },
             },
+
+            {
+                "name": "agentram_bind_coding_model",
+                "description": "Bind a coding-agent model endpoint that Claude or other agents can orchestrate later.",
+                "inputSchema": {
+                    "type": "object",
+                    "properties": {
+                        "id": {"type": "string"},
+                        "provider": {"type": "string", "default": "openai-compatible"},
+                        "model": {"type": "string"},
+                        "role": {"type": "string", "default": "coder"},
+                        "base_url": {"type": "string"},
+                        "api_key_env": {"type": "string"},
+                        "modalities": {"type": "array", "items": {"type": "string"}},
+                        "enabled": {"type": "boolean", "default": True},
+                    },
+                    "required": ["provider", "model"],
+                },
+            },
+            {
+                "name": "agentram_read_coding_models",
+                "description": "Read coding-agent model endpoints bound to this project RAM.",
+                "inputSchema": {"type": "object", "properties": {}},
+            },
+            {
+                "name": "agentram_build_coding_orchestration",
+                "description": "Build prompts for all enabled coding model endpoints without calling models.",
+                "inputSchema": {
+                    "type": "object",
+                    "properties": {
+                        "task": {"type": "string"},
+                        "query": {"type": "string"},
+                        "files": {"type": "array", "items": {"type": "string"}},
+                        "modalities": {"type": "array", "items": {"type": "string"}},
+                    },
+                    "required": ["task"],
+                },
+            },
+            {
+                "name": "agentram_run_coding_orchestration",
+                "description": "Run enabled coding model endpoints concurrently when execute=true, otherwise return dry-run plan.",
+                "inputSchema": {
+                    "type": "object",
+                    "properties": {
+                        "task": {"type": "string"},
+                        "query": {"type": "string"},
+                        "files": {"type": "array", "items": {"type": "string"}},
+                        "modalities": {"type": "array", "items": {"type": "string"}},
+                        "execute": {"type": "boolean", "default": False},
+                        "max_workers": {"type": "integer", "default": 4},
+                    },
+                    "required": ["task"],
+                },
+            },
             {
                 "name": "agentram_check_goal_drift",
                 "description": "Check whether a proposed task aligns with the current Goal Stack. Returns no suggestions when aligned.",
@@ -284,6 +343,32 @@ def call_tool(context: McpContext, name: str, arguments: dict[str, Any]) -> dict
         state = context.goal_store.update(arguments)
         return tool_result({"ok": True, "goal_state": state.to_dict(), "context": state.context_block()})
 
+
+    if name == "agentram_bind_coding_model":
+        endpoint = AgentModelEndpoint.from_dict(arguments)
+        data = context.profile_store.upsert(endpoint)
+        return tool_result({"ok": True, "endpoint": endpoint.to_dict(), "profile": data})
+
+    if name == "agentram_read_coding_models":
+        endpoints = context.profile_store.list_endpoints()
+        return tool_result({"endpoints": [endpoint.to_dict() for endpoint in endpoints]})
+
+    if name == "agentram_build_coding_orchestration":
+        request = orchestration_request_from_args(context, arguments)
+        endpoints = context.profile_store.list_endpoints()
+        plan = MultiModelCodingOrchestrator(endpoints).build_plan(request)
+        return tool_result({"ok": True, "execute": False, **plan})
+
+    if name == "agentram_run_coding_orchestration":
+        request = orchestration_request_from_args(context, arguments)
+        endpoints = context.profile_store.list_endpoints()
+        orchestrator = MultiModelCodingOrchestrator(endpoints)
+        if not bool(arguments.get("execute", False)):
+            plan = orchestrator.build_plan(request)
+            return tool_result({"ok": True, "execute": False, **plan})
+        result = orchestrator.run(request, max_workers=int(arguments.get("max_workers", 4)))
+        return tool_result({"ok": True, "execute": True, **result})
+
     if name == "agentram_check_goal_drift":
         task = str(arguments.get("task", ""))
         if not task.strip():
@@ -293,6 +378,27 @@ def call_tool(context: McpContext, name: str, arguments: dict[str, Any]) -> dict
     raise ValueError(f"unknown tool: {name}")
 
 
+
+def orchestration_request_from_args(context: McpContext, arguments: dict[str, Any]) -> CodingOrchestrationRequest:
+    task = str(arguments.get("task", ""))
+    if not task.strip():
+        raise ValueError("task is required")
+    query = str(arguments.get("query") or task)
+    files = arguments.get("files", [])
+    modalities = arguments.get("modalities", ["text"])
+    if not isinstance(files, list):
+        raise ValueError("files must be an array")
+    if not isinstance(modalities, list):
+        raise ValueError("modalities must be an array")
+    retriever = MemoryRetriever(context.memory_store, context.goal_store)
+    context_block = retriever.context_block(query=query, task_id="codex", limit=8)
+    return CodingOrchestrationRequest(
+        task=task,
+        context=context_block,
+        files=[str(item) for item in files],
+        modalities=[str(item) for item in modalities],
+    )
+
 def handle_request(context: McpContext, request: dict[str, Any]) -> dict[str, Any] | None:
     request_id = request.get("id")
     method = request.get("method")

package/agentram/orchestration.py

@@ -0,0 +1,145 @@
+from __future__ import annotations
+
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from dataclasses import dataclass, field
+import json
+import os
+import urllib.request
+from typing import Any, Callable
+from uuid import uuid4
+
+
+@dataclass(frozen=True)
+class AgentModelEndpoint:
+    provider: str
+    model: str
+    role: str = "coder"
+    base_url: str = ""
+    api_key_env: str = ""
+    modalities: list[str] = field(default_factory=lambda: ["text"])
+    enabled: bool = True
+    id: str = field(default_factory=lambda: f"model_{uuid4().hex[:10]}")
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "id": self.id,
+            "provider": self.provider,
+            "model": self.model,
+            "role": self.role,
+            "base_url": self.base_url,
+            "api_key_env": self.api_key_env,
+            "modalities": self.modalities,
+            "enabled": self.enabled,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "AgentModelEndpoint":
+        return cls(
+            id=str(data.get("id") or f"model_{uuid4().hex[:10]}"),
+            provider=str(data.get("provider", "openai-compatible")),
+            model=str(data.get("model", "")),
+            role=str(data.get("role", "coder")),
+            base_url=str(data.get("base_url", "")),
+            api_key_env=str(data.get("api_key_env", "")),
+            modalities=[str(item) for item in data.get("modalities", ["text"])],
+            enabled=bool(data.get("enabled", True)),
+        )
+
+
+@dataclass(frozen=True)
+class CodingOrchestrationRequest:
+    task: str
+    context: str = ""
+    files: list[str] = field(default_factory=list)
+    modalities: list[str] = field(default_factory=lambda: ["text"])
+
+    def to_prompt(self, endpoint: AgentModelEndpoint) -> str:
+        return "\n".join(
+            [
+                f"You are AgentRAM {endpoint.role} agent.",
+                f"Model: {endpoint.model}",
+                f"Provider: {endpoint.provider}",
+                f"Modalities: {', '.join(endpoint.modalities)}",
+                "Task:",
+                self.task,
+                "Files:",
+                "\n".join(f"- {item}" for item in self.files) or "- none provided",
+                "AgentRAM Context:",
+                self.context or "No context provided.",
+                "Output contract:",
+                "- Return concise coding findings or patch plan.",
+                "- Mention files to inspect or change.",
+                "- Do not invent repo facts.",
+            ]
+        )
+
+
+class MultiModelCodingOrchestrator:
+    def __init__(self, endpoints: list[AgentModelEndpoint], client: Callable[[AgentModelEndpoint, str], str] | None = None) -> None:
+        self.endpoints = [endpoint for endpoint in endpoints if endpoint.enabled]
+        self.client = client or self._call_endpoint
+
+    def build_plan(self, request: CodingOrchestrationRequest) -> dict[str, Any]:
+        agents = []
+        for endpoint in self.endpoints:
+            agents.append({"endpoint": endpoint.to_dict(), "prompt": request.to_prompt(endpoint)})
+        return {"task": request.task, "agent_count": len(agents), "agents": agents}
+
+    def run(self, request: CodingOrchestrationRequest, max_workers: int = 4) -> dict[str, Any]:
+        results: list[dict[str, Any]] = []
+        if not self.endpoints:
+            return {"task": request.task, "agent_count": 0, "results": []}
+        with ThreadPoolExecutor(max_workers=max(1, min(max_workers, len(self.endpoints)))) as executor:
+            future_map = {executor.submit(self.client, endpoint, request.to_prompt(endpoint)): endpoint for endpoint in self.endpoints}
+            for future in as_completed(future_map):
+                endpoint = future_map[future]
+                try:
+                    output = future.result()
+                    results.append({"endpoint": endpoint.to_dict(), "ok": True, "output": output})
+                except Exception as error:  # noqa: BLE001 - agent boundary
+                    results.append({"endpoint": endpoint.to_dict(), "ok": False, "error": str(error)})
+        return {"task": request.task, "agent_count": len(self.endpoints), "results": results}
+
+    def _call_endpoint(self, endpoint: AgentModelEndpoint, prompt: str) -> str:
+        provider = endpoint.provider.lower()
+        if provider in {"openai", "openai-compatible", "groq", "vllm", "lmstudio", "ollama-v1"}:
+            return self._call_openai_compatible(endpoint, prompt)
+        if provider in {"anthropic", "claude"}:
+            return self._call_anthropic(endpoint, prompt)
+        raise ValueError(f"Unsupported provider for execution: {endpoint.provider}")
+
+    def _call_openai_compatible(self, endpoint: AgentModelEndpoint, prompt: str) -> str:
+        api_key = os.getenv(endpoint.api_key_env) if endpoint.api_key_env else ""
+        if not endpoint.base_url:
+            raise ValueError("base_url is required")
+        if endpoint.api_key_env and not api_key:
+            raise ValueError(f"missing API key env: {endpoint.api_key_env}")
+        payload = {"model": endpoint.model, "messages": [{"role": "user", "content": prompt}], "temperature": 0}
+        request = urllib.request.Request(
+            endpoint.base_url.rstrip("/") + "/chat/completions",
+            data=json.dumps(payload).encode("utf-8"),
+            headers={"Content-Type": "application/json", "Authorization": f"Bearer {api_key}"} if api_key else {"Content-Type": "application/json"},
+            method="POST",
+        )
+        with urllib.request.urlopen(request, timeout=120) as response:
+            data = json.loads(response.read().decode("utf-8"))
+        return str(data.get("choices", [{}])[0].get("message", {}).get("content", ""))
+
+    def _call_anthropic(self, endpoint: AgentModelEndpoint, prompt: str) -> str:
+        api_key = os.getenv(endpoint.api_key_env) if endpoint.api_key_env else ""
+        if endpoint.api_key_env and not api_key:
+            raise ValueError(f"missing API key env: {endpoint.api_key_env}")
+        base_url = endpoint.base_url.rstrip("/") if endpoint.base_url else "https://api.anthropic.com/v1"
+        payload = {"model": endpoint.model, "max_tokens": 1024, "messages": [{"role": "user", "content": prompt}]}
+        request = urllib.request.Request(
+            base_url + "/messages",
+            data=json.dumps(payload).encode("utf-8"),
+            headers={"Content-Type": "application/json", "x-api-key": api_key, "anthropic-version": "2023-06-01"},
+            method="POST",
+        )
+        with urllib.request.urlopen(request, timeout=120) as response:
+            data = json.loads(response.read().decode("utf-8"))
+        content = data.get("content", [])
+        if content and isinstance(content, list):
+            return "\n".join(str(item.get("text", "")) for item in content if isinstance(item, dict))
+        return str(data)

package/agentram/storage.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 import json
 from pathlib import Path
 
+from .orchestration import AgentModelEndpoint
 from .schema import Event, GoalState, MemoryItem, utc_now
 
 
@@ -74,6 +75,40 @@ class JsonGoalStore:
         return self.save(GoalState.from_dict(current))
 
 
+class JsonAgentProfileStore:
+    def __init__(self, path: str | Path) -> None:
+        self.path = Path(path)
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+
+    def load(self) -> dict[str, object]:
+        if not self.path.exists():
+            return {"updated_at": utc_now(), "endpoints": []}
+        return json.loads(self.path.read_text(encoding="utf-8"))
+
+    def save(self, endpoints: list[AgentModelEndpoint]) -> dict[str, object]:
+        payload = {"updated_at": utc_now(), "endpoints": [endpoint.to_dict() for endpoint in endpoints]}
+        self.path.write_text(json.dumps(payload, indent=2, ensure_ascii=False), encoding="utf-8")
+        return payload
+
+    def list_endpoints(self) -> list[AgentModelEndpoint]:
+        data = self.load()
+        return [AgentModelEndpoint.from_dict(item) for item in data.get("endpoints", []) if isinstance(item, dict)]
+
+    def upsert(self, endpoint: AgentModelEndpoint) -> dict[str, object]:
+        endpoints = self.list_endpoints()
+        replaced = False
+        updated: list[AgentModelEndpoint] = []
+        for current in endpoints:
+            if current.id == endpoint.id:
+                updated.append(endpoint)
+                replaced = True
+            else:
+                updated.append(current)
+        if not replaced:
+            updated.append(endpoint)
+        return self.save(updated)
+
+
 def ensure_ram_storage(root: str | Path) -> dict[str, object]:
     ram_root = Path(root)
     ram_root.mkdir(parents=True, exist_ok=True)
@@ -81,6 +116,7 @@ def ensure_ram_storage(root: str | Path) -> dict[str, object]:
     events_path = ram_root / "events.jsonl"
     memory_path = ram_root / "memory.json"
     goal_path = ram_root / "goal_state.json"
+    profile_path = ram_root / "agent_profile.json"
 
     created: list[str] = []
     if not events_path.exists():
@@ -92,6 +128,9 @@ def ensure_ram_storage(root: str | Path) -> dict[str, object]:
     if not goal_path.exists():
         JsonGoalStore(goal_path).save(GoalState())
         created.append("goal_state.json")
+    if not profile_path.exists():
+        JsonAgentProfileStore(profile_path).save([])
+        created.append("agent_profile.json")
 
     return {
         "ram_root": str(ram_root),
@@ -100,5 +139,6 @@ def ensure_ram_storage(root: str | Path) -> dict[str, object]:
             "events": str(events_path),
             "memory": str(memory_path),
             "goal_state": str(goal_path),
+            "agent_profile": str(profile_path),
         },
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentram",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Async, model-agnostic Working RAM for coding agents.",
   "license": "MIT",
   "homepage": "https://github.com/trancongnghia/AGENT_RAM#readme",
@@ -33,6 +33,8 @@
   "files": [
     "agentram/*.py",
     "bin/*.js",
+    ".claude/agents/*.md",
+    ".claude/commands/*.md",
     "agentram_mcp_server.py",
     "agentram_daemon.py",
     "codex_ram.py",

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "agentram"
-version = "0.1.0"
+version = "0.1.2"
 description = "Async, model-agnostic RAM layer for agentic coding tools."
 readme = "README.md"
 license = "MIT"