fix: support local models by making thought field optional in Plan model (#601)

- Make thought field optional in Plan model to fix Pydantic validation errors with local models
- Add Ollama configuration example to conf.yaml.example
- Update documentation to include local model support
- Improve planner prompt with better JSON format requirements

Fixes local model integration issues where models like qwen3:14b would fail
due to missing thought field in JSON output.

Co-authored-by: Willem Jiang <willem.jiang@gmail.com>

README.md

@@ -95,6 +95,7 @@ cp .env.example .env
 
 # Configure conf.yaml for your LLM model and API keys
 # Please refer to 'docs/configuration_guide.md' for more details
+# For local development, you can use Ollama or other local models
 cp conf.yaml.example conf.yaml
 
 # Install marp for ppt generation

conf.yaml.example

@@ -13,6 +13,16 @@ BASIC_MODEL:
   # max_retries: 3 # Maximum number of retries for LLM calls
   # verify_ssl: false  # Uncomment this line to disable SSL certificate verification for self-signed certificates
 
+# Local model configuration example:
+
+# Ollama (Tested and supported for local development)
+# BASIC_MODEL:
+#   base_url: "http://localhost:11434/v1"  # Ollama OpenAI compatible endpoint
+#   model: "qwen3:14b"  # or "llama3.2", etc.
+#   api_key: "ollama"  # Ollama doesn't need real API key
+#   max_retries: 3
+#   verify_ssl: false  # Local deployment usually doesn't need SSL verification
+
 # To use Google Ai Studio as your basic platform:
 # BASIC_MODEL:
 #   platform: "google_aistudio"

docs/configuration_guide.md

@@ -17,6 +17,14 @@ In DeerFlow, we currently only support non-reasoning models. This means models l
 
 `doubao-1.5-pro-32k-250115`, `gpt-4o`, `qwen-max-latest`,`qwen3-235b-a22b`,`qwen3-coder`, `gemini-2.0-flash`, `deepseek-v3`, and theoretically any other non-reasoning chat models that implement the OpenAI API specification.
 
+### Local Model Support
+
+DeerFlow supports local models through OpenAI-compatible APIs:
+
+- **Ollama**: `http://localhost:11434/v1` (tested and supported for local development)
+
+See the `conf.yaml.example` file for detailed configuration examples.
+
 > [!NOTE]
 > The Deep Research process requires the model to have a **longer context window**, which is not supported by all models.
 > A work-around is to set the `Max steps of a research plan` to `2` in the settings dialog located on the top right corner of the web page,

src/prompts/planner.md

@@ -153,7 +153,11 @@ When planning information gathering, consider these key aspects and ensure COMPR
 
 # Output Format
 
-Directly output the raw JSON format of `Plan` without "```json". The `Plan` interface is defined as follows:
+**CRITICAL: You MUST output a valid JSON object that exactly matches the Plan interface below. Do not include any text before or after the JSON. Do not use markdown code blocks. Output ONLY the raw JSON.**
+
+**IMPORTANT: The JSON must contain ALL required fields: locale, has_enough_context, thought, title, and steps. Do not return an empty object {}.**
+
+The `Plan` interface is defined as follows:
 
 ```ts
 interface Step {
@@ -172,6 +176,24 @@ interface Plan {
 }
 ```
 
+**Example Output:**
+```json
+{
+  "locale": "en-US",
+  "has_enough_context": false,
+  "thought": "To understand the current market trends in AI, we need to gather comprehensive information about recent developments, key players, and market dynamics.",
+  "title": "AI Market Research Plan",
+  "steps": [
+    {
+      "need_search": true,
+      "title": "Current AI Market Analysis",
+      "description": "Collect data on market size, growth rates, major players, and investment trends in AI sector.",
+      "step_type": "research"
+    }
+  ]
+}
+```
+
 # Notes
 
 - Focus on information gathering in research steps - delegate all calculations to processing steps

src/prompts/planner_model.py

@@ -27,7 +27,7 @@ class Plan(BaseModel):
         ..., description="e.g. 'en-US' or 'zh-CN', based on the user's language"
     )
     has_enough_context: bool
-    thought: str
+    thought: str = Field(default="", description="Thinking process for the plan")
     title: str
     steps: List[Step] = Field(
         default_factory=list,