feat: OpenAI 兼容层工具调用增强 (tool_choice / parallel_tool_calls / strict) (#6)

* feat(openai): add tool_choice and parallel_tool_calls to request model

- Add tool_choice and parallel_tool_calls fields to ChatCompletionRequest
- Implement _preprocess_tools() for tool filtering based on tool_choice
- Update convert_messages_to_prompt() signature with new params
- Update route.py call site to pass new parameters
- Add degradation logging for tool_choice mismatches

* feat(openai): add JSON Schema block, Strict Mode paragraph, and dynamic REMINDER assembly

* tests(openai): add TDD tests for tool_choice, parallel_tool_calls, and strict mode

* docs: document tool_choice, parallel_tool_calls, and strict in OpenAI adapter README

* smoke(openai): add smoke tests for tool_choice, parallel_tool_calls, and strict mode

* fix(logging): move security warnings to FastAPI startup event to avoid duplicate logs in reload mode

Author: NIyueeE

README.md

@@ -118,8 +118,12 @@ OpenAI-compatible chat completions endpoint with full tool calling support and s
 | `messages` | array | OpenAI-style message array |
 | `stream` | bool | Streaming response, default `false` |
 | `tools` | array | Tool definitions for function calling |
+| `tool_choice` | string \| object | Controls which tools the model may call. Values: `"auto"` (default), `"none"` (disable tools), `"required"` (must call at least one tool), or `{"type": "function", "function": {"name": "..."}}` (call a specific tool). This parameter is proxy-layer only and not forwarded to DeepSeek. |
+| `parallel_tool_calls` | bool | Whether to allow parallel tool calls. Default `true`. When `false`, the model is instructed to call only one tool at a time. This parameter is proxy-layer only and not forwarded to DeepSeek. |
 | `extra_body` | dict | DeepSeek-specific parameters (see below) |
 
+> **Note on `tools`**: Each tool supports a `strict` property inside `function` (e.g., `{"type": "function", "function": {"name": "...", "strict": true}}`). When `strict: true`, the model is instructed to strictly follow the JSON Schema — do not add undefined fields, do not omit required fields, do not use values outside enum lists. Both natural language description and JSON Schema block are included in the prompt for maximum constraint fidelity.
+
 **DeepSeek-specific parameters via `extra_body`**:
 
 | Parameter | Type | Default | Description |

README.中文.md

@@ -118,8 +118,12 @@ OpenAI兼容的对话完成接口，完全支持工具调用和流式响应。
 | `messages` | array | OpenAI 风格消息数组 |
 | `stream` | bool | 流式响应，默认为 `false` |
 | `tools` | array | 函数调用工具定义 |
+| `tool_choice` | string \| object | 控制模型可以调用哪些工具。值：`"auto"`（默认）、`"none"`（禁用工具）、`"required"`（必须至少调用一个工具）、或 `{"type": "function", "function": {"name": "..."}}`（调用指定工具）。此参数仅在代理层使用，不会转发给 DeepSeek。 |
+| `parallel_tool_calls` | bool | 是否允许并行工具调用。默认为 `true`。设为 `false` 时，模型将被指示每次只调用一个工具。此参数仅在代理层使用，不会转发给 DeepSeek。 |
 | `extra_body` | dict | DeepSeek 特有参数（见下方） |
 
+> **关于 `tools` 的说明**：每个工具在 `function` 对象内支持 `strict` 属性（如 `{"type": "function", "function": {"name": "...", "strict": true}}`）。当 `strict: true` 时，模型将被指示严格遵循 JSON Schema——不添加未定义的字段、不省略必填字段、不使用枚举列表以外的值。提示中会同时包含自然语言描述和 JSON Schema 代码块，以获得最大的约束保真度。
+
 **通过 `extra_body` 传递 DeepSeek 特有参数**：
 
 | 参数 | 类型 | 默认值 | 说明 |

src/deepseek_web_api/__init__.py

@@ -3,11 +3,9 @@
 from .api.routes import app
 from .api.openai import models_router, chat_completions_router
 from .core.logger import setup_logger
-from .core.server_security import log_startup_security_warnings
 
 # Setup centralized logger (level configured in config.toml or default WARNING)
 setup_logger()
-log_startup_security_warnings()
 
 # Include OpenAI compatible routers
 app.include_router(models_router)

src/deepseek_web_api/api/openai/chat_completions/messages.py

@@ -1,10 +1,60 @@
 """Message conversion utilities for OpenAI-style messages to DeepSeek prompt."""
 
 import json
+import logging
 from typing import List, Optional, Union
 
 from .tools import TOOL_START_MARKER, TOOL_END_MARKER
 
+logger = logging.getLogger(__name__)
+
+
+def _preprocess_tools(tools: Optional[List[dict]], tool_choice: Union[str, dict]) -> tuple[Optional[List[dict]], dict]:
+    """Preprocess tools based on tool_choice.
+
+    Returns: (effective_tools, tool_choice_info)
+    - effective_tools: filtered list, or None if tools should not be exposed
+    - tool_choice_info: dict with keys:
+        - degraded: bool
+        - reason: str (None, "no_tools_available", "tool_not_found", "invalid_value")
+        - missing_name: str (only if reason == "tool_not_found")
+    """
+    info: dict = {"degraded": False, "reason": None, "missing_name": None}
+
+    # Handle "none" - tools explicitly disabled
+    if tool_choice == "none":
+        return None, info
+
+    # Handle "auto" or "required" - use all tools as-is
+    if tool_choice == "auto":
+        return tools, info
+
+    if tool_choice == "required":
+        if not tools:
+            info["degraded"] = True
+            info["reason"] = "no_tools_available"
+        return tools if tools else None, info
+
+    # Handle specific tool selection via dict
+    if isinstance(tool_choice, dict):
+        func_spec = tool_choice.get("function")
+        if func_spec and isinstance(func_spec, dict):
+            name = func_spec.get("name")
+            if name and tools:
+                for t in tools:
+                    if t.get("function", {}).get("name") == name:
+                        return [t], info
+                # Tool not found
+                info["degraded"] = True
+                info["reason"] = "tool_not_found"
+                info["missing_name"] = name
+                return None, info
+
+    # Invalid tool_choice value - degrade but preserve original tools
+    info["degraded"] = True
+    info["reason"] = "invalid_value"
+    return tools, info
+
 
 def extract_text_content(content: Union[str, List, None]) -> str:
     """Extract plain text from OpenAI message content field.
@@ -27,19 +77,36 @@ def extract_text_content(content: Union[str, List, None]) -> str:
     return ""
 
 
-def convert_messages_to_prompt(messages: List[dict], tools: Optional[List[dict]] = None) -> str:
+def convert_messages_to_prompt(
+    messages: List[dict],
+    tools: Optional[List[dict]] = None,
+    tool_choice: Union[str, dict] = "auto",
+    parallel_tool_calls: bool = True,
+) -> str:
     """Convert OpenAI-style messages array to DeepSeek prompt format.
 
     Args:
         messages: List of OpenAI-style messages with role and content
         tools: Optional OpenAI tools specification
+        tool_choice: Controls which tools the model may call (default "auto")
+        parallel_tool_calls: Whether to allow parallel tool calls (default True)
 
     Returns:
         Formatted prompt string for DeepSeek API
     """
     prompt_parts = []
     system_parts = []
 
+    # Preprocess tools based on tool_choice
+    effective_tools, tool_choice_info = _preprocess_tools(tools, tool_choice)
+
+    # Log degradation if any
+    if tool_choice_info["degraded"]:
+        logger.warning(
+            f"[messages] tool_choice degraded: reason={tool_choice_info['reason']}, "
+            f"missing_name={tool_choice_info.get('missing_name')}"
+        )
+
     for msg in messages:
         role = msg.get("role", "")
         content = msg.get("content")
@@ -75,9 +142,9 @@ def convert_messages_to_prompt(messages: List[dict], tools: Optional[List[dict]]
             prompt_parts.append(f"\nTool: id={tool_id}\n```\n{text}\n```")
 
     # Inject tools into system instruction
-    if tools:
+    if effective_tools:
         tools_lines = []
-        for t in tools:
+        for t in effective_tools:
             func = t.get('function', {})
             name = func.get('name')
             desc = func.get('description') or ''
@@ -103,7 +170,15 @@ def convert_messages_to_prompt(messages: List[dict], tools: Optional[List[dict]]
                 if not params.get('additionalProperties', True):
                     param_desc += "\n  Note: Additional parameters are not allowed."
 
-            tools_lines.append(f"- {name}: {desc}{param_desc}")
+            schema_json = ""
+            if params:
+                schema_json = "\n```json\n" + json.dumps(params, ensure_ascii=False) + "\n```\n"
+
+            strict_notice = ""
+            if func.get('strict', False):
+                strict_notice = "\n**Strict Mode**: Function calls MUST exactly match the specified schema. Do NOT add fields not defined, do not omit required fields, do not use values outside enum list."
+
+            tools_lines.append(f"- {name}: {desc}{schema_json}{param_desc}{strict_notice}")
 
         tools_prompt = "## Available Tools\n" + "\n".join(tools_lines)
         tools_prompt += """
@@ -127,8 +202,25 @@ def convert_messages_to_prompt(messages: List[dict], tools: Optional[List[dict]]
     if system_parts:
         prompt_parts.insert(0, "[System Instruction]\n" + "\n---\n".join(system_parts) + "\n---")
 
-    # Add separator and REMINDER before Assistant output if tools are available
-    if tools:
-        prompt_parts.append("\n---\nAbove is our conversation history.\n\n[REMINDER] When you need to call tools, you MUST use the [TOOL🛠️]...[/TOOL🛠️] tags. For multiple tool calls, wrap them in a JSON array: [TOOL🛠️][{\"name\": \"func1\", \"arguments\": {...}}, {\"name\": \"func2\", \"arguments\": {...}}][/TOOL🛠️].")
+    # Add separator and REMINDER before Assistant output
+    if effective_tools is not None:
+        reminder_parts = ["When you need to call tools, you MUST use the [TOOL🛠️]...[/TOOL🛠️] tags."]
+
+        if tool_choice == "required":
+            reminder_parts.append("**You MUST call at least one tool before responding.**")
+
+        if not parallel_tool_calls and not (tool_choice_info["degraded"] and tool_choice_info["reason"] == "tool_not_found"):
+            reminder_parts.append("**Call only ONE tool at a time.**")
+
+        reminder_text = " ".join(reminder_parts)
+        prompt_parts.append(f"\n---\nAbove is our conversation history.\n\n[REMINDER] {reminder_text}")
+
+    elif effective_tools is None and tool_choice_info["degraded"]:
+        reason = tool_choice_info["reason"]
+        if reason == "no_tools_available":
+            prompt_parts.append("\n---\nAbove is our conversation history.\n\n[REMINDER] The requested tool operation requires available tools, but none were provided. Inform the user that no tools are available.")
+        elif reason == "tool_not_found":
+            missing = tool_choice_info.get("missing_name", "the requested tool")
+            prompt_parts.append(f"\n---\nAbove is our conversation history.\n\n[REMINDER] The requested tool \"{missing}\" is not available. Inform the user that this tool is not available.")
 
     return "\n\n".join(prompt_parts)

src/deepseek_web_api/api/openai/chat_completions/route.py

@@ -4,7 +4,7 @@
 import json
 import time
 import uuid
-from typing import List, Optional
+from typing import List, Optional, Union
 
 from fastapi import APIRouter, Request, HTTPException
 from fastapi.responses import StreamingResponse, JSONResponse
@@ -34,11 +34,17 @@ class ChatCompletionRequest(BaseModel):
                 "thinking_enabled": False,
             }
         )
+
+    Proxy-layer parameters (not forwarded to DeepSeek):
+        - tool_choice: Controls which tools the model may call (default "auto")
+        - parallel_tool_calls: Whether to allow parallel tool calls (default True)
     """
     model: str = "deepseek-web-chat"
     messages: List[dict]
     stream: bool = False
     tools: Optional[List[dict]] = None
+    tool_choice: Optional[Union[str, dict]] = "auto"
+    parallel_tool_calls: Optional[bool] = True
     extra_body: Optional[dict] = None
 
 
@@ -71,7 +77,12 @@ async def chat_completions(request: Request):
 
     validated = ChatCompletionRequest(**data)
     logger.debug(f"Request payload: {json.dumps(data, ensure_ascii=False, indent=2)}")
-    prompt = convert_messages_to_prompt(validated.messages, validated.tools)
+    prompt = convert_messages_to_prompt(
+        validated.messages,
+        validated.tools,
+        validated.tool_choice,
+        validated.parallel_tool_calls,
+    )
     logger.debug(f"Constructed prompt:\n{prompt}")
 
     # Extract DeepSeek-specific parameters from extra_body

src/deepseek_web_api/api/routes.py

@@ -2,7 +2,7 @@
 
 from fastapi import FastAPI, HTTPException, Request, Response
 from fastapi.middleware.cors import CORSMiddleware
-from fastapi.responses import JSONResponse
+from fastapi.responses import JSONResponse, StreamingResponse
 
 from ..core.config import (
     get_cors_allow_credentials,
@@ -11,9 +11,9 @@
     get_cors_origin_regex,
     get_cors_origins,
 )
-from ..core.logger import logger
 from ..core.local_api_auth import requires_local_api_auth, verify_local_api_auth
-from fastapi.responses import StreamingResponse
+from ..core.logger import logger
+from ..core.server_security import log_startup_security_warnings
 
 from .v0_service import (
     stream_chat_completion,
@@ -45,6 +45,12 @@ def get_cors_middleware_options() -> dict:
 app.add_middleware(CORSMiddleware, **get_cors_middleware_options())
 
 
+@app.on_event("startup")
+async def startup_security_warnings():
+    """Log security warnings once when the server worker starts."""
+    log_startup_security_warnings()
+
+
 @app.middleware("http")
 async def local_api_auth_middleware(request: Request, call_next):
     """Protect /v0 and /v1 endpoints with optional local API key auth."""