devsper 2.1.6__py3-none-any.whl

devsper/providers/base.py

@@ -0,0 +1,75 @@
+"""
+Provider base interface.
+
+All providers implement generate(model, prompt, stream=False).
+When stream=True, yield chunks; when stream=False, return full text.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Iterator
+
+
+class BaseProvider(ABC):
+    """Common interface for OpenAI, Anthropic, Gemini, GitHub, and mock."""
+
+    @abstractmethod
+    def generate(self, model: str, prompt: str, stream: bool = False) -> str | Iterator[str]:
+        """Return model output (str or iterator of chunks when stream=True)."""
+        ...
+
+
+def _ensure_str(result) -> str:
+    """If result is an iterator (stream=True), consume and return concatenated string."""
+    if hasattr(result, "__iter__") and not isinstance(result, str):
+        return "".join(result)
+    return result if isinstance(result, str) else str(result)
+
+
+def _mock_planner_response(prompt: str) -> str:
+    """Return a valid numbered list so the planner can parse subtasks when no API key is set."""
+    if "Break the following task into" in prompt or "smaller steps" in prompt:
+        task_part = "Summarize the topic"  # fallback
+        if "Task:" in prompt:
+            start = prompt.find("Task:") + 5
+            end = prompt.find("\n", start) if "\n" in prompt[start:] else len(prompt)
+            task_part = prompt[start:end].strip()[:80]
+        return (
+            f"1. Define and scope the topic: {task_part}\n"
+            "2. Gather key points and examples\n"
+            "3. Synthesize into a clear summary\n"
+            "4. Add one or two concrete details\n"
+            "5. Polish into a single paragraph"
+        )
+    return f"Completed: {prompt[:200]}{'...' if len(prompt) > 200 else ''}"
+
+
+def _mock_agent_response(prompt: str) -> str:
+    """Return a short on-topic stub for agent tasks so demo output is coherent."""
+    if "Task:" in prompt:
+        task_start = prompt.find("Task:") + 5
+        rest = prompt[task_start:].strip()
+        first_line = rest.split("\n")[0].strip()[:100]
+        return (
+            f"[Mock] Summary for: {first_line}\n\n"
+            "Swarm intelligence is collective behavior that emerges from many simple agents "
+            "following local rules (e.g. ants, bees, flocks). No central controller is needed; "
+            "coordination arises from stigmergy, feedback, and self-organization."
+        )
+    return f"Completed: {prompt[:200]}{'...' if len(prompt) > 200 else ''}"
+
+
+class MockProvider(BaseProvider):
+    """In-memory provider for tests and default stub. No API key required."""
+
+    def generate(self, model: str, prompt: str, stream: bool = False) -> str | Iterator[str]:
+        if "Break the following task" in prompt or "5 smaller steps" in prompt:
+            text = _mock_planner_response(prompt)
+        elif "You are an AI worker" in prompt or "Task:" in prompt:
+            text = _mock_agent_response(prompt)
+        else:
+            text = f"Completed: {prompt[:200]}{'...' if len(prompt) > 200 else ''}"
+        if stream:
+            def _gen() -> Iterator[str]:
+                yield text
+            return _gen()
+        return text

devsper/providers/complexity_router.py

@@ -0,0 +1,94 @@
+"""
+v1.6: Route tasks to simple/medium/complex tiers and select model (fast / worker / quality).
+"""
+
+from typing import Any, Literal
+
+from devsper.types.task import Task
+
+
+TIERS: dict[str, dict[str, Any]] = {
+    "simple": {
+        "max_tools": 2,
+        "max_tokens_est": 500,
+        "roles": ["summarize", "extract", "format"],
+    },
+    "medium": {
+        "max_tools": 5,
+        "max_tokens_est": 2000,
+        "roles": ["research", "analysis", "code"],
+    },
+    "complex": {
+        "max_tools": 99,
+        "max_tokens_est": 99999,
+        "roles": ["architect", "critic", "experiment"],
+    },
+}
+
+
+class TaskComplexityRouter:
+    """Classify task complexity and select model tier (simple → fast, medium → worker, complex → quality)."""
+
+    TIERS = TIERS
+
+    def classify(self, task: Task, tools_selected: list[Any]) -> Literal["simple", "medium", "complex"]:
+        """
+        Score task complexity:
+        - Role → base tier (simple/medium/complex from TIERS)
+        - Tool count → upgrade tier if tools_selected > threshold
+        - Description length → upgrade if > 200 words
+        - Dependencies count → upgrade if task.dependencies > 3
+        - Speculative flag → downgrade one tier
+        Return final tier.
+        """
+        base = "medium"
+        role = (getattr(task, "role", None) or "").lower()
+        for tier, cfg in TIERS.items():
+            if role in [r.lower() for r in cfg["roles"]]:
+                base = tier
+                break
+
+        tier = base
+        n_tools = len(tools_selected) if tools_selected else 0
+        if n_tools > TIERS["simple"]["max_tools"] and tier == "simple":
+            tier = "medium"
+        if n_tools > TIERS["medium"]["max_tools"] and tier == "medium":
+            tier = "complex"
+
+        words = len((task.description or "").split())
+        if words > 200 and tier == "simple":
+            tier = "medium"
+        if words > 200 and tier == "medium":
+            tier = "complex"
+
+        deps = len(task.dependencies) if task.dependencies else 0
+        if deps > 3 and tier == "simple":
+            tier = "medium"
+        if deps > 3 and tier == "medium":
+            tier = "complex"
+
+        if getattr(task, "speculative", False):
+            if tier == "complex":
+                tier = "medium"
+            elif tier == "medium":
+                tier = "simple"
+
+        return tier
+
+    def select_model(self, tier: str, config: Any) -> str:
+        """
+        simple  → config.fast_model (or config.fast) — default: worker if not set
+        medium  → config.worker_model (or config.worker)
+        complex → config.quality_model (or config.quality) — default: planner
+        If model not configured: fall back to config.worker for all tiers.
+        """
+        worker = getattr(config, "worker", None) or getattr(config, "worker_model", "mock")
+        planner = getattr(config, "planner", None) or getattr(config, "planner_model", "mock")
+        fast = getattr(config, "fast", None)
+        quality = getattr(config, "quality", None) or planner
+
+        if tier == "simple":
+            return fast if fast else worker
+        if tier == "complex":
+            return quality
+        return worker

devsper/providers/gemini.py

@@ -0,0 +1,36 @@
+"""Google Gemini provider adapter using LangChain."""
+
+import os
+from typing import Iterator
+
+from langchain_core.messages import HumanMessage
+from langchain_google_genai import ChatGoogleGenerativeAI
+
+from devsper.providers.base import BaseProvider
+
+
+class GeminiProvider(BaseProvider):
+    """Google Gemini API adapter. Uses GOOGLE_API_KEY or GEMINI_API_KEY (or pass api_key)."""
+
+    def __init__(self, api_key: str | None = None) -> None:
+        self.api_key = api_key or os.environ.get("GOOGLE_API_KEY") or os.environ.get(
+            "GEMINI_API_KEY"
+        )
+        if not self.api_key:
+            raise ValueError("Gemini requires api_key or GOOGLE_API_KEY or GEMINI_API_KEY")
+
+    def generate(self, model: str, prompt: str, stream: bool = False) -> str | Iterator[str]:
+        """Call Gemini API and return the model output text."""
+        llm = ChatGoogleGenerativeAI(
+            model=model,
+            google_api_key=self.api_key,
+            temperature=0,
+        )
+        message = llm.invoke([HumanMessage(content=prompt)])
+        content = message.content
+        text = content if isinstance(content, str) else str(content)
+        if stream:
+            def _gen():
+                yield text
+            return _gen()
+        return text

devsper/providers/github.py

@@ -0,0 +1,180 @@
+"""GitHub Models provider (GitHub Models API at models.github.ai)."""
+
+import json
+import logging
+import os
+import time
+from typing import Iterator
+
+import httpx
+
+from devsper.providers.base import BaseProvider
+
+log = logging.getLogger(__name__)
+
+# Retry 429 (rate limit): max attempts, base delay in seconds, max delay cap
+GITHUB_429_MAX_RETRIES = 3
+GITHUB_429_BASE_DELAY = 1.0
+GITHUB_429_MAX_DELAY = 32.0
+
+# GitHub Models API (replaces deprecated models.inference.ai.azure.com)
+# Docs: https://docs.github.com/en/rest/models/inference
+GITHUB_MODELS_BASE = "https://models.github.ai"
+GITHUB_MODELS_CHAT_URL = f"{GITHUB_MODELS_BASE}/inference/chat/completions"
+GITHUB_API_VERSION = "2022-11-28"
+
+# Default model when user selects "copilot" or "github:copilot" (publisher/model format)
+DEFAULT_GITHUB_MODEL = "openai/gpt-4.1"
+
+
+def _normalize_model_id(model: str) -> str:
+    """Return API model ID: publisher/name. 'copilot' or 'github:copilot' -> default; else strip github: prefix."""
+    s = model.split(":", 1)[-1].strip() if ":" in model else model.strip()
+    if not s or s.lower() == "copilot":
+        return DEFAULT_GITHUB_MODEL
+    return s
+
+
+class GitHubProvider(BaseProvider):
+    """
+    GitHub Models API adapter (models.github.ai).
+    Uses GITHUB_TOKEN with models:read scope (fine-grained PAT or classic).
+    """
+
+    def __init__(self, token: str | None = None) -> None:
+        self.token = token or os.environ.get("GITHUB_TOKEN")
+        if not self.token:
+            raise ValueError("GitHub provider requires GITHUB_TOKEN")
+
+    def _headers(self) -> dict[str, str]:
+        return {
+            "Accept": "application/vnd.github.v3+json",
+            "Content-Type": "application/json",
+            "Authorization": f"Bearer {self.token}",
+            "X-GitHub-Api-Version": GITHUB_API_VERSION,
+        }
+
+    def generate(
+        self, model: str, prompt: str, stream: bool = False
+    ) -> str | Iterator[str]:
+        """Call GitHub Models inference/chat/completions and return the assistant message content."""
+        api_model = _normalize_model_id(model)
+        if stream:
+            return self._generate_stream(api_model, prompt)
+        return self._generate_sync(api_model, prompt)
+
+    def _generate_sync(self, model: str, prompt: str) -> str:
+        payload = {
+            "model": model,
+            "messages": [{"role": "user", "content": prompt}],
+            "temperature": 0.2,
+        }
+        data = {}
+        from devsper.utils.http import ssl_verify, format_retry_after
+        with httpx.Client(timeout=60.0, verify=ssl_verify()) as client:
+            for attempt in range(GITHUB_429_MAX_RETRIES):
+                try:
+                    resp = client.post(
+                        GITHUB_MODELS_CHAT_URL,
+                        headers=self._headers(),
+                        json=payload,
+                    )
+                    resp.raise_for_status()
+                    data = resp.json()
+                    break
+                except httpx.HTTPStatusError as e:
+                    retry_hint = format_retry_after(e.response)
+                    if e.response.status_code == 429 and attempt < GITHUB_429_MAX_RETRIES - 1:
+                        delay = min(
+                            GITHUB_429_BASE_DELAY * (2**attempt),
+                            GITHUB_429_MAX_DELAY,
+                        )
+                        log.warning(
+                            "GitHub Models 429 rate limit, retry %s/%s in %.1fs%s",
+                            attempt + 1,
+                            GITHUB_429_MAX_RETRIES,
+                            delay,
+                            retry_hint,
+                        )
+                        time.sleep(delay)
+                    else:
+                        if retry_hint:
+                            raise httpx.HTTPStatusError(
+                                str(e) + retry_hint, request=e.request, response=e.response
+                            ) from e
+                        raise
+                choices = data.get("choices") or []
+        if not choices:
+            return ""
+        msg = choices[0].get("message") or {}
+        content = msg.get("content")
+        if isinstance(content, str):
+            return content
+        if isinstance(content, list):
+            # OpenAI-style content parts: [{"type": "text", "text": "..."}]
+            parts = []
+            for part in content:
+                if isinstance(part, dict) and part.get("type") == "text":
+                    t = part.get("text")
+                    if isinstance(t, str):
+                        parts.append(t)
+            return "\n".join(parts) if parts else ""
+        return str(content or "") if content is not None else ""
+
+    def _generate_stream(self, model: str, prompt: str) -> Iterator[str]:
+        payload = {
+            "model": model,
+            "messages": [{"role": "user", "content": prompt}],
+            "temperature": 0.2,
+            "stream": True,
+        }
+        from devsper.utils.http import ssl_verify, format_retry_after
+        with httpx.Client(timeout=60.0, verify=ssl_verify()) as client:
+            for attempt in range(GITHUB_429_MAX_RETRIES):
+                try:
+                    with client.stream(
+                        "POST",
+                        GITHUB_MODELS_CHAT_URL,
+                        headers=self._headers(),
+                        json=payload,
+                    ) as resp:
+                        resp.raise_for_status()
+                        for line in resp.iter_lines():
+                            if not line or not line.strip():
+                                continue
+                            if line.startswith("data: "):
+                                chunk = line[6:].strip()
+                                if chunk == "[DONE]":
+                                    return
+                                try:
+                                    data = json.loads(chunk)
+                                    choices = data.get("choices") or []
+                                    if choices:
+                                        delta = choices[0].get("delta") or {}
+                                        part = delta.get("content")
+                                        if part:
+                                            yield part
+                                except Exception:
+                                    pass
+                    return
+                except httpx.HTTPStatusError as e:
+                    retry_hint = format_retry_after(e.response)
+                    if e.response.status_code == 429 and attempt < GITHUB_429_MAX_RETRIES - 1:
+                        delay = min(
+                            GITHUB_429_BASE_DELAY * (2**attempt),
+                            GITHUB_429_MAX_DELAY,
+                        )
+                        log.warning(
+                            "GitHub Models 429 rate limit (stream), retry %s/%s in %.1fs%s",
+                            attempt + 1,
+                            GITHUB_429_MAX_RETRIES,
+                            delay,
+                            retry_hint,
+                        )
+                        time.sleep(delay)
+                    else:
+                        if retry_hint:
+                            raise httpx.HTTPStatusError(
+                                str(e) + retry_hint, request=e.request, response=e.response
+                            ) from e
+                        raise

devsper/providers/model_router.py

@@ -0,0 +1,40 @@
+"""
+Automatic model routing by cost, latency, and quality tier.
+
+Use select_model(task_type) to get the best model for a given task type.
+"""
+
+from typing import Literal
+
+TaskType = Literal["planning", "analysis", "summarization", "code", "fast"]
+
+# cost: relative cost per request, latency: relative latency tier, quality: 1-5
+MODEL_REGISTRY: dict[str, dict[str, float]] = {
+    "gpt-4o": {"cost": 0.01, "latency": 2, "quality": 5},
+    "gpt-4o-mini": {"cost": 0.002, "latency": 1, "quality": 3},
+    "claude-3.5-sonnet": {"cost": 0.008, "latency": 2, "quality": 5},
+    "phi-3": {"cost": 0.001, "latency": 1, "quality": 2},
+}
+
+
+def select_model(task_type: TaskType) -> str:
+    """
+    Select the best model for the given task type.
+
+    - planning → high quality (claude-3.5-sonnet)
+    - analysis → balanced (gpt-4o)
+    - summarization → balanced (gpt-4o)
+    - code → balanced (gpt-4o)
+    - fast → cheapest / low latency (gpt-4o-mini)
+    """
+    if task_type == "planning":
+        return "claude-3.5-sonnet"
+    if task_type == "analysis":
+        return "gpt-4o"
+    if task_type == "summarization":
+        return "gpt-4o"
+    if task_type == "code":
+        return "gpt-4o"
+    if task_type == "fast":
+        return "gpt-4o-mini"
+    return "gpt-4o-mini"

devsper/providers/openai.py

@@ -0,0 +1,105 @@
+"""OpenAI provider adapter. Supports standard OpenAI API and Azure OpenAI."""
+
+import os
+
+from langchain_core.messages import HumanMessage
+from langchain_openai import AzureChatOpenAI, ChatOpenAI
+
+from devsper.providers.base import BaseProvider
+
+
+def _is_azure_foundry_v1_endpoint(endpoint: str) -> bool:
+    """True if endpoint is Azure Foundry v1 style (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
+
+
+class OpenAIProvider(BaseProvider):
+    """
+    OpenAI API adapter. Supports standard OpenAI and Azure OpenAI.
+
+    Standard: OPENAI_API_KEY (or pass api_key). Model passed in generate(model, prompt).
+    Azure: set azure=True and azure_endpoint (and optionally azure_deployment for single-deployment).
+    When Azure is used, generate(model, prompt) uses model as the deployment name so multiple
+    deployments (e.g. gpt-4o, gpt-5-mini) on the same endpoint are supported.
+
+    Azure Foundry (cognitiveservices.azure.com or .../openai/v1) uses the v1 API: one base URL
+    and deployment name in the request body. Legacy Azure (openai.azure.com) uses deployment in the path.
+    """
+
+    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
+        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 azure:
+            if not self.azure_endpoint:
+                raise ValueError("Azure requires azure_endpoint or AZURE_OPENAI_ENDPOINT")
+            key = self.api_key or os.environ.get("AZURE_OPENAI_API_KEY")
+            if not key:
+                raise ValueError("Azure requires api_key or AZURE_OPENAI_API_KEY")
+            self._azure_key = key
+            self._azure_foundry = _is_azure_foundry_v1_endpoint(self.azure_endpoint)
+            self._llm: AzureChatOpenAI | ChatOpenAI | None = None
+            self._llm_cache: dict[str, AzureChatOpenAI | ChatOpenAI] = {}
+        else:
+            if not self.api_key:
+                raise ValueError("OpenAI requires api_key or OPENAI_API_KEY")
+            self._llm = None
+            self._llm_cache = {}
+
+    def generate(self, model: str, prompt: str, stream: bool = False):
+        """Call OpenAI or Azure OpenAI and return the model output text (or stream chunks if stream=True)."""
+        if self.azure:
+            raw = (model or self.azure_deployment or "").strip()
+            deployment = raw.split(":", 1)[-1].strip() if ":" in raw else raw
+            deployment = deployment or self.azure_deployment
+            if not deployment:
+                raise ValueError("Azure requires model name or AZURE_OPENAI_DEPLOYMENT_NAME")
+            if deployment not in self._llm_cache:
+                if self._azure_foundry:
+                    # Azure Foundry v1: single base URL, model in body (no deployment in path)
+                    base = self.azure_endpoint if self.azure_endpoint.endswith("/") else self.azure_endpoint + "/"
+                    self._llm_cache[deployment] = ChatOpenAI(
+                        base_url=base,
+                        api_key=self._azure_key,
+                        model=deployment,
+                        temperature=0,
+                    )
+                else:
+                    self._llm_cache[deployment] = AzureChatOpenAI(
+                        azure_endpoint=self.azure_endpoint,
+                        azure_deployment=deployment,
+                        openai_api_key=self._azure_key,
+                        api_version=self.api_version,
+                    )
+            message = self._llm_cache[deployment].invoke([HumanMessage(content=prompt)])
+        else:
+            llm = ChatOpenAI(
+                model=model,
+                api_key=self.api_key,
+                temperature=0,
+            )
+            message = llm.invoke([HumanMessage(content=prompt)])
+        content = message.content
+        text = content if isinstance(content, str) else str(content)
+        if stream:
+            def _gen():
+                yield text
+            return _gen()
+        return text

devsper/providers/router/__init__.py

@@ -0,0 +1,21 @@
+"""Router package: legacy ProviderRouter + v2 LLMRouter."""
+
+from devsper.providers.router.base import LLMBackend, LLMRequest, LLMResponse
+from devsper.providers.router.router import LLMRouter
+from devsper.providers.router.legacy import (
+    ProviderRouter,
+    get_router,
+    _parse_model_spec,
+    _model_to_vendor,
+)
+
+__all__ = [
+    "LLMBackend",
+    "LLMRequest",
+    "LLMResponse",
+    "LLMRouter",
+    "ProviderRouter",
+    "get_router",
+    "_parse_model_spec",
+    "_model_to_vendor",
+]

devsper/providers/router/backends/__init__.py

@@ -0,0 +1,19 @@
+"""LLM backends for the router."""
+
+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
+
+__all__ = [
+    "OpenAIBackend",
+    "AnthropicBackend",
+    "GeminiBackend",
+    "GitHubBackend",
+    "OllamaBackend",
+    "VLLMBackend",
+    "CustomBackend",
+]