semora-llm 0.1.0__tar.gz

semora_llm-0.1.0/.gitignore

@@ -0,0 +1,28 @@
+.venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.coverage
+htmlcov/
+.env
+.env.*
+!.env.example
+
+
+# Local tool/editor state — machine-specific, never pushed.
+.claude/
+.codecanvas/
+.vscode/
+
+
+# Superpowers design/spec scratch — working notes, not project documentation.
+docs/superpowers/
+
+# 로컬 자격증명 — 절대 커밋 금지.
+a.txt
+*.token

semora_llm-0.1.0/PKG-INFO

@@ -0,0 +1,17 @@
+Metadata-Version: 2.5
+Name: semora-llm
+Version: 0.1.0
+Summary: OpenAI-compatible chat model for Semora: official openai SDK, LangChain chunks.
+Project-URL: Homepage, https://github.com/donggyun112/semora
+Project-URL: Source, https://github.com/donggyun112/semora
+Project-URL: Changelog, https://github.com/donggyun112/semora/blob/main/CHANGELOG.md
+Author: donggyun112
+License-Expression: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: langchain-core<2,>=1
+Requires-Dist: openai<4,>=3

semora_llm-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "semora-llm"
+version = "0.1.0"
+description = "OpenAI-compatible chat model for Semora: official openai SDK, LangChain chunks."
+requires-python = ">=3.12"
+license = "MIT"
+authors = [{ name = "donggyun112" }]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.12",
+  "Typing :: Typed",
+]
+urls = { Homepage = "https://github.com/donggyun112/semora", Source = "https://github.com/donggyun112/semora", Changelog = "https://github.com/donggyun112/semora/blob/main/CHANGELOG.md" }
+dependencies = [
+  "langchain-core>=1,<2",
+  "openai>=3,<4",
+]
+# Own footprint: the OpenAI Chat Completions wire and the chunk adapter the loop
+# already speaks. Not a provider catalog. Anthropic/Google native APIs stay extras.
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/semora_llm"]

semora_llm-0.1.0/src/semora_llm/__init__.py

@@ -0,0 +1,14 @@
+"""OpenAI-compatible chat model used by Semora's planner."""
+
+from .chat import ChatModel, openrouter, xai
+from .dsml import DsmlFilter, parse_dsml_tool_calls, recover_dsml_chunks, strip_dsml
+
+__all__ = [
+    "ChatModel",
+    "DsmlFilter",
+    "openrouter",
+    "parse_dsml_tool_calls",
+    "recover_dsml_chunks",
+    "strip_dsml",
+    "xai",
+]

semora_llm-0.1.0/src/semora_llm/chat.py

@@ -0,0 +1,303 @@
+"""OpenAI Chat Completions client that streams LangChain chunks.
+
+The loop binds tools and consumes ``astream``. This class is that surface over the
+official ``openai`` SDK. HTTP, SSE, retries-off, and error types stay the SDK's.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from collections.abc import AsyncIterator, Iterable, Mapping, Sequence
+from dataclasses import dataclass
+from typing import Any
+
+from langchain_core.messages import (
+    AIMessage,
+    AIMessageChunk,
+    BaseMessage,
+    HumanMessage,
+    SystemMessage,
+    ToolMessage,
+)
+from openai import AsyncOpenAI
+
+from .dsml import recover_dsml_chunks
+
+__all__ = ["ChatModel"]
+
+OPENROUTER_URL = "https://openrouter.ai/api/v1"
+XAI_URL = "https://api.x.ai/v1"
+
+
+@dataclass(frozen=True, slots=True)
+class ChatModel:
+    """Stream chat completions from any OpenAI-compatible ``/v1`` endpoint.
+
+    ``bind_tools`` / ``astream`` / ``_identifying_params`` are the planner contract.
+    Construct with ``base_url`` for OpenRouter, xAI, Groq, vLLM, Ollama, and the rest
+    of the OpenAI-compatible wire. Native Anthropic/Google APIs are not this class.
+    """
+
+    model: str
+    api_key: str | None = None
+    base_url: str | None = None
+    default_headers: Mapping[str, str] | None = None
+    extra_body: Mapping[str, Any] | None = None
+    tools: tuple[dict[str, Any], ...] = ()
+    client: Any = None
+    timeout: float | None = None
+    """Seconds before a request is abandoned. None leaves the SDK's own default, which
+    is generous: a hung provider holds a worker for ten minutes without one."""
+    recover_dsml: bool = False
+    """Repair tool markup a gateway left in assistant content. A no-op for a provider
+    that does not leak it, so presets turn it on per gateway rather than per model."""
+
+    def bind_tools(self, tools: Sequence[Any], **_kwargs: Any) -> ChatModel:
+        """Return a copy that sends these OpenAI-format tool definitions."""
+        encoded = tuple(_as_openai_tool(tool) for tool in tools)
+        return ChatModel(
+            model=self.model,
+            api_key=self.api_key,
+            base_url=self.base_url,
+            default_headers=self.default_headers,
+            extra_body=self.extra_body,
+            tools=encoded,
+            client=self.client,
+            timeout=self.timeout,
+            recover_dsml=self.recover_dsml,
+        )
+
+    @property
+    def _identifying_params(self) -> dict[str, Any]:
+        """Stable identity used by the durable model request key."""
+        return {
+            "model": self.model,
+            "base_url": self.base_url or "",
+            "tools": list(self.tools),
+        }
+
+    async def astream(
+        self, messages: Iterable[BaseMessage], **_kwargs: Any
+    ) -> AsyncIterator[AIMessageChunk]:
+        """Yield one LangChain chunk per provider delta, repaired where a gateway leaks."""
+        deltas = self._deltas(messages)
+        repaired = recover_dsml_chunks(deltas) if self.recover_dsml else deltas
+        async for chunk in repaired:
+            yield chunk
+
+    async def _deltas(
+        self, messages: Iterable[BaseMessage]
+    ) -> AsyncIterator[AIMessageChunk]:
+        """The provider's own stream, one LangChain chunk per delta."""
+        stream = await self._openai().chat.completions.create(
+            model=self.model,
+            messages=encode_messages(list(messages)),
+            stream=True,
+            stream_options={"include_usage": True},
+            **self._create_options(),
+        )
+        async for chunk in stream:
+            yield decode_chunk(chunk)
+
+    def _openai(self) -> Any:
+        """Return the injected client or construct the official async SDK client."""
+        if self.client is not None:
+            return self.client
+        options: dict[str, Any] = {}
+        if self.timeout is not None:
+            options["timeout"] = self.timeout
+        return AsyncOpenAI(
+            api_key=self.api_key,
+            base_url=self.base_url,
+            default_headers=dict(self.default_headers) if self.default_headers else None,
+            # Retries stay off here. A retried model call is a second turn the ledger
+            # never saw, and deciding whether that is safe is the caller's, not ours.
+            max_retries=0,
+            **options,
+        )
+
+    def _create_options(self) -> dict[str, Any]:
+        """Keyword arguments that only exist when the caller set them."""
+        options: dict[str, Any] = {}
+        if self.tools:
+            options["tools"] = list(self.tools)
+        if self.extra_body:
+            options["extra_body"] = dict(self.extra_body)
+        return options
+
+
+def encode_messages(messages: list[BaseMessage]) -> list[dict[str, Any]]:
+    """Turn LangChain messages into Chat Completions message dicts."""
+    return [_encode_one(message) for message in messages]
+
+
+def decode_chunk(chunk: Any) -> AIMessageChunk:
+    """Turn one SDK stream chunk into the chunk type the loop already adds."""
+    choice = (getattr(chunk, "choices", None) or [None])[0]
+    delta = getattr(choice, "delta", None) if choice is not None else None
+    text = getattr(delta, "content", None) if delta is not None else None
+    content: str | list[dict[str, Any]] = text or ""
+    reasoning = _extra(delta, "reasoning")
+    if reasoning:
+        blocks: list[dict[str, Any]] = [
+            {"type": "reasoning", "reasoning": str(reasoning), "index": 0},
+        ]
+        if text:
+            blocks.append({"type": "text", "text": str(text)})
+        content = blocks
+    kwargs: dict[str, Any] = {}
+    details = _extra(delta, "reasoning_details")
+    if details:
+        kwargs["reasoning_details"] = details
+    usage = getattr(chunk, "usage", None)
+    usage_metadata = _usage(usage)
+    model_name = getattr(chunk, "model", None)
+    return AIMessageChunk(
+        content=content,
+        additional_kwargs=kwargs,
+        tool_call_chunks=_tool_call_chunks(delta),
+        usage_metadata=usage_metadata or None,
+        response_metadata={"model_name": model_name} if model_name else {},
+    )
+
+
+def _encode_one(message: BaseMessage) -> dict[str, Any]:
+    """Encode one LangChain message to the Chat Completions shape."""
+    if isinstance(message, SystemMessage):
+        return {"role": "system", "content": _text(message)}
+    if isinstance(message, HumanMessage):
+        return {"role": "user", "content": _text(message)}
+    if isinstance(message, ToolMessage):
+        return {
+            "role": "tool",
+            "tool_call_id": message.tool_call_id,
+            "content": _text(message),
+        }
+    if isinstance(message, AIMessage):
+        body: dict[str, Any] = {"role": "assistant", "content": _text(message) or None}
+        if message.tool_calls:
+            body["tool_calls"] = [_encode_tool_call(call) for call in message.tool_calls]
+        if details := message.additional_kwargs.get("reasoning_details"):
+            body["reasoning_details"] = details
+        return body
+    return {"role": "user", "content": _text(message)}
+
+
+def _encode_tool_call(call: Mapping[str, Any]) -> dict[str, Any]:
+    """Encode one LangChain tool call as an OpenAI function tool call."""
+    arguments = call.get("args", {})
+    if not isinstance(arguments, str):
+        arguments = json.dumps(arguments, ensure_ascii=False)
+    return {
+        "id": call.get("id") or "",
+        "type": "function",
+        "function": {"name": call.get("name") or "", "arguments": arguments},
+    }
+
+
+def _as_openai_tool(tool: Any) -> dict[str, Any]:
+    """Accept already-normalized OpenAI tool dicts from ``as_model_tools``."""
+    if isinstance(tool, Mapping) and tool.get("type") == "function":
+        return dict(tool)
+    if isinstance(tool, Mapping) and "name" in tool:
+        return {
+            "type": "function",
+            "function": {
+                "name": tool["name"],
+                "description": tool.get("description", ""),
+                "parameters": tool.get("parameters") or tool.get("schema") or {},
+            },
+        }
+    raise TypeError(f"unsupported tool definition: {type(tool)!r}")
+
+
+def _tool_call_chunks(delta: Any) -> list[dict[str, Any]]:
+    """Extract streaming tool-call fragments from a delta."""
+    calls = getattr(delta, "tool_calls", None) if delta is not None else None
+    if not calls:
+        return []
+    chunks: list[dict[str, Any]] = []
+    for call in calls:
+        function = getattr(call, "function", None)
+        chunks.append(
+            {
+                "name": getattr(function, "name", None) or "",
+                "args": getattr(function, "arguments", None) or "",
+                "id": getattr(call, "id", None) or "",
+                "index": getattr(call, "index", None) or 0,
+            }
+        )
+    return chunks
+
+
+def _usage(usage: Any) -> dict[str, int]:
+    """Map SDK usage onto the names the loop already reads."""
+    if usage is None:
+        return {}
+    prompt = getattr(usage, "prompt_tokens", None) or getattr(usage, "input_tokens", 0) or 0
+    completion = (
+        getattr(usage, "completion_tokens", None) or getattr(usage, "output_tokens", 0) or 0
+    )
+    total = getattr(usage, "total_tokens", None) or (prompt + completion)
+    return {
+        "input_tokens": int(prompt),
+        "output_tokens": int(completion),
+        "total_tokens": int(total),
+    }
+
+
+def _extra(delta: Any, key: str) -> Any:
+    """Read an undocumented delta field without depending on one SDK attribute layout."""
+    if delta is None:
+        return None
+    value = getattr(delta, key, None)
+    if value:
+        return value
+    extra = getattr(delta, "model_extra", None)
+    if isinstance(extra, Mapping):
+        return extra.get(key)
+    return None
+
+
+def _text(message: BaseMessage) -> str:
+    """Flatten message content to the string Chat Completions still accepts."""
+    content = message.content
+    if isinstance(content, str):
+        return content
+    if isinstance(content, list):
+        parts = [
+            str(block.get("text") or block.get("reasoning") or "")
+            for block in content
+            if isinstance(block, dict)
+        ]
+        return "".join(parts)
+    return str(content or "")
+
+
+def openrouter(model: str, *, api_key: str | None = None, **options: Any) -> ChatModel:
+    """OpenRouter preset: OpenAI wire plus the attribution headers their docs ask for."""
+    return ChatModel(
+        model,
+        api_key=api_key or os.environ.get("OPENROUTER_API_KEY"),
+        base_url=OPENROUTER_URL,
+        default_headers={
+            "HTTP-Referer": options.pop("referer", "https://semora.dev"),
+            "X-Title": options.pop("title", "Semora"),
+        },
+        extra_body=options.pop("extra_body", None),
+        # OpenRouter is the gateway observed dropping DeepSeek's markup into content.
+        # The repair costs a suffix scan per delta and does nothing to a clean stream.
+        recover_dsml=options.pop("recover_dsml", True),
+        **options,
+    )
+
+
+def xai(model: str, *, api_key: str | None = None, **options: Any) -> ChatModel:
+    """XAI preset: Grok over the OpenAI-compatible ``api.x.ai`` endpoint."""
+    return ChatModel(
+        model,
+        api_key=api_key or os.environ.get("XAI_API_KEY"),
+        base_url=XAI_URL,
+        **options,
+    )

semora_llm-0.1.0/src/semora_llm/dsml.py

@@ -0,0 +1,206 @@
+"""Recover DeepSeek DSML tool markup that a provider left as assistant text.
+
+DeepSeek V4 writes its tool calls as a markup block using fullwidth bars, and some
+gateways (OpenRouter among them) fail to lift that into OpenAI ``tool_calls``,
+streaming it as assistant content instead. Repairing it belongs to the provider
+client: the planner speaks LangChain tool calls and should never learn a vendor's
+markup dialect.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import uuid
+from collections.abc import AsyncIterator
+from typing import Any
+
+from langchain_core.messages import AIMessageChunk
+
+_BAR = "\uff5c"  # FULLWIDTH VERTICAL LINE, what DeepSeek actually emits
+_DSML = rf"(?:\|DSML\||{_BAR}DSML{_BAR})"
+_INVOKE = re.compile(
+    rf"<{_DSML}invoke\s+name=\"([^\"]+)\"\s*>(.*?)</{_DSML}invoke>",
+    re.DOTALL,
+)
+_PARAM = re.compile(
+    rf"<{_DSML}parameter\s+name=\"([^\"]+)\"(?:\s+string=\"(true|false)\")?\s*>"
+    rf"(.*?)</{_DSML}parameter>",
+    re.DOTALL,
+)
+_OPENS = (
+    "<|DSML|tool_calls>",
+    "<|DSML|function_calls>",
+    "<|DSML|invoke ",
+    "<|DSML|invoke>",
+)
+
+
+def _ascii(text: str) -> str:
+    """Normalise the fullwidth bars so one set of tags matches both spellings."""
+    return text.replace(_BAR, "|")
+
+
+def parse_dsml_tool_calls(text: str) -> list[dict[str, Any]]:
+    """Turn DSML markup into LangChain tool_call dicts. Empty if none."""
+    calls: list[dict[str, Any]] = []
+    for name, body in _INVOKE.findall(text or ""):
+        args: dict[str, Any] = {}
+        for key, is_str, raw in _PARAM.findall(body):
+            value: Any = raw
+            if is_str == "false":
+                try:
+                    value = json.loads(raw)
+                except json.JSONDecodeError:
+                    value = raw
+            args[key] = value
+        calls.append(
+            {
+                "name": name,
+                "args": args,
+                "id": f"call_{uuid.uuid4().hex[:12]}",
+                "type": "tool_call",
+            }
+        )
+    return calls
+
+
+def strip_dsml(text: str) -> str:
+    """Drop DSML markup, including an unfinished open tag at the end."""
+    if not text:
+        return ""
+    start = _open_index(text)
+    if start is not None:
+        return text[:start].rstrip()
+    held = _prefix_len(text)
+    return text[:-held].rstrip() if held else text
+
+
+def _open_index(text: str) -> int | None:
+    hits = [_ascii(text).find(tag) for tag in _OPENS]
+    found = [index for index in hits if index >= 0]
+    return min(found) if found else None
+
+
+def _prefix_len(text: str) -> int:
+    """Longest suffix of ``text`` that is a prefix of a DSML open tag."""
+    norm = _ascii(text)
+    best = 0
+    for tag in _OPENS:
+        limit = min(len(tag), len(norm))
+        for size in range(1, limit + 1):
+            if norm.endswith(tag[:size]):
+                best = max(best, size)
+    return best
+
+
+class DsmlFilter:
+    """Hold streamed deltas until they are either ordinary text or DSML markup."""
+
+    def __init__(self) -> None:
+        """Start with nothing held and nothing swallowed."""
+        self._held = ""
+        self._swallow = False
+
+    @property
+    def swallowed(self) -> bool:
+        """True once a real open tag arrived and the rest is markup."""
+        return self._swallow
+
+    @property
+    def markup(self) -> str:
+        """The swallowed block, for parsing. Empty while nothing has been swallowed."""
+        return self._held if self._swallow else ""
+
+    def push(self, delta: str) -> str:
+        """Return the visible slice of ``delta``; empty when it belongs to DSML."""
+        if not delta:
+            return ""
+        if self._swallow:
+            self._held += delta
+            return ""
+        self._held += delta
+        start = _open_index(self._held)
+        if start is not None:
+            visible = self._held[:start]
+            self._held = self._held[start:]
+            self._swallow = True
+            return visible
+        held = _prefix_len(self._held)
+        if not held:
+            visible, self._held = self._held, ""
+            return visible
+        visible, self._held = self._held[:-held], self._held[-held:]
+        return visible
+
+    def finish(self) -> str:
+        """Flush a prefix that never became markup. Swallowed DSML stays hidden."""
+        if self._swallow or "DSML" in _ascii(self._held):
+            self._swallow = True
+            return ""
+        visible, self._held = self._held, ""
+        return visible
+
+
+def _chunk_text(chunk: Any) -> str:
+    """The plain text of a chunk, or empty when its content is not a string."""
+    text = getattr(chunk, "text", None)
+    if isinstance(text, str) and text:
+        return text
+    content = getattr(chunk, "content", "")
+    return content if isinstance(content, str) else ""
+
+
+def _has_native_calls(chunk: Any) -> bool:
+    """True when the gateway did lift the call, leaving nothing to recover."""
+    return bool(getattr(chunk, "tool_calls", None) or getattr(chunk, "tool_call_chunks", None))
+
+
+async def recover_dsml_chunks(
+    chunks: AsyncIterator[AIMessageChunk],
+) -> AsyncIterator[AIMessageChunk]:
+    """Hide leaked markup mid-stream and close with the calls parsed out of it.
+
+    A delta that is entirely the start of an open tag is held back, because the next
+    one decides whether it was markup or a stray character. Held chunks are dropped
+    once later output carries them, and released unchanged when the block never
+    completed — a sentence ending in ``<`` is a sentence, not a tool call.
+    """
+    pending: list[AIMessageChunk] = []
+    filt = DsmlFilter()
+    last: AIMessageChunk | None = None
+    native = False
+    async for chunk in chunks:
+        last = chunk
+        if _has_native_calls(chunk):
+            held = filt.finish()
+            if held:
+                yield AIMessageChunk(content=held)
+            pending.clear()
+            native = True
+            yield chunk
+            continue
+        piece = _chunk_text(chunk)
+        visible = filt.push(piece)
+        if visible:
+            pending.clear()
+            yield chunk.model_copy(update={"content": visible}) if piece != visible else chunk
+        elif piece:
+            pending.append(chunk)
+    leftover = filt.finish()
+    if leftover:
+        yield AIMessageChunk(content=leftover)
+        return
+    if native:
+        return
+    calls = parse_dsml_tool_calls(filt.markup)
+    if not calls:
+        for held_chunk in pending:
+            yield held_chunk
+        return
+    yield AIMessageChunk(
+        content="",
+        tool_calls=calls,
+        id=getattr(last, "id", None),
+        response_metadata=getattr(last, "response_metadata", {}) or {},
+    )