deepwrap 0.1.3__tar.gz → 0.2.1__tar.gz

{deepwrap-0.1.3 → deepwrap-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: deepwrap
-Version: 0.1.3
+Version: 0.2.1
 Summary: Python SDK, CLI, and local FastAPI wrapper for DeepSeek Chat.
 Author-email: Nika Kudukhashvili <nikakuduxashvili0@gmail.com>
 Maintainer-email: Nika Kudukhashvili <nikakuduxashvili0@gmail.com>
@@ -327,6 +327,66 @@ The `ChatSession` keeps track of the latest message ID internally, so follow-up
 
 ---
 
+### Vision file uploads
+
+Files can be attached only to a `vision` session. DeepWrap uploads the file,
+waits for DeepSeek to process it, and forwards its file ID with the prompt.
+
+```python
+chat = client.chats.create_session(model="vision")
+
+response = chat.respond(
+    "Describe this image.",
+    files=["./photo.png"],
+    stream=False,
+)
+```
+
+You can also upload once and reuse the returned ID:
+
+```python
+uploaded = chat.upload_file("./photo.png")
+response = chat.respond("What is visible?", file_ids=[uploaded.id], stream=False)
+```
+
+### Pseudo function calling
+
+DeepWrap supplies tool definitions through a synthetic system protocol. The model
+either answers normally or returns a strict `<deepwrap_tool_call>` JSON envelope.
+Passing `functions` enables the automatic tool/result loop; omitting it returns the
+parsed call for execution by the application.
+
+```python
+from deepwrap import Tool
+
+add = Tool(
+    name="add",
+    description="Add two integers.",
+    parameters={
+        "type": "object",
+        "properties": {
+            "a": {"type": "integer"},
+            "b": {"type": "integer"},
+        },
+        "required": ["a", "b"],
+    },
+)
+
+result = chat.respond_with_tools(
+    "What is 20 + 22?",
+    [add],
+    functions={"add": lambda a, b: a + b},
+)
+
+print(result.content)
+print(result.tool_calls)
+```
+
+Tool calling is non-streaming because the complete envelope must be validated
+before a function can be selected or executed.
+
+---
+
 ## Supported Models
 
 DeepWrap currently supports:
@@ -337,6 +397,9 @@ default
 vision
 ```
 
+Web search is supported only by `default` (Instant). DeepWrap always sends
+`search_enabled=false` for `expert` and `vision`, even if `search=True` is passed.
+
 Example:
 
 ```python
@@ -385,6 +448,17 @@ Run the interactive terminal interface:
 deepwrap
 ```
 
+To attach an image in interactive mode:
+
+```text
+/model vision
+/attach ./photo.png
+Describe this image.
+```
+
+Use `/attachments` to inspect pending files and `/detach` to clear them. Pending
+attachments are consumed after the next successful response.
+
 Send a single message from the terminal:
 
 ```bash
@@ -504,7 +578,7 @@ Example response:
 {
   "ok": true,
   "app": "deepwrap",
-  "version": "0.1.3",
+  "version": "0.2.1",
   "token_configured": true,
   "cached_clients": 1,
   "active_sessions": 0

{deepwrap-0.1.3 → deepwrap-0.2.1}/README.md

@@ -272,6 +272,66 @@ The `ChatSession` keeps track of the latest message ID internally, so follow-up
 
 ---
 
+### Vision file uploads
+
+Files can be attached only to a `vision` session. DeepWrap uploads the file,
+waits for DeepSeek to process it, and forwards its file ID with the prompt.
+
+```python
+chat = client.chats.create_session(model="vision")
+
+response = chat.respond(
+    "Describe this image.",
+    files=["./photo.png"],
+    stream=False,
+)
+```
+
+You can also upload once and reuse the returned ID:
+
+```python
+uploaded = chat.upload_file("./photo.png")
+response = chat.respond("What is visible?", file_ids=[uploaded.id], stream=False)
+```
+
+### Pseudo function calling
+
+DeepWrap supplies tool definitions through a synthetic system protocol. The model
+either answers normally or returns a strict `<deepwrap_tool_call>` JSON envelope.
+Passing `functions` enables the automatic tool/result loop; omitting it returns the
+parsed call for execution by the application.
+
+```python
+from deepwrap import Tool
+
+add = Tool(
+    name="add",
+    description="Add two integers.",
+    parameters={
+        "type": "object",
+        "properties": {
+            "a": {"type": "integer"},
+            "b": {"type": "integer"},
+        },
+        "required": ["a", "b"],
+    },
+)
+
+result = chat.respond_with_tools(
+    "What is 20 + 22?",
+    [add],
+    functions={"add": lambda a, b: a + b},
+)
+
+print(result.content)
+print(result.tool_calls)
+```
+
+Tool calling is non-streaming because the complete envelope must be validated
+before a function can be selected or executed.
+
+---
+
 ## Supported Models
 
 DeepWrap currently supports:
@@ -282,6 +342,9 @@ default
 vision
 ```
 
+Web search is supported only by `default` (Instant). DeepWrap always sends
+`search_enabled=false` for `expert` and `vision`, even if `search=True` is passed.
+
 Example:
 
 ```python
@@ -330,6 +393,17 @@ Run the interactive terminal interface:
 deepwrap
 ```
 
+To attach an image in interactive mode:
+
+```text
+/model vision
+/attach ./photo.png
+Describe this image.
+```
+
+Use `/attachments` to inspect pending files and `/detach` to clear them. Pending
+attachments are consumed after the next successful response.
+
 Send a single message from the terminal:
 
 ```bash
@@ -449,7 +523,7 @@ Example response:
 {
   "ok": true,
   "app": "deepwrap",
-  "version": "0.1.3",
+  "version": "0.2.1",
   "token_configured": true,
   "cached_clients": 1,
   "active_sessions": 0

deepwrap-0.2.1/deepwrap/__init__.py

@@ -0,0 +1,4 @@
+from .client import Client
+from .function_calling import Tool, ToolCall, ToolResponse
+
+__all__ = ["Client", "Tool", "ToolCall", "ToolResponse"]

deepwrap-0.2.1/deepwrap/api/__init__.py

@@ -0,0 +1,10 @@
+from .pow import PowAPI
+from .chats import ChatsAPI
+from .files import FilesAPI, UploadedFile
+
+__all__ = [
+    "PowAPI",
+    "ChatsAPI",
+    "FilesAPI",
+    "UploadedFile",
+]

{deepwrap-0.1.3 → deepwrap-0.2.1}/deepwrap/api/chat_session.py

@@ -1,9 +1,19 @@
 import json
 
-from typing import Generator, Literal, Optional
+from pathlib import Path
+from typing import Callable, Generator, Literal, Mapping, Optional, Sequence
 
 from .base import BaseAPI
 from deepwrap.config import Config
+from deepwrap.function_calling import (
+    Tool,
+    ToolCall,
+    ToolResponse,
+    build_tool_prompt,
+    build_tool_result,
+    execute_tool_call,
+    parse_tool_calls,
+)
 
 
 ChunkKind = Literal["think", "response"]
@@ -77,6 +87,7 @@ class ChatSession(BaseAPI):
         prompt: str,
         thinking: bool = True,
         search: bool = True,
+        ref_file_ids: Optional[Sequence[str]] = None,
     ) -> Generator[tuple[ChunkKind, str], None, None]:
         """
         Send a prompt and stream structured response chunks.
@@ -104,14 +115,17 @@ class ChatSession(BaseAPI):
             prompt = "\n".join(Config.god_mode).format(prompt)
             self._is_god_mode_triggered = True
 
+        if ref_file_ids and self.model_type != "vision":
+            raise ValueError("File attachments are supported only by the vision model.")
+
         body = {
             "chat_session_id":   self.session_id,
             "parent_message_id": self._last_message_id,
             "model_type":        self.model_type if self._last_message_id is None else None,
             "prompt":            prompt,
-            "ref_file_ids":      [],
+            "ref_file_ids":      list(ref_file_ids or ()),
             "thinking_enabled":  thinking,
-            "search_enabled":    search,
+            "search_enabled":    search if self.model_type == "default" else False,
             "action":            None,
             "preempt":           False,
         }
@@ -215,6 +229,7 @@ class ChatSession(BaseAPI):
         prompt: str,
         thinking: bool = True,
         search: bool = True,
+        ref_file_ids: Optional[Sequence[str]] = None,
     ) -> Generator[str, None, None]:
         """
         Internal flat streaming generator.
@@ -242,6 +257,7 @@ class ChatSession(BaseAPI):
             prompt   = prompt,
             thinking = thinking,
             search   = search,
+            ref_file_ids = ref_file_ids,
         ):
             if kind != active_kind:
                 if active_kind == "think":
@@ -263,6 +279,8 @@ class ChatSession(BaseAPI):
         thinking: bool = True,
         search: bool = True,
         stream: bool = True,
+        files: Optional[Sequence[str | Path]] = None,
+        file_ids: Optional[Sequence[str]] = None,
     ) -> str | Generator[str, None, None]:
         """
         Send a prompt and return either a stream or the full response.
@@ -287,11 +305,18 @@ class ChatSession(BaseAPI):
                 - a `str` when `stream=False`
         """
 
+        resolved_file_ids = list(file_ids or ())
+        if files:
+            if self.model_type != "vision":
+                raise ValueError("File attachments are supported only by the vision model.")
+            resolved_file_ids.extend(self.upload_file(path).id for path in files)
+
         if stream:
             return self._respond_stream(
                 prompt   = prompt,
                 thinking = thinking,
                 search   = search,
+                ref_file_ids = resolved_file_ids,
             )
 
         return "".join(
@@ -299,5 +324,65 @@ class ChatSession(BaseAPI):
                 prompt   = prompt,
                 thinking = thinking,
                 search   = search,
+                ref_file_ids = resolved_file_ids,
+            )
+        )
+
+    def upload_file(self, path: str | Path, *, timeout: float = 60.0):
+        """Upload and process a file for use by this vision session."""
+
+        if self.model_type != "vision":
+            raise ValueError("File attachments are supported only by the vision model.")
+        return self._client.files.upload_and_wait(
+            path,
+            model=self.model_type,
+            timeout=timeout,
+        )
+
+    def respond_with_tools(
+        self,
+        prompt: str,
+        tools: Sequence[Tool],
+        *,
+        functions: Optional[Mapping[str, Callable[..., object]]] = None,
+        thinking: bool = True,
+        max_tool_rounds: int = 4,
+    ) -> ToolResponse:
+        """Ask for tool calls and optionally execute them until a final answer."""
+
+        if not tools:
+            raise ValueError("At least one tool definition is required.")
+        if max_tool_rounds < 1:
+            raise ValueError("max_tool_rounds must be at least 1.")
+
+        known_names = {tool.name for tool in tools}
+        message = build_tool_prompt(prompt, tools)
+        call_history: list[ToolCall] = []
+
+        for _ in range(max_tool_rounds):
+            response = "".join(
+                chunk
+                for kind, chunk in self.respond_structured(
+                    message,
+                    thinking=thinking,
+                    search=False,
+                )
+                if kind == "response"
             )
-        )
+            calls = parse_tool_calls(response)
+            if not calls:
+                return ToolResponse(content=response, tool_calls=tuple(call_history))
+            if len(calls) != 1:
+                raise ValueError("The model must return exactly one tool call per turn.")
+
+            call = calls[0]
+            if call.name not in known_names:
+                raise ValueError(f"Model requested an unknown tool: {call.name}")
+            call_history.append(call)
+            if functions is None:
+                return ToolResponse(content="", tool_calls=tuple(call_history))
+
+            result = execute_tool_call(call, functions)
+            message = build_tool_result(call, result)
+
+        raise RuntimeError(f"Tool-call loop exceeded {max_tool_rounds} rounds.")

deepwrap-0.2.1/deepwrap/api/files.py

@@ -0,0 +1,136 @@
+from __future__ import annotations
+
+import mimetypes
+import time
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Iterable
+
+from .base import BaseAPI
+from deepwrap.config import Config
+
+if TYPE_CHECKING:
+    from deepwrap.client import Client
+
+
+@dataclass(frozen=True)
+class UploadedFile:
+    """A file accepted and processed by DeepSeek."""
+
+    id: str
+    name: str
+    size: int
+    status: str
+    is_image: bool
+    model_kind: str
+
+
+class FilesAPI(BaseAPI):
+    """Upload files and wait for DeepSeek's asynchronous processing."""
+
+    UPLOAD_PATH = "/api/v0/file/upload_file"
+    UPLOAD_ENDPOINT = f"{Config.base_url}{UPLOAD_PATH}"
+    FETCH_ENDPOINT = f"{Config.base_url}{Config.api_prefix}/file/fetch_files"
+    FAILED_STATUSES = {
+        "FAILED",
+        "ERROR",
+        "REJECTED",
+        "CANCELLED",
+        "EXPIRED",
+    }
+
+    @staticmethod
+    def _unwrap(payload: dict[str, Any]) -> dict[str, Any]:
+        if payload.get("code") != 0:
+            raise RuntimeError(f"file request failed: {payload}")
+        data = payload.get("data", {})
+        if data.get("biz_code", 0) != 0:
+            raise RuntimeError(f"file request failed: {payload}")
+        return data.get("biz_data", {})
+
+    @staticmethod
+    def _to_uploaded_file(raw: dict[str, Any]) -> UploadedFile:
+        return UploadedFile(
+            id=str(raw["id"]),
+            name=str(raw.get("file_name", "")),
+            size=int(raw.get("file_size", 0)),
+            status=str(raw.get("status", "UNKNOWN")),
+            is_image=bool(raw.get("is_image", False)),
+            model_kind=str(raw.get("model_kind", "")),
+        )
+
+    def upload(self, path: str | Path, *, model: str = "vision") -> UploadedFile:
+        """Upload one local file and return its initial server record."""
+
+        file_path = Path(path).expanduser()
+        if not file_path.is_file():
+            raise FileNotFoundError(f"File does not exist: {file_path}")
+
+        size = file_path.stat().st_size
+        mime_type = mimetypes.guess_type(file_path.name)[0] or "application/octet-stream"
+        headers = {
+            "x-thinking-enabled": "true",
+            "x-model-type": model,
+            "x-file-size": str(size),
+            "x-ds-pow-response": self._client.pow.build_header(self.UPLOAD_PATH),
+        }
+        with file_path.open("rb") as handle:
+            response = self._post(
+                self.UPLOAD_ENDPOINT,
+                files={"file": (file_path.name, handle, mime_type)},
+                headers=headers,
+            )
+
+        response.raise_for_status()
+        return self._to_uploaded_file(self._unwrap(response.json()))
+
+    def fetch(self, file_ids: Iterable[str]) -> list[UploadedFile]:
+        """Fetch the current processing state for one or more file IDs."""
+
+        ids = [str(file_id) for file_id in file_ids]
+        if not ids:
+            return []
+        response = self._get(
+            self.FETCH_ENDPOINT,
+            params={"file_ids": ",".join(ids)},
+        )
+        response.raise_for_status()
+        raw = self._unwrap(response.json())
+        return [self._to_uploaded_file(item) for item in raw.get("files", [])]
+
+    def wait_until_ready(
+        self,
+        file_id: str,
+        *,
+        timeout: float = 60.0,
+        poll_interval: float = 0.5,
+    ) -> UploadedFile:
+        """Poll until a file succeeds, fails, or the timeout expires."""
+
+        deadline = time.monotonic() + timeout
+        while time.monotonic() < deadline:
+            records = self.fetch([file_id])
+            if records:
+                record = records[0]
+                status = record.status.upper()
+                if status == "SUCCESS":
+                    return record
+                if status in self.FAILED_STATUSES or status.endswith("_FAILED"):
+                    raise RuntimeError(
+                        f"File processing failed for {file_id}: {record.status}"
+                    )
+            time.sleep(poll_interval)
+        raise TimeoutError(f"Timed out waiting for file processing: {file_id}")
+
+    def upload_and_wait(
+        self,
+        path: str | Path,
+        *,
+        model: str = "vision",
+        timeout: float = 60.0,
+    ) -> UploadedFile:
+        """Upload a file and wait until it is ready for use in a prompt."""
+
+        uploaded = self.upload(path, model=model)
+        return self.wait_until_ready(uploaded.id, timeout=timeout)

{deepwrap-0.1.3 → deepwrap-0.2.1}/deepwrap/client.py

@@ -4,7 +4,7 @@ import uuid
 from typing import Optional
 
 from deepwrap.core import SessionManager, Auth
-from deepwrap.api import ChatsAPI, PowAPI
+from deepwrap.api import ChatsAPI, FilesAPI, PowAPI
 from deepwrap.api.chat_session import ChatSession
 from deepwrap.utils.config_store import ConfigStore
 from deepwrap.utils.bearer_token_extractor import BearerTokenExtractor
@@ -53,6 +53,7 @@ class Client:
 
         self.session       = SessionManager(bearer_token = bearer_token)
         self.pow           = PowAPI(self)
+        self.files         = FilesAPI(self)
         self.chats         = ChatsAPI(self)
 
         self._conversations: dict[str, ChatSession] = {}

{deepwrap-0.1.3 → deepwrap-0.2.1}/deepwrap/config.py

@@ -3,7 +3,7 @@ import os
 from dataclasses import dataclass, field
 from typing import Dict, Optional
 
-PROJECT_VERSION = "0.1.3"
+PROJECT_VERSION = "0.2.1"
 
 @dataclass(frozen=True)
 class Settings:

deepwrap-0.2.1/deepwrap/function_calling.py

@@ -0,0 +1,104 @@
+from __future__ import annotations
+
+import json
+import re
+
+from dataclasses import dataclass
+from typing import Any, Callable, Mapping, Sequence
+
+
+TOOL_CALL_PATTERN = re.compile(
+    r"<deepwrap_tool_call>\s*(\{.*?\})\s*</deepwrap_tool_call>", re.DOTALL
+)
+
+
+@dataclass(frozen=True)
+class Tool:
+    """Description of a callable function exposed to the model."""
+
+    name: str
+    description: str
+    parameters: dict[str, Any]
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            "name": self.name,
+            "description": self.description,
+            "parameters": self.parameters,
+        }
+
+
+@dataclass(frozen=True)
+class ToolCall:
+    name: str
+    arguments: dict[str, Any]
+
+
+@dataclass(frozen=True)
+class ToolResponse:
+    content: str
+    tool_calls: tuple[ToolCall, ...] = ()
+
+
+def build_tool_prompt(prompt: str, tools: Sequence[Tool]) -> str:
+    """Create the synthetic system protocol prepended to a user message."""
+
+    definitions = json.dumps(
+        [tool.as_dict() for tool in tools], ensure_ascii=False, separators=(",", ":")
+    )
+    return (
+        "[DEEPWRAP SYSTEM TOOL PROTOCOL]\n"
+        "You have access to the tools listed below. If a tool is required, reply "
+        "with exactly one call and no other text:\n"
+        '<deepwrap_tool_call>{"name":"tool_name","arguments":{}}</deepwrap_tool_call>\n'
+        "Arguments must be valid JSON and conform to the tool's parameters schema. "
+        "Never invent a tool. If no tool is required, answer the user normally and "
+        "do not emit a tool-call tag.\n"
+        f"TOOLS={definitions}\n"
+        "[END DEEPWRAP SYSTEM TOOL PROTOCOL]\n\n"
+        f"USER MESSAGE:\n{prompt}"
+    )
+
+
+def parse_tool_calls(text: str) -> tuple[ToolCall, ...]:
+    """Parse and validate DeepWrap tool-call envelopes from model output."""
+
+    calls: list[ToolCall] = []
+    for match in TOOL_CALL_PATTERN.finditer(text):
+        try:
+            payload = json.loads(match.group(1))
+        except json.JSONDecodeError as exc:
+            raise ValueError(f"Model returned invalid tool-call JSON: {exc}") from exc
+        name = payload.get("name")
+        arguments = payload.get("arguments", {})
+        if not isinstance(name, str) or not name:
+            raise ValueError("Tool call must contain a non-empty string 'name'.")
+        if not isinstance(arguments, dict):
+            raise ValueError("Tool call 'arguments' must be a JSON object.")
+        calls.append(ToolCall(name=name, arguments=arguments))
+    return tuple(calls)
+
+
+def execute_tool_call(
+    call: ToolCall, functions: Mapping[str, Callable[..., Any]]
+) -> Any:
+    """Execute a parsed call against an explicit name-to-callable mapping."""
+
+    function = functions.get(call.name)
+    if function is None:
+        raise ValueError(f"No function registered for tool: {call.name}")
+    return function(**call.arguments)
+
+
+def build_tool_result(call: ToolCall, result: Any) -> str:
+    """Serialize a tool result for the next model turn."""
+
+    encoded = json.dumps(result, ensure_ascii=False, default=str)
+    return (
+        "[DEEPWRAP TOOL RESULT]\n"
+        f"name={call.name}\n"
+        f"result={encoded}\n"
+        "Use this result to answer the original user request. Call another tool only "
+        "if it is necessary.\n"
+        "[END DEEPWRAP TOOL RESULT]"
+    )