devsper 2.1.6__py3-none-any.whl

devsper/providers/router/backends/openai_backend.py

@@ -0,0 +1,142 @@
+"""OpenAI + Azure OpenAI LLM backend (LangChain)."""
+
+import os
+
+from langchain_core.messages import HumanMessage, AIMessage, SystemMessage
+from devsper.providers.router.base import LLMBackend, LLMRequest, LLMResponse
+
+
+def _is_azure_foundry_v1_endpoint(endpoint: str) -> bool:
+    """True if endpoint is Azure Foundry v1 (use ChatOpenAI + base_url, not AzureChatOpenAI)."""
+    if not endpoint:
+        return False
+    e = endpoint.rstrip("/").lower()
+    return "/openai/v1" in e or "cognitiveservices.azure.com" in e
+
+
+def _messages_to_lc(messages: list[dict]) -> list:
+    out = []
+    for m in messages:
+        role = (m.get("role") or "user").lower()
+        content = m.get("content") or ""
+        if role == "user":
+            out.append(HumanMessage(content=content))
+        elif role == "assistant":
+            out.append(AIMessage(content=content))
+        elif role == "system":
+            out.append(SystemMessage(content=content))
+        else:
+            out.append(HumanMessage(content=content))
+    return out
+
+
+class OpenAIBackend(LLMBackend):
+    """OpenAI API and Azure OpenAI. Uses OPENAI_* / AZURE_OPENAI_* env or constructor args."""
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        azure: bool = False,
+        azure_endpoint: str | None = None,
+        azure_deployment: str | None = None,
+        api_version: str | None = None,
+    ) -> None:
+        self.api_key = api_key or os.environ.get("OPENAI_API_KEY")
+        self.azure = azure or bool(
+            os.environ.get("AZURE_OPENAI_ENDPOINT") and os.environ.get("AZURE_OPENAI_API_KEY")
+        )
+        self.azure_endpoint = (azure_endpoint or os.environ.get("AZURE_OPENAI_ENDPOINT", "") or "").strip().rstrip("/")
+        self.azure_deployment = azure_deployment or os.environ.get("AZURE_OPENAI_DEPLOYMENT_NAME", "")
+        self.api_version = api_version or os.environ.get("AZURE_OPENAI_API_VERSION", "2024-05-01-preview")
+        if self.azure and not self.api_key:
+            self.api_key = os.environ.get("AZURE_OPENAI_API_KEY")
+        self._azure_foundry = _is_azure_foundry_v1_endpoint(self.azure_endpoint)
+        self._llm_cache: dict[str, object] = {}
+
+    @property
+    def name(self) -> str:
+        return "openai"
+
+    def _get_llm(self, model: str):
+        key = model or (self.azure_deployment if self.azure else "gpt-4o")
+        if key in self._llm_cache:
+            return self._llm_cache[key]
+        if self.azure:
+            dep = model or self.azure_deployment or "gpt-4o"
+            if self._azure_foundry:
+                from langchain_openai import ChatOpenAI
+                base = self.azure_endpoint if self.azure_endpoint.endswith("/") else self.azure_endpoint + "/"
+                llm = ChatOpenAI(
+                    base_url=base,
+                    api_key=self.api_key,
+                    model=dep,
+                    temperature=0,
+                )
+            else:
+                from langchain_openai import AzureChatOpenAI
+                llm = AzureChatOpenAI(
+                    azure_endpoint=self.azure_endpoint,
+                    azure_deployment=dep,
+                    openai_api_key=self.api_key,
+                    api_version=self.api_version,
+                    temperature=0,
+                )
+        else:
+            from langchain_openai import ChatOpenAI
+            llm = ChatOpenAI(
+                model=model or "gpt-4o",
+                api_key=self.api_key,
+                temperature=0,
+            )
+        self._llm_cache[key] = llm
+        return llm
+
+    def supports_model(self, model_name: str) -> bool:
+        m = (model_name or "").strip().lower()
+        if self.azure:
+            return True
+        return m.startswith("gpt") or m.startswith("o1") or m.startswith("o3") or m.startswith("o4")
+
+    async def complete(self, request: LLMRequest) -> LLMResponse:
+        model = request.model or (self.azure_deployment if self.azure else "gpt-4o")
+        llm = self._get_llm(model)
+        lc_messages = _messages_to_lc(request.messages)
+        msg = await llm.ainvoke(lc_messages)
+        content = msg.content if isinstance(msg.content, str) else str(msg.content or "")
+        usage = {}
+        if hasattr(msg, "response_metadata") and msg.response_metadata:
+            meta = msg.response_metadata.get("usage", {}) or msg.response_metadata
+            usage = {
+                "prompt_tokens": meta.get("prompt_tokens", meta.get("input_tokens", 0)),
+                "completion_tokens": meta.get("completion_tokens", meta.get("output_tokens", 0)),
+                "total_tokens": meta.get("total_tokens", 0),
+            }
+        return LLMResponse(
+            content=content,
+            model=model,
+            usage=usage,
+            finish_reason="stop",
+            backend=self.name,
+        )
+
+    async def stream(self, request: LLMRequest):
+        model = request.model or (self.azure_deployment if self.azure else "gpt-4o")
+        llm = self._get_llm(model)
+        lc_messages = _messages_to_lc(request.messages)
+        async for chunk in llm.astream(lc_messages):
+            if hasattr(chunk, "content") and chunk.content:
+                yield chunk.content
+
+    async def health(self) -> bool:
+        try:
+            await self.complete(
+                LLMRequest(
+                    model="gpt-4o-mini" if not self.azure else (self.azure_deployment or "gpt-4o"),
+                    messages=[{"role": "user", "content": "Hi"}],
+                    max_tokens=2,
+                )
+            )
+            return True
+        except Exception:
+            return False

devsper/providers/router/backends/vllm_backend.py

@@ -0,0 +1,35 @@
+"""vLLM backend (OpenAI-compatible endpoint)."""
+
+from devsper.providers.router.base import LLMBackend, LLMRequest, LLMResponse
+from devsper.providers.router.backends.custom_backend import CustomBackend
+
+
+class VLLMBackend(LLMBackend):
+    """vLLM server: OpenAI-compatible API with configurable base_url."""
+
+    def __init__(self, base_url: str = "http://localhost:8000", api_key: str = "") -> None:
+        self._custom = CustomBackend(base_url=base_url, api_key=api_key or None, model_prefix_strip=None)
+
+    @property
+    def name(self) -> str:
+        return "vllm"
+
+    def supports_model(self, model_name: str) -> bool:
+        return True
+
+    async def complete(self, request: LLMRequest) -> LLMResponse:
+        resp = await self._custom.complete(request)
+        return LLMResponse(
+            content=resp.content,
+            model=resp.model,
+            usage=resp.usage,
+            finish_reason=resp.finish_reason,
+            backend=self.name,
+        )
+
+    async def stream(self, request: LLMRequest):
+        async for chunk in self._custom.stream(request):
+            yield chunk
+
+    async def health(self) -> bool:
+        return await self._custom.health()

devsper/providers/router/base.py

@@ -0,0 +1,60 @@
+"""
+Abstract LLM router types (v2.0).
+
+LLMBackend: abstract backend interface.
+LLMRequest / LLMResponse: unified request/response for all backends.
+"""
+
+from abc import ABC, abstractmethod
+from collections.abc import AsyncIterator
+from dataclasses import dataclass
+
+
+@dataclass
+class LLMRequest:
+    """Unified request for any LLM backend."""
+    model: str
+    messages: list[dict]
+    max_tokens: int = 4096
+    temperature: float = 0.0
+    tools: list[dict] | None = None
+    stream: bool = False
+
+
+@dataclass
+class LLMResponse:
+    """Unified response from any LLM backend."""
+    content: str
+    model: str
+    usage: dict  # prompt_tokens, completion_tokens, total_tokens
+    finish_reason: str
+    backend: str
+
+
+class LLMBackend(ABC):
+    """Abstract backend for LLM completion. All providers implement this."""
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Backend identifier (e.g. 'openai', 'ollama')."""
+        ...
+
+    @abstractmethod
+    async def complete(self, request: LLMRequest) -> LLMResponse:
+        """Non-streaming completion."""
+        ...
+
+    @abstractmethod
+    async def stream(self, request: LLMRequest) -> AsyncIterator[str]:
+        """Streaming completion; yield content chunks."""
+        ...
+
+    @abstractmethod
+    async def health(self) -> bool:
+        """Return True if backend is reachable and usable."""
+        ...
+
+    def supports_model(self, model_name: str) -> bool:
+        """Return True if this backend can serve the given model (bare name, no prefix)."""
+        return False

devsper/providers/router/factory.py

@@ -0,0 +1,92 @@
+"""Build LLMRouter from config and register backends."""
+
+from devsper.config import get_config
+from devsper.providers.router.router import LLMRouter
+from devsper.providers.router.backends.openai_backend import OpenAIBackend
+from devsper.providers.router.backends.anthropic_backend import AnthropicBackend
+from devsper.providers.router.backends.gemini_backend import GeminiBackend
+from devsper.providers.router.backends.github_backend import GitHubBackend
+from devsper.providers.router.backends.ollama_backend import OllamaBackend
+from devsper.providers.router.backends.vllm_backend import VLLMBackend
+from devsper.providers.router.backends.custom_backend import CustomBackend
+
+_router_instance: LLMRouter | None = None
+
+
+def _emit_fallback(payload: dict) -> None:
+    try:
+        from devsper.types.event import Event, events
+        from devsper.utils.event_logger import EventLog
+        from datetime import datetime, timezone
+        from devsper.config import get_config
+        log = EventLog(events_folder_path=get_config().events_dir)
+        log.append_event(
+            Event(timestamp=datetime.now(timezone.utc), type=events.PROVIDER_FALLBACK, payload=payload)
+        )
+    except Exception:
+        pass
+
+
+def get_llm_router() -> LLMRouter | None:
+    """Build and return the v2 LLMRouter from config. Cached. Returns None if not configured."""
+    global _router_instance
+    if _router_instance is not None:
+        return _router_instance
+    try:
+        cfg = get_config()
+        pc = cfg.providers
+    except Exception:
+        return None
+    fallback_order = getattr(pc, "fallback_order", None) or []
+    router = LLMRouter(
+        fallback_order=fallback_order,
+        max_fallbacks=2,
+        on_fallback=_emit_fallback,
+    )
+    # Register standard backends when env/config allows
+    import os
+    if os.environ.get("OPENAI_API_KEY") or (os.environ.get("AZURE_OPENAI_ENDPOINT") and os.environ.get("AZURE_OPENAI_API_KEY")):
+        try:
+            router.register(OpenAIBackend())
+        except Exception:
+            pass
+    if os.environ.get("ANTHROPIC_API_KEY") or os.environ.get("AZURE_ANTHROPIC_API_KEY") or os.environ.get("AZURE_ANTHROPIC_ENDPOINT"):
+        try:
+            router.register(AnthropicBackend())
+        except Exception:
+            pass
+    if os.environ.get("GOOGLE_API_KEY") or os.environ.get("GEMINI_API_KEY"):
+        try:
+            router.register(GeminiBackend())
+        except Exception:
+            pass
+    if os.environ.get("GITHUB_TOKEN"):
+        try:
+            router.register(GitHubBackend())
+        except Exception:
+            pass
+    if getattr(pc, "ollama", None) and getattr(pc.ollama, "enabled", False):
+        try:
+            router.register(OllamaBackend(base_url=pc.ollama.base_url or "http://localhost:11434"))
+        except Exception:
+            pass
+    if getattr(pc, "vllm", None) and getattr(pc.vllm, "enabled", False):
+        try:
+            router.register(VLLMBackend(base_url=pc.vllm.base_url or "http://localhost:8000", api_key=pc.vllm.api_key or ""))
+        except Exception:
+            pass
+    if getattr(pc, "custom", None) and getattr(pc.custom, "enabled", False) and getattr(pc.custom, "base_url", ""):
+        try:
+            router.register(
+                CustomBackend(
+                    base_url=pc.custom.base_url,
+                    api_key=pc.custom.api_key or None,
+                    model_prefix_strip=pc.custom.model_prefix_strip or None,
+                )
+            )
+        except Exception:
+            pass
+    if not router._backends:
+        return None
+    _router_instance = router
+    return _router_instance

devsper/providers/router/legacy.py

@@ -0,0 +1,101 @@
+"""
+Legacy provider router: map model name → provider instance.
+
+Agent and planner call generate(model, prompt) in utils.models;
+utils.models uses the router to get the right provider (or v2 LLMRouter when available).
+
+When AZURE_OPENAI_ENDPOINT is set, GPT models use Azure OpenAI (model name = deployment name).
+When AZURE_ANTHROPIC_ENDPOINT (or AZURE_ANTHROPIC_API_KEY) is set, Claude models use Azure Foundry.
+"""
+
+import os
+
+from dotenv import load_dotenv
+
+from devsper.providers.base import BaseProvider, MockProvider
+from devsper.providers.openai import OpenAIProvider
+from devsper.providers.anthropic import AnthropicProvider
+from devsper.providers.gemini import GeminiProvider
+from devsper.providers.github import GitHubProvider
+
+load_dotenv()
+
+# Provider prefix in model spec (provider:model)
+PROVIDERS = {
+    "openai": OpenAIProvider,
+    "anthropic": AnthropicProvider,
+    "azure": OpenAIProvider,  # Azure OpenAI uses OpenAIProvider with azure=True
+    "gemini": GeminiProvider,
+    "github": GitHubProvider,
+}
+
+
+def _parse_model_spec(model: str) -> tuple[str, str]:
+    """Return (vendor, model_name). If 'provider:model' format, vendor is provider; else infer from name."""
+    m = (model or "").strip()
+    if ":" in m:
+        vendor, name = m.split(":", 1)
+        return vendor.strip().lower(), name.strip()
+    return _model_to_vendor(m), m
+
+
+def _model_to_vendor(model: str) -> str:
+    """Return 'openai' | 'anthropic' | 'gemini' | 'github' | 'mock' from model name (no prefix)."""
+    m = (model or "").strip().lower()
+    if m in ("mock", "default", ""):
+        return "mock"
+    if m.startswith("gpt") or m.startswith("o1") or m.startswith("o3") or m.startswith("o4"):
+        return "openai"
+    if m.startswith("claude"):
+        return "anthropic"
+    if m.startswith("gemini"):
+        return "gemini"
+    return "mock"
+
+
+def _use_azure_openai() -> bool:
+    """True when Azure OpenAI env vars are set (endpoint + key)."""
+    return bool(os.environ.get("AZURE_OPENAI_ENDPOINT") and os.environ.get("AZURE_OPENAI_API_KEY"))
+
+
+class ProviderRouter:
+    """Maps model name (or provider:model) to provider. Caches one instance per vendor."""
+
+    def __init__(self) -> None:
+        self._openai: OpenAIProvider | None = None
+        self._anthropic: AnthropicProvider | None = None
+        self._gemini: GeminiProvider | None = None
+        self._github: GitHubProvider | None = None
+        self._mock = MockProvider()
+
+    def get_provider(self, model_name: str) -> BaseProvider:
+        """Return the provider that should handle this model name (supports provider:model)."""
+        vendor, _ = _parse_model_spec(model_name)
+        if vendor == "openai" or vendor == "azure":
+            if self._openai is None:
+                self._openai = OpenAIProvider(azure=_use_azure_openai())
+            return self._openai
+        if vendor == "anthropic":
+            if self._anthropic is None:
+                self._anthropic = AnthropicProvider()
+            return self._anthropic
+        if vendor == "gemini":
+            if self._gemini is None:
+                self._gemini = GeminiProvider()
+            return self._gemini
+        if vendor == "github":
+            if self._github is None:
+                self._github = GitHubProvider()
+            return self._github
+        return self._mock
+
+
+_router: ProviderRouter | None = None
+
+
+def get_router() -> ProviderRouter:
+    """Return the global router (singleton)."""
+    global _router
+    if _router is None:
+        _router = ProviderRouter()
+    return _router

devsper/providers/router/router.py

@@ -0,0 +1,135 @@
+"""
+LLMRouter: routes requests by model string (provider:model or bare name), with optional fallback.
+"""
+
+from collections.abc import AsyncIterator, Callable
+
+from devsper.providers.router.base import LLMBackend, LLMRequest, LLMResponse
+
+# Event type for fallback (caller can emit to event bus)
+PROVIDER_FALLBACK_EVENT = "provider_fallback"
+
+
+def _parse_model_spec(model: str) -> tuple[str | None, str]:
+    """Return (prefix, model_name). prefix is None if no 'provider:' prefix."""
+    m = (model or "").strip()
+    if ":" in m:
+        prefix, name = m.split(":", 1)
+        return prefix.strip().lower(), name.strip()
+    return None, m
+
+
+class LLMRouter:
+    """
+    Holds registered LLMBackend instances. Routes by model string:
+    - "ollama:llama3" -> OllamaBackend, model="llama3"
+    - "vllm:mistral-7b" -> VLLMBackend, model="mistral-7b"
+    - "openai:gpt-4o" -> OpenAIBackend
+    - bare "gpt-4o" -> first backend where supports_model("gpt-4o") is True
+    """
+
+    def __init__(
+        self,
+        fallback_order: list[str] | None = None,
+        max_fallbacks: int = 2,
+        on_fallback: Callable[[dict], None] | None = None,
+    ) -> None:
+        self._backends: list[LLMBackend] = []
+        self._by_name: dict[str, LLMBackend] = {}
+        self.fallback_order = fallback_order or []
+        self.max_fallbacks = max(0, max_fallbacks)
+        self.on_fallback = on_fallback
+
+    def register(self, backend: LLMBackend) -> None:
+        """Register a backend. Name must be unique."""
+        if backend.name in self._by_name:
+            return
+        self._backends.append(backend)
+        self._by_name[backend.name] = backend
+
+    def _backend_for_prefix(self, prefix: str) -> LLMBackend | None:
+        return self._by_name.get(prefix)
+
+    async def _backend_for_bare_model(self, model_name: str) -> LLMBackend | None:
+        """First registered backend that supports the bare model name."""
+        for b in self._backends:
+            if b.supports_model(model_name):
+                return b
+        return None
+
+    def _order_for_fallback(self, primary_name: str) -> list[LLMBackend]:
+        """Backends to try after primary, in fallback_order order."""
+        seen = {primary_name}
+        out = []
+        for name in self.fallback_order:
+            if name not in seen and name in self._by_name:
+                seen.add(name)
+                out.append(self._by_name[name])
+        return out
+
+    async def route(self, request: LLMRequest) -> LLMResponse:
+        """Route request to the appropriate backend. On failure, try fallback chain."""
+        prefix, model_name = _parse_model_spec(request.model)
+        primary: LLMBackend | None = None
+        if prefix is not None:
+            primary = self._backend_for_prefix(prefix)
+            if primary is not None:
+                req = LLMRequest(
+                    model=model_name,
+                    messages=request.messages,
+                    max_tokens=request.max_tokens,
+                    temperature=request.temperature,
+                    tools=request.tools,
+                    stream=False,
+                )
+            else:
+                primary = await self._backend_for_bare_model(request.model)
+                req = request
+        else:
+            primary = await self._backend_for_bare_model(model_name or request.model)
+            req = request
+
+        if primary is None:
+            raise ValueError(f"No backend for model: {request.model}")
+
+        fallbacks = self._order_for_fallback(primary.name)[: self.max_fallbacks]
+        last_error = None
+        for backend in [primary] + fallbacks:
+            try:
+                if backend is not primary and self.on_fallback:
+                    self.on_fallback({
+                        "original_backend": primary.name,
+                        "fallback_backend": backend.name,
+                        "reason": str(last_error) if last_error else "unknown",
+                    })
+                resp = await backend.complete(req)
+                return resp
+            except Exception as e:
+                last_error = e
+                continue
+        if last_error:
+            raise last_error
+        raise ValueError(f"No backend could complete request for model: {request.model}")
+
+    async def route_stream(self, request: LLMRequest) -> AsyncIterator[str]:
+        """Route streaming request. Fallback not applied to stream (use complete for retries)."""
+        prefix, model_name = _parse_model_spec(request.model)
+        backend: LLMBackend | None = None
+        req = request
+        if prefix is not None:
+            backend = self._backend_for_prefix(prefix)
+            if backend is not None:
+                req = LLMRequest(
+                    model=model_name,
+                    messages=request.messages,
+                    max_tokens=request.max_tokens,
+                    temperature=request.temperature,
+                    tools=request.tools,
+                    stream=True,
+                )
+        if backend is None:
+            backend = await self._backend_for_bare_model(model_name or request.model)
+        if backend is None:
+            raise ValueError(f"No backend for model: {request.model}")
+        async for chunk in backend.stream(req):
+            yield chunk

devsper/reasoning/__init__.py

@@ -0,0 +1,12 @@
+"""
+Multi-agent reasoning graph: store and query intermediate reasoning artifacts.
+
+Agents write ReasoningNode entries after completing steps; subsequent agents
+can query the graph for context via ReasoningStore.
+"""
+
+from devsper.reasoning.nodes import ReasoningNode
+from devsper.reasoning.graph import ReasoningGraph
+from devsper.reasoning.store import ReasoningStore
+
+__all__ = ["ReasoningNode", "ReasoningGraph", "ReasoningStore"]

devsper/reasoning/graph.py

@@ -0,0 +1,59 @@
+"""
+Reasoning graph: DAG of reasoning nodes with add_node, query_nodes, get_dependencies.
+"""
+
+import networkx as nx
+
+from devsper.reasoning.nodes import ReasoningNode
+
+
+class ReasoningGraph:
+    """DAG of reasoning nodes. Supports add_node, query_nodes, get_dependencies."""
+
+    def __init__(self) -> None:
+        self._graph: nx.DiGraph = nx.DiGraph()
+        self._nodes: dict[str, ReasoningNode] = {}
+
+    def add_node(self, node: ReasoningNode) -> None:
+        """Add a reasoning node and its dependency edges."""
+        self._nodes[node.id] = node
+        self._graph.add_node(node.id)
+        for dep_id in node.dependencies:
+            if dep_id in self._nodes:
+                self._graph.add_edge(dep_id, node.id)
+
+    def query_nodes(
+        self,
+        *,
+        agent_id: str | None = None,
+        task_id: str | None = None,
+        limit: int = 100,
+    ) -> list[ReasoningNode]:
+        """Return nodes matching optional agent_id and/or task_id, most recent first."""
+        out: list[ReasoningNode] = []
+        for n in self._nodes.values():
+            if agent_id is not None and n.agent_id != agent_id:
+                continue
+            if task_id is not None and n.task_id != task_id:
+                continue
+            out.append(n)
+        out.sort(key=lambda x: x.timestamp, reverse=True)
+        return out[:limit]
+
+    def get_dependencies(self, node_id: str) -> list[ReasoningNode]:
+        """Return all reasoning nodes that the given node depends on."""
+        if node_id not in self._nodes:
+            return []
+        pred_ids = list(self._graph.predecessors(node_id))
+        return [self._nodes[pid] for pid in pred_ids if pid in self._nodes]
+
+    def get_node(self, node_id: str) -> ReasoningNode | None:
+        """Return the reasoning node with the given id, or None."""
+        return self._nodes.get(node_id)
+
+    def get_successors(self, node_id: str) -> list[ReasoningNode]:
+        """Return nodes that depend on the given node."""
+        if node_id not in self._nodes:
+            return []
+        succ_ids = list(self._graph.successors(node_id))
+        return [self._nodes[sid] for sid in succ_ids if sid in self._nodes]

devsper/reasoning/nodes.py

@@ -0,0 +1,20 @@
+"""
+Reasoning node: single artifact produced by an agent during a step.
+"""
+
+from datetime import datetime, timezone
+from pydantic import BaseModel, Field
+
+
+class ReasoningNode(BaseModel):
+    """A single reasoning artifact produced by an agent."""
+
+    id: str
+    agent_id: str = ""
+    task_id: str = ""
+    content: str = ""
+    timestamp: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+    dependencies: list[str] = Field(default_factory=list)
+
+    def __hash__(self) -> int:
+        return hash(self.id)