Skip to content

Self-improving AI Employees for everyone

feat: native LLM provider layer with Protocol-based typing

trohitg0e9b4e31f4a3
diff --git a/server/services/llm/__init__.py b/server/services/llm/__init__.py
new file mode 100644
index 00000000..28108693
--- /dev/null
+++ b/server/services/llm/__init__.py
@@ -0,0 +1,52 @@
+"""LLM service layer -- native provider SDKs, config, protocol types, factory."""
+
+from services.llm.config import (
+ ProviderConfig,
+ PROVIDER_CONFIGS,
+ detect_provider_from_model,
+ is_model_valid_for_provider,
+ get_default_model,
+ get_default_model_async,
+ resolve_max_tokens,
+ resolve_temperature,
+ build_headers,
+)
+from services.llm.protocol import (
+ ThinkingConfig,
+ ToolDef,
+ ToolCall,
+ Message,
+ Usage,
+ LLMResponse,
+ LLMProvider,
+)
+from services.llm.messages import is_valid_message_content, filter_empty_messages
+from services.llm.factory import create_provider, is_native_provider, NATIVE_PROVIDERS
+
+__all__ = [
+ # Config
+ "ProviderConfig",
+ "PROVIDER_CONFIGS",
+ "detect_provider_from_model",
+ "is_model_valid_for_provider",
+ "get_default_model",
+ "get_default_model_async",
+ "resolve_max_tokens",
+ "resolve_temperature",
+ "build_headers",
+ # Protocol types
+ "ThinkingConfig",
+ "ToolDef",
+ "ToolCall",
+ "Message",
+ "Usage",
+ "LLMResponse",
+ "LLMProvider",
+ # Messages
+ "is_valid_message_content",
+ "filter_empty_messages",
+ # Factory
+ "create_provider",
+ "is_native_provider",
+ "NATIVE_PROVIDERS",
+]
diff --git a/server/services/llm/config.py b/server/services/llm/config.py
new file mode 100644
index 00000000..99f5f8ce
--- /dev/null
+++ b/server/services/llm/config.py
@@ -0,0 +1,196 @@
+"""Provider configuration and model resolution.
+
+Loads provider metadata from config/llm_defaults.json.
+No LangChain imports -- pure config and resolution logic.
+"""
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Dict, Any, Optional, Tuple
+
+from core.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# Provider config dataclass
+# ---------------------------------------------------------------------------
+
+@dataclass
+class ProviderConfig:
+ """Metadata for a single LLM provider."""
+ name: str
+ default_model: str
+ detection_patterns: Tuple[str, ...]
+ models_endpoint: str
+ api_key_header: str # e.g. "Authorization", "x-api-key"
+ api_key_format: str = "Bearer {key}" # how the header value is built
+ extra_headers: Dict[str, str] = field(default_factory=dict)
+
+
+# ---------------------------------------------------------------------------
+# Load config/llm_defaults.json once at import time
+# ---------------------------------------------------------------------------
+
+def _load_llm_defaults() -> Dict[str, Any]:
+ config_path = Path(__file__).parent.parent.parent / "config" / "llm_defaults.json"
+ try:
+ with open(config_path, encoding="utf-8") as f:
+ return json.load(f)
+ except Exception as e:
+ logger.warning(f"Could not load llm_defaults.json: {e}")
+ return {"providers": {}}
+
+
+LLM_DEFAULTS: Dict[str, Any] = _load_llm_defaults()
+
+
+def reload_defaults() -> None:
+ """Reload llm_defaults.json (e.g. after model registry refresh)."""
+ global LLM_DEFAULTS
+ LLM_DEFAULTS = _load_llm_defaults()
+
+
+# ---------------------------------------------------------------------------
+# Provider registry -- built from llm_defaults.json
+# ---------------------------------------------------------------------------
+
+PROVIDER_CONFIGS: Dict[str, ProviderConfig] = {
+ "openai": ProviderConfig(
+ name="openai",
+ default_model=LLM_DEFAULTS.get("providers", {}).get("openai", {}).get("default_model", "gpt-5.2"),
+ detection_patterns=("gpt", "openai", "o1", "o3", "o4"),
+ models_endpoint="https://api.openai.com/v1/models",
+ api_key_header="Authorization",
+ api_key_format="Bearer {key}",
+ ),
+ "anthropic": ProviderConfig(
+ name="anthropic",
+ default_model=LLM_DEFAULTS.get("providers", {}).get("anthropic", {}).get("default_model", "claude-sonnet-4-6"),
+ detection_patterns=("claude", "anthropic"),
+ models_endpoint="https://api.anthropic.com/v1/models",
+ api_key_header="x-api-key",
+ api_key_format="{key}",
+ extra_headers={"anthropic-version": "2023-06-01"},
+ ),
+ "gemini": ProviderConfig(
+ name="gemini",
+ default_model=LLM_DEFAULTS.get("providers", {}).get("gemini", {}).get("default_model", "gemini-2.5-flash"),
+ detection_patterns=("gemini", "google"),
+ models_endpoint="https://generativelanguage.googleapis.com/v1beta/models",
+ api_key_header="", # API key in URL query param for Gemini
+ api_key_format="",
+ ),
+ "openrouter": ProviderConfig(
+ name="openrouter",
+ default_model=LLM_DEFAULTS.get("providers", {}).get("openrouter", {}).get("default_model", "anthropic/claude-sonnet-4.6"),
+ detection_patterns=("openrouter",),
+ models_endpoint="https://openrouter.ai/api/v1/models",
+ api_key_header="Authorization",
+ api_key_format="Bearer {key}",
+ extra_headers={"HTTP-Referer": "http://localhost:3000", "X-Title": "MachinaOS"},
+ ),
+ "xai": ProviderConfig(
+ name="xai",
+ default_model=LLM_DEFAULTS.get("providers", {}).get("xai", {}).get("default_model", "grok-3"),
+ detection_patterns=("grok", "xai"),
+ models_endpoint="https://api.x.ai/v1/models",
+ api_key_header="Authorization",
+ api_key_format="Bearer {key}",
+ ),
+}
+
+
+def get_provider_config(provider: str) -> Optional[ProviderConfig]:
+ return PROVIDER_CONFIGS.get(provider)
+
+
+# ---------------------------------------------------------------------------
+# Provider detection from model name
+# ---------------------------------------------------------------------------
+
+def detect_provider_from_model(model: str) -> str:
+ model_lower = model.lower()
+ for name, cfg in PROVIDER_CONFIGS.items():
+ if any(p in model_lower for p in cfg.detection_patterns):
+ return name
+ return "openai"
+
+
+def is_model_valid_for_provider(model: str, provider: str) -> bool:
+ cfg = PROVIDER_CONFIGS.get(provider)
+ if not cfg:
+ return True
+ model_lower = model.lower()
+ return any(p in model_lower for p in cfg.detection_patterns)
+
+
+# ---------------------------------------------------------------------------
+# Default model helpers
+# ---------------------------------------------------------------------------
+
+def get_default_model(provider: str) -> str:
+ cfg = PROVIDER_CONFIGS.get(provider)
+ return cfg.default_model if cfg else "gpt-5.2"
+
+
+async def get_default_model_async(provider: str, database) -> str:
+ """DB user setting > JSON config > fallback."""
+ if database:
+ try:
+ db_defaults = await database.get_provider_defaults(provider)
+ if db_defaults and db_defaults.get("default_model"):
+ return db_defaults["default_model"]
+ except Exception as e:
+ logger.warning(f"Failed to get DB defaults for {provider}: {e}")
+ return get_default_model(provider)
+
+
+# ---------------------------------------------------------------------------
+# Max-tokens / temperature resolution
+# ---------------------------------------------------------------------------
+
+def resolve_max_tokens(params: dict, model: str, provider: str) -> int:
+ """Resolve max_tokens: user param -> model registry -> llm_defaults -> 4096."""
+ from services.model_registry import get_model_registry
+ registry = get_model_registry()
+ model_max = registry.get_max_output_tokens(model, provider)
+
+ user_val = params.get("max_tokens") or params.get("maxTokens")
+ if user_val:
+ user_int = int(user_val)
+ if user_int > model_max:
+ logger.info(f"[AI] Clamping max_tokens {user_int} -> {model_max} for {provider}/{model}")
+ return model_max
+ return user_int
+ return model_max
+
+
+def resolve_temperature(params: dict, model: str, provider: str, thinking_enabled: bool) -> float:
+ """Resolve temperature with model-specific constraints."""
+ from services.model_registry import get_model_registry
+ registry = get_model_registry()
+
+ user_temp = float(params.get("temperature", 0.7))
+
+ if registry.is_reasoning_model(model, provider):
+ return 1.0
+
+ if thinking_enabled and provider == "anthropic":
+ return 1.0
+
+ lo, hi = registry.get_temperature_range(model, provider)
+ return max(lo, min(hi, user_temp))
+
+
+def build_headers(provider: str, api_key: str) -> Dict[str, str]:
+ """Build HTTP headers for a provider (used by fetch_models)."""
+ cfg = PROVIDER_CONFIGS.get(provider)
+ if not cfg:
+ return {"Authorization": f"Bearer {api_key}"}
+ headers = dict(cfg.extra_headers)
+ if cfg.api_key_header:
+ headers[cfg.api_key_header] = cfg.api_key_format.format(key=api_key)
+ return headers
diff --git a/server/services/llm/factory.py b/server/services/llm/factory.py
new file mode 100644
index 00000000..8c478183
--- /dev/null
+++ b/server/services/llm/factory.py
@@ -0,0 +1,51 @@
+"""Provider factory -- lazy-imports native SDK providers."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from core.logging import get_logger
+from services.llm.protocol import LLMProvider
+
+logger = get_logger(__name__)
+
+# Providers that have native SDK implementations
+NATIVE_PROVIDERS = frozenset({"anthropic", "openai", "gemini", "openrouter", "xai"})
+
+
+def create_provider(
+ provider: str,
+ api_key: str,
+ *,
+ proxy_url: Optional[str] = None,
+) -> LLMProvider:
+ """Create a native LLM provider instance.
+
+ Lazy-imports the provider module to avoid loading SDKs at startup.
+ """
+ if provider == "anthropic":
+ from services.llm.providers.anthropic import AnthropicProvider
+ return AnthropicProvider(api_key, proxy_url=proxy_url)
+
+ if provider == "openai":
+ from services.llm.providers.openai import OpenAIProvider
+ return OpenAIProvider(api_key, proxy_url=proxy_url)
+
+ if provider == "gemini":
+ from services.llm.providers.gemini import GeminiProvider
+ return GeminiProvider(api_key, proxy_url=proxy_url)
+
+ if provider == "openrouter":
+ from services.llm.providers.openrouter import OpenRouterProvider
+ return OpenRouterProvider(api_key, proxy_url=proxy_url)
+
+ if provider == "xai":
+ # xAI uses OpenAI-compatible API
+ from services.llm.providers.openai import OpenAIProvider
+ return OpenAIProvider(api_key, base_url="https://api.x.ai/v1", proxy_url=proxy_url)
+
+ raise ValueError(f"Unknown provider: {provider}")
+
+
+def is_native_provider(provider: str) -> bool:
+ return provider in NATIVE_PROVIDERS
diff --git a/server/services/llm/messages.py b/server/services/llm/messages.py
new file mode 100644
index 00000000..40659d49
--- /dev/null
+++ b/server/services/llm/messages.py
@@ -0,0 +1,51 @@
+"""Message validation and filtering utilities.
+
+Provider-agnostic -- works with any message format.
+"""
+
+from typing import Any, List, Sequence
+
+
+def is_valid_message_content(content: Any) -> bool:
+ """Check if message content is non-empty for API calls."""
+ if content is None:
+ return False
+ if isinstance(content, list):
+ return any(
+ (isinstance(b, dict) and b.get("text", "").strip())
+ or (isinstance(b, str) and b.strip())
+ for b in content
+ )
+ if isinstance(content, str):
+ return bool(content.strip())
+ return bool(content)
+
+
+def filter_empty_messages(messages: Sequence) -> List:
+ """Filter out messages with empty content.
+
+ Works with both LangChain BaseMessage objects and native Message dataclasses.
+ """
+ filtered = []
+ for m in messages:
+ # Detect role (works for both LangChain and native messages)
+ role = getattr(m, "role", None) or getattr(m, "type", "")
+
+ # Tool messages -- always keep
+ if role == "tool":
+ filtered.append(m)
+ continue
+
+ # AI/assistant with tool_calls -- keep even if content is empty
+ if role in ("ai", "assistant"):
+ tool_calls = getattr(m, "tool_calls", None)
+ if tool_calls:
+ filtered.append(m)
+ continue
+
+ # Everything else -- keep only if content is non-empty
+ content = getattr(m, "content", None)
+ if is_valid_message_content(content):
+ filtered.append(m)
+
+ return filtered
diff --git a/server/services/llm/protocol.py b/server/services/llm/protocol.py
new file mode 100644
index 00000000..1a3bfb6f
--- /dev/null
+++ b/server/services/llm/protocol.py
@@ -0,0 +1,101 @@
+"""Shared types and provider protocol for native LLM providers.
+
+All providers implement LLMProvider (structural typing via Protocol).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional, Protocol, runtime_checkable
+
+
+# ---------------------------------------------------------------------------
+# Shared data types
+# ---------------------------------------------------------------------------
+
+@dataclass
+class ThinkingConfig:
+ """Unified thinking/reasoning configuration.
+
+ - Anthropic: budget_tokens (int)
+ - OpenAI o-series / GPT-5: reasoning_effort (low/medium/high)
+ - Gemini 2.5: thinking_budget (int tokens)
+ - Gemini 3+: thinking_level (low/medium/high)
+ - Groq Qwen3: reasoning_format (parsed/hidden)
+ """
+ enabled: bool = False
+ budget: int = 2048
+ effort: str = "medium"
+ level: str = "medium" # Gemini 3+ thinking_level
+ format: str = "parsed"
+
+
+@dataclass
+class ToolDef:
+ """Tool definition passed to the LLM."""
+ name: str
+ description: str
+ parameters: Dict[str, Any] # JSON Schema
+
+
+@dataclass
+class ToolCall:
+ """A tool invocation returned by the LLM."""
+ id: str
+ name: str
+ args: Dict[str, Any]
+
+
+@dataclass
+class Message:
+ """Normalized chat message."""
+ role: str # system | user | assistant | tool
+ content: str = ""
+ tool_calls: List[ToolCall] = field(default_factory=list)
+ tool_call_id: Optional[str] = None
+ name: Optional[str] = None
+
+
+@dataclass
+class Usage:
+ """Token usage metrics."""
+ input_tokens: int = 0
+ output_tokens: int = 0
+ total_tokens: int = 0
+ cache_creation_tokens: int = 0
+ cache_read_tokens: int = 0
+ reasoning_tokens: int = 0
+
+
+@dataclass
+class LLMResponse:
+ """Normalized response from any LLM provider."""
+ content: str = ""
+ thinking: Optional[str] = None
+ tool_calls: List[ToolCall] = field(default_factory=list)
+ usage: Usage = field(default_factory=Usage)
+ model: str = ""
+ finish_reason: str = "stop"
+ raw: Any = None
+
+
+# ---------------------------------------------------------------------------
+# Provider protocol (structural typing)
+# ---------------------------------------------------------------------------
+
+@runtime_checkable
+class LLMProvider(Protocol):
+ provider_name: str
+
+ async def chat(
+ self,
+ messages: List[Message],
+ *,
+ model: str,
+ temperature: float = 0.7,
+ max_tokens: int = 4096,
+ thinking: Optional[ThinkingConfig] = None,
+ tools: Optional[List[ToolDef]] = None,
+ ) -> LLMResponse: ...
+
+ async def fetch_models(self, api_key: str) -> List[str]: ...
diff --git a/server/services/llm/providers/__init__.py b/server/services/llm/providers/__init__.py
new file mode 100644
index 00000000..14deae54
--- /dev/null
+++ b/server/services/llm/providers/__init__.py
@@ -0,0 +1 @@
+"""Native LLM provider implementations."""
diff --git a/server/services/llm/providers/anthropic.py b/server/services/llm/providers/anthropic.py
new file mode 100644
index 00000000..d1dc4a37
--- /dev/null
+++ b/server/services/llm/providers/anthropic.py
@@ -0,0 +1,171 @@
+"""Anthropic native provider using the official `anthropic` Python SDK."""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Dict, List, Optional
+
+from core.logging import get_logger
+from services.llm.protocol import (
+ LLMResponse, Message, ThinkingConfig, ToolCall, ToolDef, Usage,
+)
+
+logger = get_logger(__name__)
+
+
+class AnthropicProvider:
+ provider_name = "anthropic"
+
+ def __init__(self, api_key: str, *, proxy_url: Optional[str] = None):
+ import anthropic
+ kwargs: Dict[str, Any] = {"api_key": api_key}
+ if proxy_url:
+ kwargs["base_url"] = proxy_url
+ kwargs["api_key"] = "ollama"
+ self._client = anthropic.AsyncAnthropic(**kwargs)
+
+ # ------------------------------------------------------------------
+ # chat
+ # ------------------------------------------------------------------
+
+ async def chat(
+ self,
+ messages: List[Message],
+ *,
+ model: str,
+ temperature: float = 0.7,
+ max_tokens: int = 4096,
+ thinking: Optional[ThinkingConfig] = None,
+ tools: Optional[List[ToolDef]] = None,
+ ) -> LLMResponse:
+ system, api_msgs = self._split_system(messages)
+
+ params: Dict[str, Any] = {
+ "model": model,
+ "messages": api_msgs,
+ "max_tokens": max_tokens,
+ }
+ if system:
+ params["system"] = system
+
+ # Thinking / extended thinking
+ if thinking and thinking.enabled:
+ budget = thinking.budget or 2048
+ if max_tokens <= budget:
+ params["max_tokens"] = budget + 1024
+ params["thinking"] = {"type": "enabled", "budget_tokens": budget}
+ params["temperature"] = 1 # required by Anthropic when thinking
+ else:
+ params["temperature"] = temperature
+
+ # Tools
+ if tools:
+ params["tools"] = [self._to_api_tool(t) for t in tools]
+
+ resp = await self._client.messages.create(**params)
+ return self._normalize(resp, model)
+
+ # ------------------------------------------------------------------
+ # fetch_models
+ # ------------------------------------------------------------------
+
+ async def fetch_models(self, api_key: str) -> List[str]:
+ import httpx
+ async with httpx.AsyncClient() as client:
+ r = await client.get(
+ "https://api.anthropic.com/v1/models",
+ headers={"x-api-key": api_key, "anthropic-version": "2023-06-01"},
+ timeout=15.0,
+ )
+ r.raise_for_status()
+ data = r.json()
+ return sorted([m["id"] for m in data.get("data", [])])
+
+ # ------------------------------------------------------------------
+ # internals
+ # ------------------------------------------------------------------
+
+ def _split_system(self, messages: List[Message]):
+ """Extract system message (Anthropic takes it as a top-level param)."""
+ system_parts = []
+ api_msgs = []
+ for m in messages:
+ if m.role == "system":
+ if m.content:
+ system_parts.append(m.content)
+ else:
+ api_msgs.append(self._to_api_message(m))
+ return "\n\n".join(system_parts) if system_parts else None, api_msgs
+
+ def _to_api_message(self, m: Message) -> Dict[str, Any]:
+ role = "assistant" if m.role == "assistant" else "user"
+
+ if m.role == "tool":
+ return {
+ "role": "user",
+ "content": [
+ {
+ "type": "tool_result",
+ "tool_use_id": m.tool_call_id or "",
+ "content": m.content,
+ }
+ ],
+ }
+
+ if m.role == "assistant" and m.tool_calls:
+ content: List[Dict[str, Any]] = []
+ if m.content:
+ content.append({"type": "text", "text": m.content})
+ for tc in m.tool_calls:
+ content.append({
+ "type": "tool_use",
+ "id": tc.id,
+ "name": tc.name,
+ "input": tc.args,
+ })
+ return {"role": "assistant", "content": content}
+
+ return {"role": role, "content": m.content}
+
+ @staticmethod
+ def _to_api_tool(tool: ToolDef) -> Dict[str, Any]:
+ return {
+ "name": tool.name,
+ "description": tool.description,
+ "input_schema": tool.parameters,
+ }
+
+ def _normalize(self, resp: Any, model: str) -> LLMResponse:
+ text_parts = []
+ thinking_parts = []
+ tool_calls = []
+
+ for block in resp.content:
+ if block.type == "text":
+ text_parts.append(block.text)
+ elif block.type == "thinking":
+ thinking_parts.append(block.thinking)
+ elif block.type == "tool_use":
+ tool_calls.append(ToolCall(
+ id=block.id,
+ name=block.name,
+ args=block.input if isinstance(block.input, dict) else json.loads(block.input),
+ ))
+
+ usage = Usage(
+ input_tokens=getattr(resp.usage, "input_tokens", 0),
+ output_tokens=getattr(resp.usage, "output_tokens", 0),
+ total_tokens=getattr(resp.usage, "input_tokens", 0) + getattr(resp.usage, "output_tokens", 0),
+ cache_creation_tokens=getattr(resp.usage, "cache_creation_input_tokens", 0),
+ cache_read_tokens=getattr(resp.usage, "cache_read_input_tokens", 0),
+ )
+
+ return LLMResponse(
+ content="\n".join(text_parts),
+ thinking="\n\n".join(thinking_parts) if thinking_parts else None,
+ tool_calls=tool_calls,
+ usage=usage,
+ model=model,
+ finish_reason=resp.stop_reason or "stop",
+ raw=resp,
+ )
diff --git a/server/services/llm/providers/gemini.py b/server/services/llm/providers/gemini.py
new file mode 100644
index 00000000..abba94f5
--- /dev/null
+++ b/server/services/llm/providers/gemini.py
@@ -0,0 +1,184 @@
+"""Google Gemini native provider using the official `google-genai` SDK."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from core.logging import get_logger
+from services.llm.protocol import (
+ LLMResponse, Message, ThinkingConfig, ToolCall, ToolDef, Usage,
+)
+
+logger = get_logger(__name__)
+
+
+class GeminiProvider:
+ provider_name = "gemini"
+
+ def __init__(self, api_key: str, *, proxy_url: Optional[str] = None):
+ from google import genai
+ kwargs: Dict[str, Any] = {"api_key": api_key}
+ if proxy_url:
+ kwargs["http_options"] = {"base_url": proxy_url}
+ self._client = genai.Client(**kwargs)
+
+ # ------------------------------------------------------------------
+ # chat
+ # ------------------------------------------------------------------
+
+ async def chat(
+ self,
+ messages: List[Message],
+ *,
+ model: str,
+ temperature: float = 0.7,
+ max_tokens: int = 4096,
+ thinking: Optional[ThinkingConfig] = None,
+ tools: Optional[List[ToolDef]] = None,
+ ) -> LLMResponse:
+ from google.genai import types
+
+ system_instruction, contents = self._split_system_and_contents(messages)
+
+ config: Dict[str, Any] = {
+ "temperature": temperature,
+ "max_output_tokens": max_tokens,
+ }
+
+ if system_instruction:
+ config["system_instruction"] = system_instruction
+
+ # Thinking -- pass available fields, let the SDK/API resolve per model
+ if thinking and thinking.enabled:
+ thinking_kwargs: Dict[str, Any] = {}
+ if thinking.budget:
+ thinking_kwargs["thinking_budget"] = thinking.budget
+ if thinking.level:
+ thinking_kwargs["thinking_level"] = thinking.level
+ config["thinking_config"] = types.ThinkingConfig(**thinking_kwargs)
+
+ # Tools
+ if tools:
+ config["tools"] = [self._to_api_tool(t) for t in tools]
+
+ resp = await self._client.aio.models.generate_content(
+ model=model,
+ contents=contents,
+ config=types.GenerateContentConfig(**config),
+ )
+ return self._normalize(resp, model)
+
+ # ------------------------------------------------------------------
+ # fetch_models
+ # ------------------------------------------------------------------
+
+ async def fetch_models(self, api_key: str) -> List[str]:
+ import httpx
+ async with httpx.AsyncClient() as client:
+ r = await client.get(
+ f"https://generativelanguage.googleapis.com/v1beta/models?key={api_key}",
+ timeout=15.0,
+ )
+ r.raise_for_status()
+ data = r.json()
+ models = []
+ for m in data.get("models", []):
+ name = m.get("name", "")
+ if name.startswith("models/"):
+ name = name[7:]
+ models.append(name)
+ return sorted(models)
+
+ # ------------------------------------------------------------------
+ # internals
+ # ------------------------------------------------------------------
+
+ def _split_system_and_contents(self, messages: List[Message]):
+ system_parts = []
+ contents = []
+ for m in messages:
+ if m.role == "system":
+ if m.content:
+ system_parts.append(m.content)
+ continue
+
+ if m.role == "tool":
+ contents.append({
+ "role": "function",
+ "parts": [{"function_response": {
+ "name": m.name or "",
+ "response": {"result": m.content},
+ }}],
+ })
+ continue
+
+ if m.role == "assistant" and m.tool_calls:
+ parts = []
+ if m.content:
+ parts.append({"text": m.content})
+ for tc in m.tool_calls:
+ parts.append({"function_call": {
+ "name": tc.name,
+ "args": tc.args,
+ }})
+ contents.append({"role": "model", "parts": parts})
+ continue
+
+ role = "model" if m.role == "assistant" else "user"
+ contents.append({"role": role, "parts": [{"text": m.content}]})
+
+ system = "\n\n".join(system_parts) if system_parts else None
+ return system, contents
+
+ @staticmethod
+ def _to_api_tool(tool: ToolDef) -> Dict[str, Any]:
+ return {
+ "function_declarations": [{
+ "name": tool.name,
+ "description": tool.description,
+ "parameters": tool.parameters,
+ }]
+ }
+
+ def _normalize(self, resp: Any, model: str) -> LLMResponse:
+ text_parts = []
+ thinking_parts = []
+ tool_calls = []
+
+ if resp.candidates:
+ for part in resp.candidates[0].content.parts:
+ if hasattr(part, "thought") and part.thought:
+ thinking_parts.append(part.text)
+ elif hasattr(part, "function_call") and part.function_call:
+ fc = part.function_call
+ args = dict(fc.args) if fc.args else {}
+ tool_calls.append(ToolCall(
+ id=fc.name, # Gemini doesn't have separate IDs
+ name=fc.name,
+ args=args,
+ ))
+ elif hasattr(part, "text") and part.text:
+ text_parts.append(part.text)
+
+ um = resp.usage_metadata if hasattr(resp, "usage_metadata") and resp.usage_metadata else None
+ usage = Usage(
+ input_tokens=getattr(um, "prompt_token_count", 0) if um else 0,
+ output_tokens=getattr(um, "candidates_token_count", 0) if um else 0,
+ total_tokens=getattr(um, "total_token_count", 0) if um else 0,
+ )
+
+ finish = "stop"
+ if resp.candidates and hasattr(resp.candidates[0], "finish_reason"):
+ fr = resp.candidates[0].finish_reason
+ if fr:
+ finish = str(fr).lower()
+
+ return LLMResponse(
+ content="\n".join(text_parts),
+ thinking="\n\n".join(thinking_parts) if thinking_parts else None,
+ tool_calls=tool_calls,
+ usage=usage,
+ model=model,
+ finish_reason=finish,
+ raw=resp,
+ )
diff --git a/server/services/llm/providers/openai.py b/server/services/llm/providers/openai.py
new file mode 100644
index 00000000..a340f6a9
--- /dev/null
+++ b/server/services/llm/providers/openai.py
@@ -0,0 +1,175 @@
+"""OpenAI native provider using the official `openai` Python SDK.
+
+Handles GPT-5.x, GPT-4.x, and o-series reasoning models.
+Also used as base for OpenRouter (same API shape, different base_url).
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Dict, List, Optional
+
+from core.logging import get_logger
+from services.llm.protocol import (
+ LLMResponse, Message, ThinkingConfig, ToolCall, ToolDef, Usage,
+)
+
+logger = get_logger(__name__)
+
+
+class OpenAIProvider:
+ provider_name = "openai"
+
+ def __init__(self, api_key: str, *, proxy_url: Optional[str] = None, base_url: Optional[str] = None):
+ import openai
+ kwargs: Dict[str, Any] = {"api_key": api_key}
+ url = proxy_url or base_url
+ if url:
+ kwargs["base_url"] = url
+ if proxy_url:
+ kwargs["api_key"] = "ollama"
+ self._client = openai.AsyncOpenAI(**kwargs)
+
+ # ------------------------------------------------------------------
+ # chat
+ # ------------------------------------------------------------------
+
+ async def chat(
+ self,
+ messages: List[Message],
+ *,
+ model: str,
+ temperature: float = 0.7,
+ max_tokens: int = 4096,
+ thinking: Optional[ThinkingConfig] = None,
+ tools: Optional[List[ToolDef]] = None,
+ ) -> LLMResponse:
+ params: Dict[str, Any] = {
+ "model": model,
+ "messages": [self._to_api_message(m) for m in messages],
+ }
+
+ is_reasoning = model.startswith(("o1", "o3", "o4"))
+
+ # Reasoning models use max_completion_tokens, not max_tokens
+ if is_reasoning:
+ params["max_completion_tokens"] = max_tokens
+ else:
+ params["max_tokens"] = max_tokens
+ params["temperature"] = temperature
+
+ # Thinking / reasoning effort
+ if thinking and thinking.enabled:
+ effort = thinking.effort or "medium"
+ if is_reasoning:
+ params["reasoning_effort"] = effort
+ elif model.startswith("gpt-5"):
+ params["reasoning_effort"] = effort
+
+ # Tools
+ if tools:
+ params["tools"] = [self._to_api_tool(t) for t in tools]
+
+ resp = await self._client.chat.completions.create(**params)
+ return self._normalize(resp, model)
+
+ # ------------------------------------------------------------------
+ # fetch_models
+ # ------------------------------------------------------------------
+
+ async def fetch_models(self, api_key: str) -> List[str]:
+ import httpx
+ async with httpx.AsyncClient() as client:
+ r = await client.get(
+ "https://api.openai.com/v1/models",
+ headers={"Authorization": f"Bearer {api_key}"},
+ timeout=15.0,
+ )
+ r.raise_for_status()
+ data = r.json()
+ return sorted([m["id"] for m in data.get("data", [])])
+
+ # ------------------------------------------------------------------
+ # internals
+ # ------------------------------------------------------------------
+
+ @staticmethod
+ def _to_api_message(m: Message) -> Dict[str, Any]:
+ if m.role == "tool":
+ return {
+ "role": "tool",
+ "tool_call_id": m.tool_call_id or "",
+ "content": m.content,
+ }
+
+ if m.role == "assistant" and m.tool_calls:
+ return {
+ "role": "assistant",
+ "content": m.content or None,
+ "tool_calls": [
+ {
+ "id": tc.id,
+ "type": "function",
+ "function": {
+ "name": tc.name,
+ "arguments": json.dumps(tc.args),
+ },
+ }
+ for tc in m.tool_calls
+ ],
+ }
+
+ return {"role": m.role, "content": m.content}
+
+ @staticmethod
+ def _to_api_tool(tool: ToolDef) -> Dict[str, Any]:
+ return {
+ "type": "function",
+ "function": {
+ "name": tool.name,
+ "description": tool.description,
+ "parameters": tool.parameters,
+ },
+ }
+
+ def _normalize(self, resp: Any, model: str) -> LLMResponse:
+ choice = resp.choices[0] if resp.choices else None
+ if not choice:
+ return LLMResponse(model=model)
+
+ msg = choice.message
+ content = msg.content or ""
+ thinking = None
+ tool_calls = []
+
+ # Extract reasoning/thinking if present
+ if hasattr(msg, "reasoning_content") and msg.reasoning_content:
+ thinking = msg.reasoning_content
+
+ # Tool calls
+ if msg.tool_calls:
+ for tc in msg.tool_calls:
+ args = tc.function.arguments
+ tool_calls.append(ToolCall(
+ id=tc.id,
+ name=tc.function.name,
+ args=json.loads(args) if isinstance(args, str) else args,
+ ))
+
+ u = resp.usage
+ usage = Usage(
+ input_tokens=getattr(u, "prompt_tokens", 0) if u else 0,
+ output_tokens=getattr(u, "completion_tokens", 0) if u else 0,
+ total_tokens=getattr(u, "total_tokens", 0) if u else 0,
+ reasoning_tokens=getattr(getattr(u, "completion_tokens_details", None), "reasoning_tokens", 0) if u else 0,
+ )
+
+ return LLMResponse(
+ content=content,
+ thinking=thinking,
+ tool_calls=tool_calls,
+ usage=usage,
+ model=model,
+ finish_reason=choice.finish_reason or "stop",
+ raw=resp,
+ )
diff --git a/server/services/llm/providers/openrouter.py b/server/services/llm/providers/openrouter.py
new file mode 100644
index 00000000..5e93966f
--- /dev/null
+++ b/server/services/llm/providers/openrouter.py
@@ -0,0 +1,75 @@
+"""OpenRouter provider -- wraps OpenAI-compatible API with different base_url."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from core.logging import get_logger
+from services.llm.protocol import (
+ LLMResponse, Message, ThinkingConfig, ToolDef,
+)
+from services.llm.providers.openai import OpenAIProvider
+
+logger = get_logger(__name__)
+
+
+class OpenRouterProvider(OpenAIProvider):
+ provider_name = "openrouter"
+
+ def __init__(self, api_key: str, *, proxy_url: Optional[str] = None):
+ import openai
+ kwargs: Dict[str, Any] = {
+ "api_key": api_key,
+ "base_url": proxy_url or "https://openrouter.ai/api/v1",
+ "default_headers": {
+ "HTTP-Referer": "http://localhost:3000",
+ "X-Title": "MachinaOS",
+ },
+ }
+ self._client = openai.AsyncOpenAI(**kwargs)
+
+ async def chat(
+ self,
+ messages: List[Message],
+ *,
+ model: str,
+ temperature: float = 0.7,
+ max_tokens: int = 4096,
+ thinking: Optional[ThinkingConfig] = None,
+ tools: Optional[List[ToolDef]] = None,
+ ) -> LLMResponse:
+ # Strip [FREE] prefix from model ID
+ clean_model = model.replace("[FREE] ", "")
+ return await super().chat(
+ messages,
+ model=clean_model,
+ temperature=temperature,
+ max_tokens=max_tokens,
+ thinking=thinking,
+ tools=tools,
+ )
+
+ async def fetch_models(self, api_key: str) -> List[str]:
+ import httpx
+ async with httpx.AsyncClient() as client:
+ r = await client.get(
+ "https://openrouter.ai/api/v1/models",
+ headers={
+ "Authorization": f"Bearer {api_key}",
+ "HTTP-Referer": "http://localhost:3000",
+ "X-Title": "MachinaOS",
+ },
+ timeout=15.0,
+ )
+ r.raise_for_status()
+ data = r.json()
+
+ models = []
+ for m in data.get("data", []):
+ model_id = m.get("id", "")
+ pricing = m.get("pricing", {})
+ is_free = pricing.get("prompt") == "0" and pricing.get("completion") == "0"
+ display = f"[FREE] {model_id}" if is_free else model_id
+ models.append(display)
+
+ return sorted(models, key=lambda x: (not x.startswith("[FREE]"), x))
diff --git a/server/services/memory.py b/server/services/memory.py
new file mode 100644
index 00000000..d53877fd
--- /dev/null
+++ b/server/services/memory.py
@@ -0,0 +1,93 @@
+"""Markdown-based conversation memory helpers.
+
+Parse, append, trim, and archive conversation history stored in markdown format.
+Used by AI Agent and Chat Agent for persistent memory across turns.
+"""
+
+import re
+from datetime import datetime
+from typing import Dict, Any, List
+
+from langchain_core.messages import HumanMessage, AIMessage, BaseMessage
+
+from core.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+def parse_memory_markdown(content: str) -> List[BaseMessage]:
+ """Parse markdown memory content into LangChain messages.
+
+ Markdown format:
+ ### **Human** (timestamp)
+ message content
+
+ ### **Assistant** (timestamp)
+ response content
+ """
+ messages = []
+ pattern = r'### \*\*(Human|Assistant)\*\*[^\n]*\n(.*?)(?=\n### \*\*|$)'
+ for role, text in re.findall(pattern, content, re.DOTALL):
+ text = text.strip()
+ if text:
+ msg_class = HumanMessage if role == 'Human' else AIMessage
+ messages.append(msg_class(content=text))
+ return messages
+
+
+def append_to_memory_markdown(content: str, role: str, message: str) -> str:
+ """Append a message to markdown memory content."""
+ ts = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+ label = "Human" if role == "human" else "Assistant"
+ entry = f"\n### **{label}** ({ts})\n{message}\n"
+ # Remove empty state message if present
+ return content.replace("*No messages yet.*\n", "") + entry
+
+
+def trim_markdown_window(content: str, window_size: int) -> tuple:
+ """Keep last N message pairs, return (trimmed_content, removed_texts).
+
+ Args:
+ content: Full markdown content
+ window_size: Number of message PAIRS to keep (human+assistant)
+
+ Returns:
+ Tuple of (trimmed markdown, list of removed message texts for archival)
+ """
+ pattern = r'(### \*\*(Human|Assistant)\*\*[^\n]*\n.*?)(?=\n### \*\*|$)'
+ blocks = [m[0] for m in re.findall(pattern, content, re.DOTALL)]
+
+ if len(blocks) <= window_size * 2:
+ return content, []
+
+ keep = blocks[-(window_size * 2):]
+ removed = blocks[:-(window_size * 2)]
+
+ # Extract text from removed blocks for vector storage
+ removed_texts = []
+ for block in removed:
+ match = re.search(r'\n(.*)$', block, re.DOTALL)
+ if match:
+ removed_texts.append(match.group(1).strip())
+
+ return "# Conversation History\n" + "\n".join(keep), removed_texts
+
+
+# Global cache for vector stores per session (InMemoryVectorStore)
+_memory_vector_stores: Dict[str, Any] = {}
+
+
+def get_memory_vector_store(session_id: str):
+ """Get or create InMemoryVectorStore for a session."""
+ if session_id not in _memory_vector_stores:
+ try:
+ from langchain_core.vectorstores import InMemoryVectorStore
+ from langchain_huggingface import HuggingFaceEmbeddings
+
+ embeddings = HuggingFaceEmbeddings(model_name="BAAI/bge-small-en-v1.5")
+ _memory_vector_stores[session_id] = InMemoryVectorStore(embeddings)
+ logger.debug(f"[Memory] Created vector store for session '{session_id}'")
+ except ImportError as e:
+ logger.warning(f"[Memory] Vector store not available: {e}")
+ return None
+ return _memory_vector_stores[session_id]
diff --git a/server/services/skill_prompt.py b/server/services/skill_prompt.py
new file mode 100644
index 00000000..6a21c30d
--- /dev/null
+++ b/server/services/skill_prompt.py
@@ -0,0 +1,70 @@
+"""Skill system prompt builder for AI agents.
+
+Constructs system message text from connected skill nodes.
+Personality skills get full SKILL.md instructions injected.
+Standard skills get brief registry descriptions.
+"""
+
+from typing import Dict, Any, List
+
+from core.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+def build_skill_system_prompt(skill_data: List[Dict[str, Any]], log_prefix: str = "[Agent]") -> tuple:
+ """Build skill injection text for the system message.
+
+ Personality skills (names ending in '-personality') get their FULL SKILL.md
+ instructions injected. All other skills get brief registry descriptions only.
+
+ Args:
+ skill_data: List of skill entries from _collect_agent_connections.
+ log_prefix: Log prefix for debug messages.
+
+ Returns:
+ Tuple of (prompt_text, has_personality). prompt_text is the string to
+ append to system_message. has_personality indicates whether any
+ personality skills were found (used to drop the default system message).
+ """
+ if not skill_data:
+ return "", False
+
+ from services.skill_loader import get_skill_loader
+
+ skill_loader = get_skill_loader()
+ skill_loader.scan_skills()
+
+ personality_blocks = []
+ non_personality_names = []
+
+ for skill_info in skill_data:
+ skill_name = skill_info.get('skill_name') or skill_info.get('node_type', '').replace('Skill', '-skill').lower()
+ if skill_name.endswith('skill') and '-' not in skill_name:
+ skill_name = skill_name[:-5] + '-skill'
+
+ if skill_name.endswith('-personality'):
+ instructions = skill_info.get('parameters', {}).get('instructions', '')
+ if instructions:
+ personality_blocks.append(instructions)
+ logger.debug(f"{log_prefix} Personality skill injected (full): {skill_name}")
+ else:
+ logger.warning(f"{log_prefix} Personality skill {skill_name} has no instructions")
+ else:
+ non_personality_names.append(skill_name)
+ logger.debug(f"{log_prefix} Skill detected: {skill_name}")
+
+ parts = []
+
+ for block in personality_blocks:
+ parts.append(block)
+
+ if non_personality_names:
+ registry_prompt = skill_loader.get_registry_prompt(non_personality_names)
+ if registry_prompt:
+ parts.append(registry_prompt)
+
+ if parts:
+ logger.debug(f"{log_prefix} Enhanced system message: {len(personality_blocks)} personality, {len(non_personality_names)} standard skills")
+
+ return "\n\n".join(parts), len(personality_blocks) > 0
diff --git a/server/tests/__init__.py b/server/tests/__init__.py
new file mode 100644
index 00000000..e69de29b
diff --git a/server/tests/conftest.py b/server/tests/conftest.py
new file mode 100644
index 00000000..b7a778d5
--- /dev/null
+++ b/server/tests/conftest.py
@@ -0,0 +1,22 @@
+"""Shared fixtures for native LLM provider tests."""
+
+import sys
+from pathlib import Path
+from unittest.mock import MagicMock
+
+# Ensure server/ is on sys.path
+SERVER_DIR = Path(__file__).parent.parent
+if str(SERVER_DIR) not in sys.path:
+ sys.path.insert(0, str(SERVER_DIR))
+
+
+# Stub core.logging before any provider import
+def _stub_module(name: str) -> MagicMock:
+ if name not in sys.modules:
+ sys.modules[name] = MagicMock()
+ return sys.modules[name]
+
+
+_stub_module("core")
+_core_logging = _stub_module("core.logging")
+_core_logging.get_logger = MagicMock(return_value=MagicMock())
diff --git a/server/tests/llm/__init__.py b/server/tests/llm/__init__.py
new file mode 100644
index 00000000..e69de29b
diff --git a/server/tests/llm/test_factory.py b/server/tests/llm/test_factory.py
new file mode 100644
index 00000000..6ba79df5
--- /dev/null
+++ b/server/tests/llm/test_factory.py
@@ -0,0 +1,67 @@
+"""Test create_provider() factory and provider detection."""
+
+from unittest.mock import MagicMock, patch
+
+from services.llm.factory import create_provider, is_native_provider, NATIVE_PROVIDERS
+from services.llm.config import detect_provider_from_model
+from services.llm.protocol import LLMProvider
+
+
+def test_native_providers_set():
+ assert NATIVE_PROVIDERS == {"anthropic", "openai", "gemini", "openrouter", "xai"}
+
+
+def test_is_native_provider():
+ assert is_native_provider("openai") is True
+ assert is_native_provider("groq") is False
+
+
+def test_create_anthropic_provider():
+ with patch("anthropic.AsyncAnthropic"):
+ p = create_provider("anthropic", "sk-test")
+ assert p.provider_name == "anthropic"
+ assert isinstance(p, LLMProvider)
+
+
+def test_create_openai_provider():
+ with patch("openai.AsyncOpenAI"):
+ p = create_provider("openai", "sk-test")
+ assert p.provider_name == "openai"
+ assert isinstance(p, LLMProvider)
+
+
+def test_create_gemini_provider():
+ with patch("google.genai.Client"):
+ p = create_provider("gemini", "key")
+ assert p.provider_name == "gemini"
+ assert isinstance(p, LLMProvider)
+
+
+def test_create_openrouter_provider():
+ with patch("openai.AsyncOpenAI"):
+ p = create_provider("openrouter", "or-key")
+ assert p.provider_name == "openrouter"
+
+
+def test_create_xai_uses_openai_with_base_url():
+ with patch("openai.AsyncOpenAI") as mock_cls:
+ p = create_provider("xai", "xai-key")
+ assert p.provider_name == "openai" # reuses OpenAI class
+ mock_cls.assert_called_once()
+ call_kwargs = mock_cls.call_args[1]
+ assert call_kwargs["base_url"] == "https://api.x.ai/v1"
+
+
+def test_create_unknown_raises():
+ import pytest
+ with pytest.raises(ValueError, match="Unknown provider"):
+ create_provider("nonexistent", "key")
+
+
+def test_detect_provider_from_model():
+ assert detect_provider_from_model("gpt-5.2") == "openai"
+ assert detect_provider_from_model("o3-mini") == "openai"
+ assert detect_provider_from_model("claude-sonnet-4-6") == "anthropic"
+ assert detect_provider_from_model("gemini-2.5-flash") == "gemini"
+ assert detect_provider_from_model("grok-3") == "xai"
+ assert detect_provider_from_model("unknown-xyz") == "openai" # fallback
diff --git a/server/tests/llm/test_messages.py b/server/tests/llm/test_messages.py
new file mode 100644
index 00000000..440d24c0
--- /dev/null
+++ b/server/tests/llm/test_messages.py
@@ -0,0 +1,37 @@
+"""Test message filtering used before sending to provider APIs."""
+
+from services.llm.messages import filter_empty_messages
+from services.llm.protocol import Message, ToolCall
+
+
+def test_keeps_non_empty_messages():
+ msgs = [
+ Message(role="user", content="hi"),
+ Message(role="assistant", content="hello"),
+ ]
+ assert len(filter_empty_messages(msgs)) == 2
+
+
+def test_removes_empty_user_message():
+ msgs = [
+ Message(role="user", content=""),
+ Message(role="assistant", content="hello"),
+ ]
+ result = filter_empty_messages(msgs)
+ assert len(result) == 1
+
+
+def test_keeps_tool_messages_even_if_empty():
+ msgs = [Message(role="tool", content="", tool_call_id="1")]
+ assert len(filter_empty_messages(msgs)) == 1
+
+
+def test_keeps_assistant_with_tool_calls():
+ tc = ToolCall(id="1", name="calc", args={})
+ msgs = [Message(role="assistant", content="", tool_calls=[tc])]
+ assert len(filter_empty_messages(msgs)) == 1
+
+
+def test_removes_empty_assistant_without_tool_calls():
+ msgs = [Message(role="assistant", content="")]
+ assert len(filter_empty_messages(msgs)) == 0
diff --git a/server/tests/llm/test_providers.py b/server/tests/llm/test_providers.py
new file mode 100644
index 00000000..f848804b
--- /dev/null
+++ b/server/tests/llm/test_providers.py
@@ -0,0 +1,312 @@
+"""Test provider message formatting and response normalization.
+
+These tests verify the internal conversion logic without hitting real APIs.
+"""
+
+import json
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+
+from services.llm.protocol import LLMResponse, Message, ThinkingConfig, ToolCall, ToolDef, Usage
+
+
+# ---------------------------------------------------------------------------
+# Anthropic: message formatting + response normalization
+# ---------------------------------------------------------------------------
+
+class TestAnthropicProvider:
+
+ @pytest.fixture
+ def provider(self):
+ with patch("anthropic.AsyncAnthropic"):
+ from services.llm.providers.anthropic import AnthropicProvider
+ return AnthropicProvider("sk-test")
+
+ def test_system_extracted_from_messages(self, provider):
+ msgs = [
+ Message(role="system", content="Be helpful"),
+ Message(role="user", content="Hi"),
+ ]
+ system, api_msgs = provider._split_system(msgs)
+ assert system == "Be helpful"
+ assert len(api_msgs) == 1
+ assert api_msgs[0]["role"] == "user"
+
+ def test_tool_result_sent_as_user_role(self, provider):
+ msg = Message(role="tool", content="42", tool_call_id="tc_1")
+ result = provider._to_api_message(msg)
+ assert result["role"] == "user"
+ assert result["content"][0]["type"] == "tool_result"
+ assert result["content"][0]["tool_use_id"] == "tc_1"
+
+ def test_tool_def_uses_input_schema(self, provider):
+ td = ToolDef(name="calc", description="Math", parameters={"type": "object"})
+ result = provider._to_api_tool(td)
+ assert result["name"] == "calc"
+ assert result["input_schema"] == {"type": "object"}
+
+ def test_normalize_text_response(self, provider):
+ resp = MagicMock()
+ resp.content = [MagicMock(type="text", text="Hello")]
+ resp.usage = MagicMock(input_tokens=10, output_tokens=5,
+ cache_creation_input_tokens=0, cache_read_input_tokens=0)
+ resp.stop_reason = "end_turn"
+
+ result = provider._normalize(resp, "claude-sonnet-4-6")
+ assert result.content == "Hello"
+ assert result.model == "claude-sonnet-4-6"
+ assert result.usage.input_tokens == 10
+
+ def test_normalize_thinking_response(self, provider):
+ resp = MagicMock()
+ thinking_block = MagicMock(type="thinking", thinking="Let me think...")
+ text_block = MagicMock(type="text", text="Answer")
+ resp.content = [thinking_block, text_block]
+ resp.usage = MagicMock(input_tokens=50, output_tokens=30,
+ cache_creation_input_tokens=0, cache_read_input_tokens=0)
+ resp.stop_reason = "end_turn"
+
+ result = provider._normalize(resp, "claude-sonnet-4-6")
+ assert result.thinking == "Let me think..."
+ assert result.content == "Answer"
+
+ @pytest.mark.asyncio
+ async def test_chat_sets_thinking_params(self, provider):
+ """When thinking enabled, budget_tokens and temperature=1 are set."""
+ mock_resp = MagicMock()
+ mock_resp.content = [MagicMock(type="text", text="ok")]
+ mock_resp.usage = MagicMock(input_tokens=5, output_tokens=2,
+ cache_creation_input_tokens=0, cache_read_input_tokens=0)
+ mock_resp.stop_reason = "end_turn"
+ provider._client.messages.create = AsyncMock(return_value=mock_resp)
+
+ thinking = ThinkingConfig(enabled=True, budget=4096)
+ await provider.chat(
+ [Message(role="user", content="test")],
+ model="claude-sonnet-4-6", thinking=thinking,
+ )
+
+ call_kwargs = provider._client.messages.create.call_args[1]
+ assert call_kwargs["thinking"]["budget_tokens"] == 4096
+ assert call_kwargs["temperature"] == 1
+
+
+# ---------------------------------------------------------------------------
+# OpenAI: message formatting + response normalization
+# ---------------------------------------------------------------------------
+
+class TestOpenAIProvider:
+
+ @pytest.fixture
+ def provider(self):
+ with patch("openai.AsyncOpenAI"):
+ from services.llm.providers.openai import OpenAIProvider
+ return OpenAIProvider("sk-test")
+
+ def test_user_message_format(self, provider):
+ msg = Message(role="user", content="Hi")
+ result = provider._to_api_message(msg)
+ assert result == {"role": "user", "content": "Hi"}
+
+ def test_tool_message_format(self, provider):
+ msg = Message(role="tool", content="42", tool_call_id="tc_1")
+ result = provider._to_api_message(msg)
+ assert result["role"] == "tool"
+ assert result["tool_call_id"] == "tc_1"
+
+ def test_assistant_tool_calls_format(self, provider):
+ tc = ToolCall(id="tc_1", name="calc", args={"x": 1})
+ msg = Message(role="assistant", content="", tool_calls=[tc])
+ result = provider._to_api_message(msg)
+ assert result["role"] == "assistant"
+ assert len(result["tool_calls"]) == 1
+ assert result["tool_calls"][0]["function"]["name"] == "calc"
+ assert json.loads(result["tool_calls"][0]["function"]["arguments"]) == {"x": 1}
+
+ def test_normalize_basic_response(self, provider):
+ choice = MagicMock()
+ choice.message.content = "Hello"
+ choice.message.reasoning_content = None
+ choice.message.tool_calls = None
+ choice.finish_reason = "stop"
+
+ resp = MagicMock()
+ resp.choices = [choice]
+ resp.usage = MagicMock(prompt_tokens=10, completion_tokens=5, total_tokens=15,
+ completion_tokens_details=None)
+
+ result = provider._normalize(resp, "gpt-5.2")
+ assert result.content == "Hello"
+ assert result.thinking is None
+ assert result.usage.input_tokens == 10
+
+ def test_normalize_reasoning_response(self, provider):
+ choice = MagicMock()
+ choice.message.content = "Answer"
+ choice.message.reasoning_content = "Thinking..."
+ choice.message.tool_calls = None
+ choice.finish_reason = "stop"
+
+ resp = MagicMock()
+ resp.choices = [choice]
+ resp.usage = MagicMock(prompt_tokens=10, completion_tokens=5, total_tokens=15,
+ completion_tokens_details=MagicMock(reasoning_tokens=20))
+
+ result = provider._normalize(resp, "o3-mini")
+ assert result.thinking == "Thinking..."
+ assert result.usage.reasoning_tokens == 20
+
+ @pytest.mark.asyncio
+ async def test_chat_reasoning_model_uses_max_completion_tokens(self, provider):
+ mock_resp = MagicMock()
+ mock_resp.choices = [MagicMock(
+ message=MagicMock(content="ok", reasoning_content=None, tool_calls=None),
+ finish_reason="stop"
+ )]
+ mock_resp.usage = MagicMock(prompt_tokens=5, completion_tokens=2, total_tokens=7,
+ completion_tokens_details=None)
+ provider._client.chat.completions.create = AsyncMock(return_value=mock_resp)
+
+ await provider.chat(
+ [Message(role="user", content="test")],
+ model="o3-mini",
+ )
+
+ call_kwargs = provider._client.chat.completions.create.call_args[1]
+ assert "max_completion_tokens" in call_kwargs
+ assert "max_tokens" not in call_kwargs
+
+
+# ---------------------------------------------------------------------------
+# Gemini: message formatting + thinking config
+# ---------------------------------------------------------------------------
+
+class TestGeminiProvider:
+
+ @pytest.fixture
+ def provider(self):
+ with patch("google.genai.Client"):
+ from services.llm.providers.gemini import GeminiProvider
+ return GeminiProvider("key")
+
+ def test_split_system_and_contents(self, provider):
+ msgs = [
+ Message(role="system", content="Be helpful"),
+ Message(role="user", content="Hi"),
+ Message(role="assistant", content="Hello"),
+ ]
+ system, contents = provider._split_system_and_contents(msgs)
+ assert system == "Be helpful"
+ assert len(contents) == 2
+ assert contents[0]["role"] == "user"
+ assert contents[1]["role"] == "model"
+
+ def test_tool_response_format(self, provider):
+ msgs = [
+ Message(role="tool", content="42", name="calc"),
+ ]
+ _, contents = provider._split_system_and_contents(msgs)
+ assert contents[0]["role"] == "function"
+ assert "function_response" in contents[0]["parts"][0]
+
+ def test_normalize_text(self, provider):
+ part = MagicMock(thought=False, function_call=None, text="Hello")
+ candidate = MagicMock()
+ candidate.content.parts = [part]
+ candidate.finish_reason = "STOP"
+
+ resp = MagicMock()
+ resp.candidates = [candidate]
+ resp.usage_metadata = MagicMock(
+ prompt_token_count=10, candidates_token_count=5, total_token_count=15
+ )
+
+ result = provider._normalize(resp, "gemini-2.5-flash")
+ assert result.content == "Hello"
+ assert result.usage.total_tokens == 15
+
+ def test_normalize_thinking_part(self, provider):
+ thinking_part = MagicMock(thought=True, function_call=None, text="Thinking...")
+ text_part = MagicMock(thought=False, function_call=None, text="Answer")
+
+ candidate = MagicMock()
+ candidate.content.parts = [thinking_part, text_part]
+ candidate.finish_reason = "STOP"
+
+ resp = MagicMock()
+ resp.candidates = [candidate]
+ resp.usage_metadata = None
+
+ result = provider._normalize(resp, "gemini-2.5-pro")
+ assert result.thinking == "Thinking..."
+ assert result.content == "Answer"
+
+ @pytest.mark.asyncio
+ async def test_chat_thinking_forwards_to_sdk(self, provider):
+ """Thinking config fields are forwarded to the SDK's ThinkingConfig."""
+ mock_types = MagicMock()
+ mock_resp = MagicMock()
+ mock_resp.candidates = []
+ mock_resp.usage_metadata = None
+ provider._client.aio.models.generate_content = AsyncMock(return_value=mock_resp)
+
+ with patch("google.genai.types", mock_types):
+ thinking = ThinkingConfig(enabled=True, budget=4096, level="high")
+ await provider.chat(
+ [Message(role="user", content="test")],
+ model="gemini-2.5-flash", thinking=thinking,
+ )
+
+ call_kwargs = mock_types.ThinkingConfig.call_args[1]
+ assert call_kwargs["thinking_budget"] == 4096
+ assert call_kwargs["thinking_level"] == "high"
+
+ @pytest.mark.asyncio
+ async def test_chat_no_thinking_when_disabled(self, provider):
+ """No thinking_config when thinking is disabled."""
+ mock_types = MagicMock()
+ mock_resp = MagicMock()
+ mock_resp.candidates = []
+ mock_resp.usage_metadata = None
+ provider._client.aio.models.generate_content = AsyncMock(return_value=mock_resp)
+
+ with patch("google.genai.types", mock_types):
+ await provider.chat(
+ [Message(role="user", content="test")],
+ model="gemini-2.5-flash",
+ )
+
+ mock_types.ThinkingConfig.assert_not_called()
+
+
+# ---------------------------------------------------------------------------
+# OpenRouter: [FREE] prefix handling
+# ---------------------------------------------------------------------------
+
+class TestOpenRouterProvider:
+
+ @pytest.fixture
+ def provider(self):
+ with patch("openai.AsyncOpenAI"):
+ from services.llm.providers.openrouter import OpenRouterProvider
+ return OpenRouterProvider("or-key")
+
+ @pytest.mark.asyncio
+ async def test_strips_free_prefix(self, provider):
+ mock_resp = MagicMock()
+ mock_resp.choices = [MagicMock(
+ message=MagicMock(content="ok", reasoning_content=None, tool_calls=None),
+ finish_reason="stop"
+ )]
+ mock_resp.usage = MagicMock(prompt_tokens=5, completion_tokens=2, total_tokens=7,
+ completion_tokens_details=None)
+ provider._client.chat.completions.create = AsyncMock(return_value=mock_resp)
+
+ await provider.chat(
+ [Message(role="user", content="test")],
+ model="[FREE] meta-llama/llama-3-8b",
+ )
+
+ call_kwargs = provider._client.chat.completions.create.call_args[1]
+ assert call_kwargs["model"] == "meta-llama/llama-3-8b"