stcode 0.0.1a0__py3-none-any.whl

stcode/core/providers/google_gemini.py

@@ -0,0 +1,225 @@
+"""
+Google GenAI (Gemini) LLM Provider
+"""
+
+from __future__ import annotations
+
+import json
+from typing import AsyncGenerator
+
+from google import genai
+from google.genai import types
+
+from stcode.core.providers.base import BaseModelProvider
+from stcode.core.providers.types import (
+    Message,
+    MessageStop,
+    ReasoningDelta,
+    ReasoningEffort,
+    StopReason,
+    StreamEvent,
+    TextBlock,
+    TextDelta,
+    ToolCallDelta,
+    ToolCallEnd,
+    ToolCallStart,
+    ToolDefinition,
+    ToolResultBlock,
+    ToolUseBlock,
+    Usage,
+)
+
+DEFAULT_MODEL = "gemini-3.7-flash"
+
+# ThinkingConfig.thinking_level tops out at HIGH — there's no xhigh/max rung,
+# so both clamp down to it. "none" is handled separately via thinking_budget=0.
+_EFFORT_TO_GEMINI_THINKING_LEVEL: dict[str, str] = {
+    "minimal": "MINIMAL",
+    "low": "LOW",
+    "medium": "MEDIUM",
+    "high": "HIGH",
+    "xhigh": "HIGH",
+    "max": "HIGH",
+}
+
+_ROLE_MAP = {"user": "user", "assistant": "model"}
+
+_REFUSAL_FINISH_REASONS = {
+    types.FinishReason.SAFETY,
+    types.FinishReason.PROHIBITED_CONTENT,
+    types.FinishReason.BLOCKLIST,
+    types.FinishReason.SPII,
+    types.FinishReason.RECITATION,
+    types.FinishReason.IMAGE_SAFETY,
+    types.FinishReason.IMAGE_PROHIBITED_CONTENT,
+}
+
+
+class GoogleGenAIProvider(BaseModelProvider):
+    def __init__(self, api_key: str | None = None, base_url: str | None = None) -> None:
+        super().__init__(api_key, base_url)
+        http_options = types.HttpOptions(base_url=base_url) if base_url else None
+        self._client = genai.Client(api_key=api_key, http_options=http_options)
+
+    async def list_models(self) -> list[str]:
+        return [model.name.removeprefix("models/") async for model in self._client.aio.models.list()]
+
+    async def aclose(self) -> None:
+        await self._client.aio.aclose()
+
+    async def stream(
+        self,
+        messages: list[Message],
+        *,
+        model: str = DEFAULT_MODEL,
+        system: str | None = None,
+        tools: list[ToolDefinition] | None = None,
+        max_tokens: int = 8192,
+        reasoning_effort: ReasoningEffort | None = None,
+        temperature: float | None = None,
+        top_p: float | None = None,
+        stop: list[str] | None = None,
+        parallel_tool_calls: bool | None = None,
+    ) -> AsyncGenerator[StreamEvent, None]:
+        """`reasoning_effort="none"` sets `thinking_budget=0` (thinking off);
+        any other value maps onto `thinking_config.thinking_level`, clamped to
+        Gemini's four-level scale (`xhigh`/`max` both become `HIGH`). Thoughts
+        are always requested (`include_thoughts=True`) so a thinking-capable
+        model's reasoning surfaces as `ReasoningDelta` regardless of level —
+        it's a no-op on models that don't support thinking.
+
+        `parallel_tool_calls` has no Gemini equivalent exposed by this SDK and
+        is accepted but ignored.
+        """
+        thinking_config = (
+            types.ThinkingConfig(thinking_budget=0)
+            if reasoning_effort == "none"
+            else types.ThinkingConfig(
+                include_thoughts=True,
+                thinking_level=(
+                    _EFFORT_TO_GEMINI_THINKING_LEVEL[reasoning_effort] if reasoning_effort else None
+                ),
+            )
+        )
+        config = types.GenerateContentConfig(
+            system_instruction=system,
+            max_output_tokens=max_tokens,
+            tools=[self._to_tool(tools)] if tools else None,
+            thinking_config=thinking_config,
+            temperature=temperature,
+            top_p=top_p,
+            stop_sequences=stop,
+        )
+
+        has_tool_call = False
+        finish_reason: types.FinishReason | None = None
+        usage = Usage()
+
+        response_stream = await self._client.aio.models.generate_content_stream(
+            model=model,
+            contents=self._to_contents(messages),
+            config=config,
+        )
+        async for chunk in response_stream:
+            for candidate in chunk.candidates or []:
+                if candidate.finish_reason is not None:
+                    finish_reason = candidate.finish_reason
+                if candidate.content is None or not candidate.content.parts:
+                    continue
+                for part in candidate.content.parts:
+                    if part.text:
+                        if part.thought:
+                            yield ReasoningDelta(text=part.text)
+                        else:
+                            yield TextDelta(text=part.text)
+                    elif part.function_call is not None:
+                        has_tool_call = True
+                        call = part.function_call
+                        call_id = call.id or call.name or ""
+                        args = dict(call.args) if call.args else {}
+                        yield ToolCallStart(id=call_id, name=call.name)
+                        yield ToolCallDelta(id=call_id, partial_json=json.dumps(args, default=str))
+                        yield ToolCallEnd(id=call_id, name=call.name, input=args)
+            if chunk.usage_metadata is not None:
+                usage = Usage(
+                    input_tokens=chunk.usage_metadata.prompt_token_count or 0,
+                    output_tokens=chunk.usage_metadata.candidates_token_count or 0,
+                )
+
+        yield MessageStop(
+            stop_reason=self._map_stop_reason(has_tool_call, finish_reason),
+            usage=usage,
+        )
+
+    @staticmethod
+    def _to_tool(tools: list[ToolDefinition]) -> types.Tool:
+        return types.Tool(
+            function_declarations=[
+                types.FunctionDeclaration(
+                    name=tool.name,
+                    description=tool.description,
+                    parameters_json_schema=tool.input_schema,
+                )
+                for tool in tools
+            ]
+        )
+
+    @staticmethod
+    def _to_contents(messages: list[Message]) -> list[types.Content]:
+        # Gemini matches tool results by name, not id — recover each id's tool name
+        # from the tool_use blocks that precede it in the conversation.
+        tool_names: dict[str, str] = {}
+        for message in messages:
+            if isinstance(message.content, list):
+                for block in message.content:
+                    if isinstance(block, ToolUseBlock):
+                        tool_names[block.id] = block.name
+
+        contents: list[types.Content] = []
+        for message in messages:
+            blocks = (
+                [TextBlock(text=message.content)]
+                if isinstance(message.content, str)
+                else message.content
+            )
+            buffer: list[types.Part] = []
+            buffer_role: str | None = None
+            for block in blocks:
+                if isinstance(block, TextBlock):
+                    role = _ROLE_MAP[message.role]
+                    part = types.Part.from_text(text=block.text)
+                elif isinstance(block, ToolUseBlock):
+                    role = "model"
+                    part = types.Part(
+                        function_call=types.FunctionCall(id=block.id, name=block.name, args=block.input)
+                    )
+                elif isinstance(block, ToolResultBlock):
+                    role = "tool"
+                    name = tool_names.get(block.tool_use_id, block.tool_use_id)
+                    response = {"error": block.content} if block.is_error else {"result": block.content}
+                    part = types.Part(
+                        function_response=types.FunctionResponse(
+                            id=block.tool_use_id, name=name, response=response
+                        )
+                    )
+                else:
+                    continue
+
+                if buffer_role is not None and buffer_role != role:
+                    contents.append(types.Content(role=buffer_role, parts=buffer))
+                    buffer = []
+                buffer_role = role
+                buffer.append(part)
+            if buffer:
+                contents.append(types.Content(role=buffer_role, parts=buffer))
+        return contents
+
+    @staticmethod
+    def _map_stop_reason(has_tool_call: bool, finish_reason: types.FinishReason | None) -> StopReason:
+        if has_tool_call:
+            return "tool_use"
+        if finish_reason == types.FinishReason.MAX_TOKENS:
+            return "max_tokens"
+        if finish_reason in _REFUSAL_FINISH_REASONS:
+            return "refusal"
+        return "end_turn"

stcode/core/providers/openai_gpt.py

@@ -0,0 +1,250 @@
+"""
+OpenAI LLM Provider
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any, AsyncGenerator
+
+from openai import AsyncOpenAI
+
+log = logging.getLogger("stcode.providers.openai")
+
+from stcode.core.providers.base import BaseModelProvider
+from stcode.core.providers.types import (
+    Message,
+    MessageStop,
+    ReasoningDelta,
+    ReasoningEffort,
+    StopReason,
+    StreamEvent,
+    TextBlock,
+    TextDelta,
+    ToolCallDelta,
+    ToolCallEnd,
+    ToolCallStart,
+    ToolDefinition,
+    ToolResultBlock,
+    ToolUseBlock,
+    Usage,
+)
+
+DEFAULT_MODEL = "gpt-5.6"
+
+_FINISH_REASON_MAP: dict[str, StopReason] = {
+    "stop": "end_turn",
+    "tool_calls": "tool_use",
+    "length": "max_tokens",
+    "content_filter": "refusal",
+}
+
+
+def _parse_tool_arguments(raw_json: str) -> dict[str, Any]:
+    """Parse tool call arguments from streamed chunks with lenient repair.
+
+    A stream cut off by `finish_reason="length"` or an open-source proxy often drops the
+    closing quote or bracket. Attempting simple repairs prevents a truncated generation
+    from crashing the turn with JSONDecodeError.
+    """
+    if not raw_json or not raw_json.strip():
+        return {}
+    cleaned = raw_json.strip()
+    try:
+        val = json.loads(cleaned)
+        return val if isinstance(val, dict) else {"_value": val}
+    except json.JSONDecodeError:
+        pass
+
+    # Try common truncation closures (unclosed string or unclosed objects)
+    for suffix in ['"}', '"}]', "}", "]}", '"]}', '"]}}']:
+        try:
+            val = json.loads(cleaned + suffix)
+            if isinstance(val, dict):
+                log.debug("Repaired truncated tool arguments using suffix %r", suffix)
+                return val
+        except json.JSONDecodeError:
+            continue
+
+    log.warning("Malformed tool call arguments received from model: %s", raw_json)
+    return {"_raw": raw_json, "_error": "JSONDecodeError"}
+
+
+class OpenAIProvider(BaseModelProvider):
+    """Talks to the OpenAI Chat Completions protocol — the de facto standard for
+    third-party OpenAI-compatible routers/proxies (unlike the newer Responses API,
+    which is rarely implemented outside api.openai.com itself).
+    """
+
+    def __init__(self, api_key: str | None = None, base_url: str | None = None) -> None:
+        super().__init__(api_key, base_url)
+        self._client = AsyncOpenAI(api_key=api_key, base_url=base_url)
+
+    async def list_models(self) -> list[str]:
+        return [model.id async for model in self._client.models.list()]
+
+    async def aclose(self) -> None:
+        await self._client.close()
+
+    async def stream(
+        self,
+        messages: list[Message],
+        *,
+        model: str = DEFAULT_MODEL,
+        system: str | None = None,
+        tools: list[ToolDefinition] | None = None,
+        max_tokens: int = 8192,
+        reasoning_effort: ReasoningEffort | None = None,
+        temperature: float | None = None,
+        top_p: float | None = None,
+        stop: list[str] | None = None,
+        parallel_tool_calls: bool | None = None,
+    ) -> AsyncGenerator[StreamEvent, None]:
+        """`reasoning_effort` maps 1:1 onto Chat Completions' own `reasoning_effort`
+        field — OpenAI already uses this exact seven-value scale. Support for
+        each value is model-dependent; the API rejects a value the target model
+        doesn't recognize rather than us pre-validating it here.
+        """
+        kwargs: dict[str, Any] = {}
+        if tools:
+            kwargs["tools"] = [self._to_tool(tool) for tool in tools]
+            if parallel_tool_calls is not None:
+                kwargs["parallel_tool_calls"] = parallel_tool_calls
+        if reasoning_effort is not None:
+            kwargs["reasoning_effort"] = reasoning_effort
+        if temperature is not None:
+            kwargs["temperature"] = temperature
+        if top_p is not None:
+            kwargs["top_p"] = top_p
+        if stop is not None:
+            kwargs["stop"] = stop
+
+        # index -> accumulated call state, for pairing deltas back to a call
+        pending_calls: dict[int, dict[str, Any]] = {}
+        usage = Usage()
+        stop_reason: StopReason = "end_turn"
+
+        response_stream = await self._client.chat.completions.create(
+            model=model,
+            messages=self._to_messages(messages, system),
+            max_tokens=max_tokens,
+            stream=True,
+            stream_options={"include_usage": True},
+            **kwargs,
+        )
+        # `async with`, not a bare `async for`. The SDK closes the response only "if the
+        # response body is read to completion", and an SSE stream never is: iteration
+        # stops at the `[DONE]` sentinel with httpcore's byte generator still suspended
+        # mid-body. Left to the garbage collector it is closed after the event loop has
+        # gone, which surfaces as `RuntimeError: generator didn't stop after athrow()`
+        # from inside httpcore — a traceback with nothing in it pointing here.
+        async with response_stream:
+            async for chunk in response_stream:
+                if chunk.usage is not None:
+                    usage = Usage(
+                        input_tokens=chunk.usage.prompt_tokens,
+                        output_tokens=chunk.usage.completion_tokens,
+                    )
+                if not chunk.choices:
+                    continue
+
+                choice = chunk.choices[0]
+                delta = choice.delta
+                if delta.content:
+                    yield TextDelta(text=delta.content)
+
+                # Not a Chat Completions field — some OpenAI-compatible routers (e.g.
+                # reasoning-model proxies) bolt it onto the delta as an extra attribute.
+                reasoning = getattr(delta, "reasoning", None)
+                if reasoning:
+                    yield ReasoningDelta(text=reasoning)
+
+                for tool_call_delta in delta.tool_calls or []:
+                    index = tool_call_delta.index
+                    if tool_call_delta.id is not None:
+                        # First chunk for this call: id + name arrive together.
+                        name = tool_call_delta.function.name if tool_call_delta.function else ""
+                        pending_calls[index] = {"id": tool_call_delta.id, "name": name, "json": ""}
+                        yield ToolCallStart(id=tool_call_delta.id, name=name)
+                    call = pending_calls.get(index)
+                    if call is None:
+                        continue
+                    arguments = tool_call_delta.function.arguments if tool_call_delta.function else None
+                    if arguments:
+                        call["json"] += arguments
+                        yield ToolCallDelta(id=call["id"], partial_json=arguments)
+
+                if choice.finish_reason is not None:
+                    stop_reason = _FINISH_REASON_MAP.get(choice.finish_reason, "end_turn")
+                    # Some OpenAI-compatible routers repeat finish_reason on a trailing
+                    # usage-only chunk — clear so that chunk doesn't re-flush stale calls.
+                    for call in pending_calls.values():
+                        yield ToolCallEnd(
+                            id=call["id"],
+                            name=call["name"],
+                            input=_parse_tool_arguments(call["json"]),
+                        )
+                    pending_calls.clear()
+
+        # Flush any remaining calls if finish_reason was omitted or stream ended early
+        for call in pending_calls.values():
+            yield ToolCallEnd(
+                id=call["id"],
+                name=call["name"],
+                input=_parse_tool_arguments(call["json"]),
+            )
+        pending_calls.clear()
+
+        yield MessageStop(stop_reason=stop_reason, usage=usage)
+
+    @staticmethod
+    def _to_tool(tool: ToolDefinition) -> dict[str, Any]:
+        return {
+            "type": "function",
+            "function": {
+                "name": tool.name,
+                "description": tool.description,
+                "parameters": tool.input_schema,
+            },
+        }
+
+    @staticmethod
+    def _to_messages(messages: list[Message], system: str | None) -> list[dict[str, Any]]:
+        chat_messages: list[dict[str, Any]] = []
+        if system:
+            chat_messages.append({"role": "system", "content": system})
+
+        for message in messages:
+            if isinstance(message.content, str):
+                chat_messages.append({"role": message.role, "content": message.content})
+                continue
+
+            text_parts: list[str] = []
+            tool_calls: list[dict[str, Any]] = []
+            for block in message.content:
+                if isinstance(block, TextBlock):
+                    text_parts.append(block.text)
+                elif isinstance(block, ToolUseBlock):
+                    tool_calls.append(
+                        {
+                            "id": block.id,
+                            "type": "function",
+                            "function": {"name": block.name, "arguments": json.dumps(block.input)},
+                        }
+                    )
+                elif isinstance(block, ToolResultBlock):
+                    # Chat Completions has no first-class error flag on tool messages —
+                    # fold it into the content so the model still sees the failure.
+                    content = f"Error: {block.content}" if block.is_error else block.content
+                    chat_messages.append(
+                        {"role": "tool", "tool_call_id": block.tool_use_id, "content": content}
+                    )
+
+            if text_parts or tool_calls:
+                turn: dict[str, Any] = {"role": message.role, "content": "".join(text_parts) or None}
+                if tool_calls:
+                    turn["tool_calls"] = tool_calls
+                chat_messages.append(turn)
+
+        return chat_messages

stcode/core/providers/registry.py

@@ -0,0 +1,46 @@
+"""
+Provider registry — the LLM libraries stcode can talk to, and each one's default model.
+
+The default model lives in each provider module and is read from there, so it cannot
+drift. Which environment variable holds a library's key is configuration, and lives in
+`core/configs.py` (`PROVIDER_KEY_ENV`).
+"""
+
+from stcode.core.providers.anthropic_claude import (
+    DEFAULT_MODEL as ANTHROPIC_DEFAULT_MODEL,
+)
+from stcode.core.providers.anthropic_claude import AnthropicProvider
+from stcode.core.providers.base import BaseModelProvider
+from stcode.core.providers.google_gemini import DEFAULT_MODEL as GOOGLE_DEFAULT_MODEL
+from stcode.core.providers.google_gemini import GoogleGenAIProvider
+from stcode.core.providers.openai_gpt import DEFAULT_MODEL as OPENAI_DEFAULT_MODEL
+from stcode.core.providers.openai_gpt import OpenAIProvider
+
+PROVIDERS: dict[str, type[BaseModelProvider]] = {
+    "anthropic": AnthropicProvider,
+    "openai": OpenAIProvider,
+    "google": GoogleGenAIProvider,
+}
+
+
+DEFAULT_MODELS: dict[str, str] = {
+    "anthropic": ANTHROPIC_DEFAULT_MODEL,
+    "openai": OPENAI_DEFAULT_MODEL,
+    "google": GOOGLE_DEFAULT_MODEL,
+}
+
+
+def default_model_for(provider: str) -> str:
+    """The model a library is pointed at when the config names none."""
+    return DEFAULT_MODELS.get(provider, "")
+
+
+def get_provider(
+    name: str, api_key: str | None = None, base_url: str | None = None
+) -> BaseModelProvider:
+    """Instantiate a registered provider by name (e.g. "anthropic", "openai", "google")."""
+    try:
+        provider_cls = PROVIDERS[name]
+    except KeyError:
+        raise ValueError(f"Unknown provider {name!r}. Available: {sorted(PROVIDERS)}") from None
+    return provider_cls(api_key=api_key, base_url=base_url)

stcode/core/providers/types.py

@@ -0,0 +1,148 @@
+"""
+Unified message, tool and streaming-event shapes, shared by every provider.
+
+Providers translate to and from these at their boundary, so the agent loop, the tool
+executor and the TUI never touch a provider SDK type directly.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal, Union
+
+from pydantic import BaseModel
+
+from stcode.core.common.tools import ToolDefinition
+
+__all__ = [
+    "REASONING_EFFORTS",
+    "ContentBlock",
+    "Message",
+    "MessageStop",
+    "ReasoningDelta",
+    "ReasoningEffort",
+    "Role",
+    "StopReason",
+    "StreamEvent",
+    "TextBlock",
+    "TextDelta",
+    "ToolCallDelta",
+    "ToolCallEnd",
+    "ToolCallStart",
+    "ToolDefinition",
+    "ToolResultBlock",
+    "ToolUseBlock",
+    "Usage",
+]
+
+Role = Literal["user", "assistant"]
+
+# The effort scale is the union of every provider's; a provider with a narrower one
+# (Anthropic has no `none`/`minimal`, Gemini tops out at `high`) clamps at its boundary.
+from stcode.core.configs import REASONING_EFFORTS, ReasoningEffort  # noqa: E402
+
+StopReason = Literal[
+    "end_turn",
+    "tool_use",
+    "max_tokens",
+    "stop_sequence",
+    "pause_turn",
+    "refusal",
+    "error",
+]
+
+
+class TextBlock(BaseModel):
+    type: Literal["text"] = "text"
+    text: str
+
+
+class ToolUseBlock(BaseModel):
+    type: Literal["tool_use"] = "tool_use"
+    id: str
+    name: str
+    input: dict[str, Any]
+
+
+class ToolResultBlock(BaseModel):
+    type: Literal["tool_result"] = "tool_result"
+    tool_use_id: str
+    content: str
+    is_error: bool = False
+
+
+ContentBlock = Union[TextBlock, ToolUseBlock, ToolResultBlock]
+
+
+class Message(BaseModel):
+    role: Role
+    content: str | list[ContentBlock]
+
+
+# `ToolDefinition` is re-exported, not defined here: three packages need it now, so it
+# lives in `core/common/tools.py`. Importing it from this module still works — every
+# provider adapter already does — but new code should reach for `core.common`.
+
+
+class Usage(BaseModel):
+    """Token counts for one completion.
+
+    The two cache fields stay 0 for providers that cache implicitly (OpenAI) or not at
+    all. They are here because "turn 2 is ~10x cheaper" is otherwise an unverifiable
+    claim: `cache_read_input_tokens` on turn 2 is the evidence, and the agent writes it
+    into the session where anyone can look."""
+
+    input_tokens: int = 0
+    output_tokens: int = 0
+    cache_creation_input_tokens: int = 0
+    cache_read_input_tokens: int = 0
+
+
+class TextDelta(BaseModel):
+    """Incremental assistant text."""
+
+    type: Literal["text_delta"] = "text_delta"
+    text: str
+
+
+class ReasoningDelta(BaseModel):
+    """Incremental reasoning/thinking text — model's internal deliberation, not the
+    final answer. Never sent back to the provider as conversation history."""
+
+    type: Literal["reasoning_delta"] = "reasoning_delta"
+    text: str
+
+
+class ToolCallStart(BaseModel):
+    """A new tool call began; its input will arrive via ToolCallDelta events."""
+
+    type: Literal["tool_call_start"] = "tool_call_start"
+    id: str
+    name: str
+
+
+class ToolCallDelta(BaseModel):
+    """Incremental (partial-JSON) tool call input."""
+
+    type: Literal["tool_call_delta"] = "tool_call_delta"
+    id: str
+    partial_json: str
+
+
+class ToolCallEnd(BaseModel):
+    """A tool call finished streaming; `input` is the fully parsed argument dict."""
+
+    type: Literal["tool_call_end"] = "tool_call_end"
+    id: str
+    name: str
+    input: dict[str, Any]
+
+
+class MessageStop(BaseModel):
+    """Terminal event for a single completion — always the last event yielded."""
+
+    type: Literal["message_stop"] = "message_stop"
+    stop_reason: StopReason
+    usage: Usage
+
+
+StreamEvent = Union[TextDelta, ReasoningDelta, ToolCallStart, ToolCallDelta, ToolCallEnd, MessageStop]

stcode/core/repl/__init__.py

@@ -0,0 +1,19 @@
+"""
+`core/repl/` — a persistent Python namespace, in a subprocess.
+
+Two files: `_worker.py` is the child, `client.py` is the parent. They speak JSONL over
+stdin/stdout — the same framing as the session file and the daemon protocol.
+
+It exists for MCP-as-code: somewhere to `import` a generated stub and hold the result
+across turns, so the bulk never touches the context window.
+"""
+
+from stcode.core.repl.client import (
+    DEFAULT_TIMEOUT,
+    ExecResult,
+    PyREPL,
+    ReplError,
+    StreamFn,
+)
+
+__all__ = ["DEFAULT_TIMEOUT", "ExecResult", "PyREPL", "ReplError", "StreamFn"]