deepy-cli 0.1.1__py3-none-any.whl

deepy/data/tools/AskUserQuestion.md

@@ -0,0 +1,10 @@
+## AskUserQuestion
+
+Ask the user only when progress is blocked by missing intent or a required decision.
+
+Args: `questions` (non-empty array). Each question needs `question` and non-empty `options`;
+each option needs `label` and may include `description`. Use `multiSelect=true` only when
+multiple choices are allowed.
+
+Returns standard JSON with `awaitUserResponse=true`, `metadata.kind="ask_user_question"`,
+and normalized questions.

deepy/data/tools/WebFetch.md

@@ -0,0 +1,9 @@
+## WebFetch
+
+Fetch a specific web page when the user provides a complete URL.
+
+Args: `url`.
+
+Accepts only complete `http://` or `https://` URLs. Returns the final URL, title,
+content type, and extracted readable text for HTML pages. Use `WebSearch` to
+discover URLs; use `WebFetch` when the URL is already known.

deepy/data/tools/WebSearch.md

@@ -0,0 +1,9 @@
+## WebSearch
+
+Search when current or external information is required.
+
+Args: `query`.
+
+Uses the configured local command first, then configured API endpoint if present. If
+neither is configured, uses Deepy's built-in local web search implementation and
+returns parsed search result titles, URLs, and snippets.

deepy/data/tools/__init__.py

@@ -0,0 +1 @@
+"""Built-in tool documentation."""

deepy/data/tools/bash.md

@@ -0,0 +1,7 @@
+## bash
+
+Run shell commands for inspection, tests, builds, and project operations.
+
+Args: `command`, optional `timeout_ms`.
+
+Runs in the session cwd, preserves cwd between calls, and returns stdout/stderr JSON.

deepy/data/tools/edit.md

@@ -0,0 +1,13 @@
+## edit
+
+Replace existing text after reading the file first.
+
+Prefer `edit` over `write` for existing files when changing specific code, tests, imports,
+comments, blocks, or lines; it keeps changes scoped and reviewable.
+
+Args: `path`, `old`, `new`, optional `replace_all`, optional `snippet_id`.
+
+The file must be read first. Stale files are rejected. Repeated matches are rejected unless
+`replace_all` is true; candidate snippets can be reused with `snippet_id`. If exact text is
+missing, simple over-escaping may be corrected or closest-match metadata returned. Success
+includes diff metadata.

deepy/data/tools/modify.md

@@ -0,0 +1,17 @@
+## modify
+
+Create new files or edit existing files.
+
+Use `content` only when the target file does not exist. For existing files, read the
+file first, then use `old_string` and `new_string` for the smallest reliable
+replacement. Do not rewrite an existing scaffolded file with full content; replace the
+specific generated block instead.
+
+Args for new files: `file_path`, `content`.
+
+Args for existing files: `file_path`, `old_string`, `new_string`, optional
+`replace_all`, optional `snippet_id`.
+
+Existing files must be read before editing. Stale edits are rejected. Repeated matches
+are rejected unless `replace_all` is true; candidate snippets can be reused with
+`snippet_id`. Success includes diff metadata.

deepy/data/tools/read.md

@@ -0,0 +1,8 @@
+## read
+
+Inspect files or list directories before changes.
+
+Args: `path`, optional `start_line`, `limit`.
+
+Text output includes line numbers. Directory output lists entries. Reads record file state so
+later `modify` calls can detect stale changes.

deepy/data/tools/write.md

@@ -0,0 +1,12 @@
+## write
+
+Create a new file or explicit whole-file replacement.
+
+Prefer `edit` over `write` for existing targeted changes: code, tests, imports,
+comments, blocks, or lines. Do not rewrite an existing file just because final content
+is known; preserve surrounding user changes with `edit`.
+
+Args: `path`, `content` (complete file content).
+
+Existing files must be read first. If rejected for unread state, read and usually switch
+to `edit` unless a full rewrite was requested. Stale writes are rejected. Success includes diff.

deepy/errors.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True)
+class ErrorDisplay:
+    category: str
+    detail: str
+    hint: str = ""
+
+
+def classify_error(error: BaseException | str) -> ErrorDisplay:
+    text = str(error).strip()
+    normalized = text.casefold()
+    status = _status_code(error)
+
+    if status in {401, 403} or any(token in normalized for token in ("unauthorized", "forbidden")):
+        return ErrorDisplay(
+            category="api_auth",
+            detail=text or "API authentication failed.",
+            hint="Check the API key with `deepy config setup`.",
+        )
+    if status in {408, 429, 500, 502, 503, 504} or any(
+        token in normalized
+        for token in ("timeout", "timed out", "connection", "network", "dns", "temporarily")
+    ):
+        return ErrorDisplay(
+            category="network",
+            detail=text or "Network request failed.",
+            hint="Retry later or check base_url and network connectivity.",
+        )
+    if any(token in normalized for token in ("tool", "functiontool", "max_turns", "run failed")):
+        return ErrorDisplay(
+            category="sdk_tool_failure",
+            detail=text or "Agent or tool execution failed.",
+            hint="Check the tool output above or rerun with debug logging enabled.",
+        )
+    if any(token in normalized for token in ("api_key", "api key", "config", "toml")):
+        return ErrorDisplay(
+            category="config",
+            detail=text or "Deepy configuration is incomplete.",
+            hint="Run `deepy config setup`.",
+        )
+    return ErrorDisplay(category="unknown", detail=text or error.__class__.__name__)
+
+
+def format_error_display(error: BaseException | str) -> str:
+    display = classify_error(error)
+    if display.category == "unknown" and not display.hint:
+        return display.detail
+    hint = f" Hint: {display.hint}" if display.hint else ""
+    return f"{display.category}: {display.detail}{hint}"
+
+
+def _status_code(error: Any) -> int | None:
+    value = getattr(error, "status_code", None)
+    if isinstance(value, int):
+        return value
+    response = getattr(error, "response", None)
+    response_value = getattr(response, "status_code", None)
+    return response_value if isinstance(response_value, int) else None

deepy/llm/__init__.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+from .context import build_session_input_callback
+from .events import DeepyStreamEvent, normalize_stream_event
+from .thinking import build_model_settings, build_thinking_extra_body
+
+__all__ = [
+    "DeepyStreamEvent",
+    "build_model_settings",
+    "build_session_input_callback",
+    "build_thinking_extra_body",
+    "normalize_stream_event",
+]

deepy/llm/agent.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from deepy.config import Settings
+from deepy.prompts import build_system_prompt
+from deepy.skills import SkillInfo
+from deepy.tools import ToolRuntime
+from deepy.tools.agents import build_function_tools
+
+from .provider import ProviderBundle, build_provider_bundle
+
+
+def build_deepy_agent(
+    settings: Settings,
+    runtime: ToolRuntime,
+    *,
+    project_root: Path,
+    provider: ProviderBundle | None = None,
+    loaded_skills: list[SkillInfo] | None = None,
+):
+    from agents import Agent
+
+    provider = provider or build_provider_bundle(settings)
+    return Agent(
+        name="Deepy",
+        instructions=build_system_prompt(project_root, settings, loaded_skills=loaded_skills),
+        model=provider.model,
+        model_settings=provider.model_settings,
+        tools=build_function_tools(runtime),
+    )

deepy/llm/context.py

@@ -0,0 +1,109 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from math import ceil
+from typing import Any
+
+from deepy.config import Settings
+from deepy.utils import json as json_utils
+
+try:
+    import tiktoken
+except Exception:  # pragma: no cover - optional dependency fallback.
+    tiktoken = None  # type: ignore[assignment]
+
+_ENCODING = None
+
+
+def estimate_tokens_for_text(text: str) -> int:
+    if not text:
+        return 0
+    encoding = _token_encoding()
+    if encoding is not None:
+        return max(1, len(encoding.encode(text)))
+    return max(1, ceil(len(text) / 4))
+
+
+def estimate_tokens_for_item(item: Any) -> int:
+    if isinstance(item, str):
+        return estimate_tokens_for_text(item)
+    if isinstance(item, dict):
+        return estimate_tokens_for_text(json_utils.dumps(item))
+    if isinstance(item, list):
+        return sum(estimate_tokens_for_item(part) for part in item)
+    return estimate_tokens_for_text(str(item))
+
+
+def estimate_tokens_for_items(items: list[dict[str, Any]]) -> int:
+    return sum(estimate_tokens_for_item(item) for item in items)
+
+
+def compact_items_for_context(
+    history: list[dict[str, Any]],
+    new_input: list[dict[str, Any]],
+    *,
+    threshold_tokens: int,
+) -> list[dict[str, Any]]:
+    combined = history + new_input
+    if estimate_tokens_for_items(combined) <= threshold_tokens:
+        return combined
+
+    recent: list[dict[str, Any]] = []
+    recent_tokens = estimate_tokens_for_items(new_input)
+    budget = max(threshold_tokens - _compact_notice_token_budget(), 1)
+
+    for item in reversed(history):
+        item_tokens = estimate_tokens_for_item(item)
+        if recent and recent_tokens + item_tokens > budget:
+            break
+        if recent_tokens + item_tokens > budget:
+            continue
+        recent.insert(0, item)
+        recent_tokens += item_tokens
+
+    omitted = len(history) - len(recent)
+    if omitted <= 0:
+        return recent + new_input
+
+    notice = {
+        "role": "system",
+        "content": (
+            "Earlier conversation history was compacted by Deepy to fit the configured context "
+            f"window. Omitted history items: {omitted}. Continue using the remaining recent "
+            "history and the current user request."
+        ),
+    }
+    return [notice] + recent + new_input
+
+
+def build_session_input_callback(settings: Settings) -> Callable[
+    [list[dict[str, Any]], list[dict[str, Any]]],
+    list[dict[str, Any]],
+]:
+    threshold = settings.context.resolved_compact_threshold
+
+    def callback(history: list[dict[str, Any]], new_input: list[dict[str, Any]]) -> list[dict[str, Any]]:
+        return compact_items_for_context(
+            history,
+            new_input,
+            threshold_tokens=threshold,
+        )
+
+    return callback
+
+
+def _compact_notice_token_budget() -> int:
+    return 80
+
+
+def _token_encoding() -> Any | None:
+    global _ENCODING
+    if _ENCODING is not None:
+        return _ENCODING
+    if tiktoken is None:
+        return None
+    try:
+        _ENCODING = tiktoken.get_encoding("cl100k_base")
+    except Exception:
+        return None
+    return _ENCODING

deepy/llm/events.py

@@ -0,0 +1,187 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+StreamKind = Literal[
+    "text_delta",
+    "reasoning_delta",
+    "reasoning_item",
+    "tool_call",
+    "tool_output",
+    "message",
+    "agent_updated",
+    "usage",
+    "raw_response",
+    "unknown",
+]
+
+TEXT_DELTA_TYPES = {
+    "",
+    "response.output_text.delta",
+    "response.refusal.delta",
+}
+REASONING_DELTA_TYPES = {
+    "response.reasoning_summary_text.delta",
+    "response.reasoning_text.delta",
+}
+
+
+@dataclass(frozen=True)
+class DeepyStreamEvent:
+    kind: StreamKind
+    text: str = ""
+    name: str = ""
+    payload: dict[str, Any] = field(default_factory=dict)
+
+
+def normalize_stream_event(event: Any) -> DeepyStreamEvent | None:
+    event_type = getattr(event, "type", None)
+    if event_type == "raw_response_event":
+        data = getattr(event, "data", None)
+        data_type = getattr(data, "type", "")
+        delta = _raw_delta(event)
+        if data_type in REASONING_DELTA_TYPES and delta:
+            return DeepyStreamEvent(kind="reasoning_delta", text=delta, payload={"raw": data})
+        if delta and data_type in TEXT_DELTA_TYPES:
+            return DeepyStreamEvent(kind="text_delta", text=delta)
+        if delta:
+            return DeepyStreamEvent(
+                kind="raw_response",
+                name=str(data_type or ""),
+                text=delta,
+                payload={"raw": data},
+            )
+        if data_type == "response.completed":
+            usage = _response_usage(data)
+            return DeepyStreamEvent(
+                kind="usage",
+                payload={"usage": usage, "raw": data},
+            )
+        return DeepyStreamEvent(kind="raw_response", name=str(data_type or ""), payload={"raw": data})
+
+    if event_type == "agent_updated_stream_event":
+        agent = getattr(event, "new_agent", None)
+        name = getattr(agent, "name", "") if agent is not None else ""
+        return DeepyStreamEvent(kind="agent_updated", name=name, text=name)
+
+    if event_type != "run_item_stream_event":
+        return DeepyStreamEvent(kind="unknown", name=str(event_type or ""), payload={"event": event})
+
+    item = getattr(event, "item", None)
+    name = getattr(event, "name", "")
+    if name == "tool_called":
+        tool_name = _tool_name(item)
+        return DeepyStreamEvent(
+            kind="tool_call",
+            name=tool_name,
+            text=tool_name,
+            payload={"call_id": _call_id(item), "arguments": _tool_arguments(item)},
+        )
+    if name == "tool_output":
+        output = getattr(item, "output", "")
+        return DeepyStreamEvent(
+            kind="tool_output",
+            name=_tool_name(item),
+            text=output if isinstance(output, str) else str(output),
+            payload={"call_id": _call_id(item)},
+        )
+    if name == "message_output_created":
+        text = _message_text(item)
+        return DeepyStreamEvent(kind="message", text=text)
+    if name == "reasoning_item_created":
+        return DeepyStreamEvent(kind="reasoning_item", payload={"item": item})
+
+    return DeepyStreamEvent(kind="unknown", name=str(name), payload={"item": item})
+
+
+def _raw_delta(event: Any) -> str:
+    data = getattr(event, "data", None)
+    delta = getattr(data, "delta", None)
+    if isinstance(delta, str):
+        return delta
+    return ""
+
+
+def _response_usage(data: Any) -> Any:
+    response = getattr(data, "response", None)
+    usage = getattr(response, "usage", None)
+    return _to_payload(usage)
+
+
+def _to_payload(value: Any) -> Any:
+    if value is None or isinstance(value, (str, int, float, bool, list, dict)):
+        return value
+    model_dump = getattr(value, "model_dump", None)
+    if callable(model_dump):
+        return model_dump()
+    if hasattr(value, "__dict__"):
+        return dict(value.__dict__)
+    return value
+
+
+def _tool_name(item: Any) -> str:
+    if item is None:
+        return ""
+    tool_name = getattr(item, "tool_name", None)
+    if isinstance(tool_name, str) and tool_name:
+        return tool_name
+    raw_item = getattr(item, "raw_item", None)
+    if isinstance(raw_item, dict):
+        value = raw_item.get("name")
+        return value if isinstance(value, str) else ""
+    value = getattr(raw_item, "name", "")
+    return value if isinstance(value, str) else ""
+
+
+def _tool_arguments(item: Any) -> str:
+    if item is None:
+        return ""
+    arguments = getattr(item, "arguments", None)
+    if isinstance(arguments, str):
+        return arguments
+    raw_item = getattr(item, "raw_item", None)
+    if isinstance(raw_item, dict):
+        value = raw_item.get("arguments")
+        if isinstance(value, str):
+            return value
+        function = raw_item.get("function")
+        if isinstance(function, dict):
+            value = function.get("arguments")
+            return value if isinstance(value, str) else ""
+        return ""
+    value = getattr(raw_item, "arguments", None)
+    if isinstance(value, str):
+        return value
+    function = getattr(raw_item, "function", None)
+    value = getattr(function, "arguments", None)
+    return value if isinstance(value, str) else ""
+
+
+def _call_id(item: Any) -> str:
+    if item is None:
+        return ""
+    call_id = getattr(item, "call_id", None)
+    if isinstance(call_id, str):
+        return call_id
+    raw_item = getattr(item, "raw_item", None)
+    if isinstance(raw_item, dict):
+        value = raw_item.get("call_id") or raw_item.get("id")
+        return str(value) if value is not None else ""
+    value = getattr(raw_item, "call_id", None) or getattr(raw_item, "id", None)
+    return str(value) if value is not None else ""
+
+
+def _message_text(item: Any) -> str:
+    raw_item = getattr(item, "raw_item", None)
+    content = getattr(raw_item, "content", None)
+    if isinstance(content, str):
+        return content
+    if isinstance(content, list):
+        parts: list[str] = []
+        for part in content:
+            text = part.get("text") if isinstance(part, dict) else getattr(part, "text", "")
+            if isinstance(text, str):
+                parts.append(text)
+        return "".join(parts)
+    return ""

deepy/llm/model_capabilities.py

@@ -0,0 +1,7 @@
+from __future__ import annotations
+
+DEEPSEEK_V4_MODELS = frozenset({"deepseek-v4-pro", "deepseek-v4-flash"})
+
+
+def defaults_to_thinking_mode(model: str) -> bool:
+    return model in DEEPSEEK_V4_MODELS

deepy/llm/provider.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from agents import OpenAIChatCompletionsModel
+
+from deepy.config import Settings
+
+from .replay import (
+    sanitize_chat_completion_stream_event,
+    sanitize_model_input_for_chat_completions,
+    sanitize_model_response_output,
+)
+
+
+@dataclass(frozen=True)
+class ProviderBundle:
+    client: object
+    model: object
+    model_settings: object
+
+
+class DeepyOpenAIChatCompletionsModel(OpenAIChatCompletionsModel):
+    async def get_response(self, *args: Any, **kwargs: Any) -> Any:
+        response = await super().get_response(*args, **kwargs)
+        response.output = sanitize_model_response_output(response.output)
+        return response
+
+    async def stream_response(self, *args: Any, **kwargs: Any) -> Any:
+        async for event in super().stream_response(*args, **kwargs):
+            sanitized = sanitize_chat_completion_stream_event(event)
+            if sanitized is not None:
+                yield sanitized
+
+    async def _fetch_response(
+        self,
+        system_instructions: str | None,
+        input: Any,
+        *args: Any,
+        **kwargs: Any,
+    ) -> Any:
+        return await super()._fetch_response(
+            system_instructions,
+            sanitize_model_input_for_chat_completions(input),
+            *args,
+            **kwargs,
+        )
+
+
+def should_replay_deepseek_reasoning_content(context: object) -> bool:
+    model = str(getattr(context, "model", "")).lower()
+    if "deepseek" not in model:
+        return False
+
+    reasoning = getattr(context, "reasoning", None)
+    origin_model = getattr(reasoning, "origin_model", None)
+    provider_data = getattr(reasoning, "provider_data", {}) or {}
+    return (
+        isinstance(origin_model, str)
+        and "deepseek" in origin_model.lower()
+    ) or provider_data == {}
+
+
+def build_provider_bundle(settings: Settings) -> ProviderBundle:
+    from agents import set_tracing_disabled
+    from openai import AsyncOpenAI
+
+    from .thinking import build_model_settings
+
+    if not settings.model.api_key:
+        raise ValueError(f"DeepSeek API key is missing in {settings.path or 'Deepy config'}.")
+
+    set_tracing_disabled(disabled=True)
+    client = AsyncOpenAI(base_url=settings.model.base_url, api_key=settings.model.api_key)
+    model = DeepyOpenAIChatCompletionsModel(
+        model=settings.model.name,
+        openai_client=client,
+        should_replay_reasoning_content=should_replay_deepseek_reasoning_content,
+    )
+    return ProviderBundle(client=client, model=model, model_settings=build_model_settings(settings))