Hybrid agents

README.md

@@ -4,6 +4,16 @@ https://github.com/user-attachments/assets/a5e34116-7853-43c2-ba93-2db811b8584a
 
 Production-ready open-source system for automated research using Schema-Guided Reasoning (SGR). Features real-time streaming responses, OpenAI-compatible API, and comprehensive research capabilities with agent interruption support.
 
+## 📊 Summary Table of Agents
+
+| Agent                   | SGR Implementation | ReasoningTool        | Tools                 | API Requests | Selection Mechanism |
+| ----------------------- | ------------------ | -------------------- | --------------------- | ------------ | ------------------- |
+| **1. SGR-Agent**        | Structured Output  | ❌ Built into schema | 6 basic               | 1            | SO Union Type       |
+| **2. FCAgent**          | ❌ Absent          | ❌ Absent            | 6 basic               | 1            | FC "required"       |
+| **3. HybridSGRAgent**   | FC Tool enforced   | ✅ First step FC     | 7 (6 + ReasoningTool) | 2            | FC → FC             |
+| **4. OptionalSGRAgent** | FC Tool optional   | ✅ At model’s choice | 7 (6 + ReasoningTool) | 1–2          | FC "auto"           |
+| **5. ReasoningFC_SO**   | FC → SO → FC auto  | ✅ FC enforced       | 7 (6 + ReasoningTool) | 3            | FC → SO → FC auto   |
+
 ## 👥 Open-Source Development Team
 
 This project is built by the community with pure enthusiasm as an open-source initiative:
@@ -94,7 +104,7 @@ client = OpenAI(
 
 # Make research request
 response = client.chat.completions.create(
-    model="sgr-research",
+    model="sgr-agent",
     messages=[{"role": "user", "content": "Research BMW X6 2025 prices in Russia"}],
     stream=True,
     temperature=0.4,
@@ -119,7 +129,7 @@ client = OpenAI(base_url="http://localhost:8010/v1", api_key="dummy")
 # Step 1: Initial research request
 print("Starting research...")
 response = client.chat.completions.create(
-    model="sgr-research",
+    model="sgr-agent",
     messages=[{"role": "user", "content": "Research AI market trends"}],
     stream=True,
     temperature=0,
@@ -195,7 +205,7 @@ The system provides a fully OpenAI-compatible API with advanced agent interrupti
 curl -X POST "http://localhost:8010/v1/chat/completions" \
   -H "Content-Type: application/json" \
   -d '{
-    "model": "sgr-research",
+    "model": "sgr-agent",
     "messages": [{"role": "user", "content": "Research BMW X6 2025 prices in Russia"}],
     "stream": true,
     "max_tokens": 1500,
@@ -213,7 +223,7 @@ When the agent needs clarification, it returns a unique agent ID in the streamin
 curl -X POST "http://localhost:8010/v1/chat/completions" \
   -H "Content-Type: application/json" \
   -d '{
-    "model": "sgr-research",
+    "model": "sgr-agent",
     "messages": [{"role": "user", "content": "Research AI market trends"}],
     "stream": true,
     "max_tokens": 1500,
@@ -293,7 +303,7 @@ sequenceDiagram
 
     Note over Client, Tools: SGR Deep Research - Agent Workflow
 
-    Client->>API: POST /v1/chat/completions<br/>{"model": "sgr-research", "messages": [...]}
+    Client->>API: POST /v1/chat/completions<br/>{"model": "sgr-agent", "messages": [...]}
 
     API->>Agent: Create new SGR Agent<br/>with unique ID
     Note over Agent: State: INITED
@@ -453,17 +463,23 @@ cp config.yaml.example config.yaml
 2. **Configure API keys:**
 
 ```yaml
+# SGR Research Agent - Configuration Template
+# Production-ready configuration for Schema-Guided Reasoning
+# Copy this file to config.yaml and fill in your API keys
+
 # OpenAI API Configuration
 openai:
   api_key: "your-openai-api-key-here"  # Required: Your OpenAI API key
   base_url: ""                         # Optional: Alternative URL (e.g., for proxy LiteLLM/vLLM)
   model: "gpt-4o-mini"                 # Model to use
   max_tokens: 8000                     # Maximum number of tokens
   temperature: 0.4                     # Generation temperature (0.0-1.0)
+  proxy: ""                            # Example: "socks5://127.0.0.1:1081" or "http://127.0.0.1:8080" or leave empty for no proxy
 
 # Tavily Search Configuration
 tavily:
   api_key: "your-tavily-api-key-here"  # Required: Your Tavily API key
+  api_base_url: "https://api.tavily.com"  # Tavily API base URL
 
 # Search Settings
 search:
@@ -479,12 +495,13 @@ scraping:
 execution:
   max_steps: 6                         # Maximum number of execution steps
   reports_dir: "reports"               # Directory for saving reports
+  logs_dir: "logs"                     # Directory for saving reports
 
 # Prompts Settings
 prompts:
-  prompts_dir: "prompts"           # Directory with prompts
+  prompts_dir: "prompts"               # Directory with prompts
   tool_function_prompt_file: "tool_function_prompt.txt"  # Tool function prompt file
-  system_prompt_file: "system_prompt.txt"               # System prompt file
+  system_prompt_file: "system_prompt.txt"  # System prompt file
 ```
 
 ### Server Configuration
@@ -494,6 +511,26 @@ prompts:
 python sgr_deep_research --host 127.0.0.1 --port 8080
 ```
 
+## 🤖 Available Agent Models
+
+### Agent Types Overview
+
+| Agent Model            | Description                        |
+| ---------------------- | ---------------------------------- |
+| `sgr-agent`            | Pure SGR (Schema-Guided Reasoning) |
+| `sgr-tools-agent`      | SGR + Function Calling hybrid      |
+| `sgr-auto-tools-agent` | SGR + Auto Function Calling        |
+| `sgr-so-tools-agent`   | SGR + Structured Output            |
+| `tools-agent`          | Pure Function Calling              |
+
+### Models Endpoint
+
+Get the list of available agent models:
+
+```bash
+curl http://localhost:8010/v1/models
+```
+
 ## 📝 Reports
 
 Research reports are automatically saved to the `reports/` directory in Markdown format:

config.yaml.example

@@ -14,6 +14,7 @@ openai:
 # Tavily Search Configuration
 tavily:
   api_key: "your-tavily-api-key-here"  # Required: Your Tavily API key
+  api_base_url: "https://api.tavily.com"  # Tavily API base URL
 
 # Search Settings
 search:
@@ -29,9 +30,10 @@ scraping:
 execution:
   max_steps: 6                         # Maximum number of execution steps
   reports_dir: "reports"               # Directory for saving reports
+  logs_dir: "logs"                     # Directory for saving reports
 
 # Prompts Settings
 prompts:
-  prompts_dir: "prompts"           # Directory with prompts
+  prompts_dir: "prompts"               # Directory with prompts
   tool_function_prompt_file: "tool_function_prompt.txt"  # Tool function prompt file
-  system_prompt_file: "system_prompt.txt"               # System prompt file
+  system_prompt_file: "system_prompt.txt"  # System prompt file

services/docker-compose.yml

@@ -11,6 +11,8 @@ services:
     volumes:
       - ../sgr_deep_research:/app/sgr_deep_research:ro
       - ../config.yaml:/app/config.yaml:ro
+      -  ./logs:/app/logs
+      -  ./reports:/app/reports
 
     healthcheck:
       test: ["CMD", "curl", "-f", "http://localhost:8010/health"]

sgr_deep_research/api/endpoints.py

@@ -5,21 +5,23 @@
 from fastapi.responses import StreamingResponse
 
 from sgr_deep_research.api.models import (
+    AGENT_MODEL_MAPPING,
     AgentListItem,
     AgentListResponse,
+    AgentModel,
     AgentStateResponse,
     ChatCompletionRequest,
     HealthResponse,
 )
-from sgr_deep_research.core.agent import SGRResearchAgent
+from sgr_deep_research.core.agents import BaseAgent
 from sgr_deep_research.core.models import AgentStatesEnum
 
 logger = logging.getLogger(__name__)
 
 app = FastAPI(title="SGR Deep Research API", version="1.0.0")
 
 # ToDo: better to move to a separate service
-agents_storage: dict[str, SGRResearchAgent] = {}
+agents_storage: dict[str, BaseAgent] = {}
 
 
 @app.get("/health", response_model=HealthResponse)
@@ -35,8 +37,8 @@ async def get_agent_state(agent_id: str):
     agent = agents_storage[agent_id]
 
     current_state_dict = None
-    if agent._context.current_state:
-        current_state_dict = agent._context.current_state.model_dump()
+    if agent._context.current_state_reasoning:
+        current_state_dict = agent._context.current_state_reasoning.model_dump()
 
     return AgentStateResponse(
         agent_id=agent.id,
@@ -58,6 +60,18 @@ async def get_agents_list():
     return AgentListResponse(agents=agents_list, total=len(agents_list))
 
 
+@app.get("/v1/models")
+async def get_available_models():
+    """Get list of available agent models."""
+    return {
+        "data": [
+            {"id": model.value, "object": "model", "created": 1234567890, "owned_by": "sgr-deep-research"}
+            for model in AgentModel
+        ],
+        "object": "list",
+    }
+
+
 def extract_user_content_from_messages(messages):
     for message in reversed(messages):
         if message.role == "user":
@@ -96,22 +110,52 @@ async def provide_clarification(agent_id: str, request: ChatCompletionRequest):
         raise HTTPException(status_code=500, detail="str(e)")
 
 
+def _is_agent_id(model_str: str) -> bool:
+    """Check if model string is an agent ID (contains underscore and UUID-like
+    format)."""
+    return "_" in model_str and len(model_str) > 20
+
+
 @app.post("/v1/chat/completions")
 async def create_chat_completion(request: ChatCompletionRequest):
     if not request.stream:
         raise HTTPException(status_code=501, detail="Only streaming responses are supported. Set 'stream=true'")
+
+    # Check if this is a clarification request for an existing agent
     if (
         request.model
+        and isinstance(request.model, str)
+        and _is_agent_id(request.model)
         and request.model in agents_storage
-        and agents_storage[request.model].state == AgentStatesEnum.WAITING_FOR_CLARIFICATION
+        and agents_storage[request.model]._context.state == AgentStatesEnum.WAITING_FOR_CLARIFICATION
     ):
         return await provide_clarification(request.model, request)
+
     try:
         task = extract_user_content_from_messages(request.messages)
-        agent = SGRResearchAgent(task=task)
 
+        # Determine agent model type
+        agent_model = request.model
+        if isinstance(agent_model, str) and _is_agent_id(agent_model):
+            # If it's an agent ID but not found in storage, use default
+            agent_model = AgentModel.SGR_AGENT
+        elif agent_model is None:
+            agent_model = AgentModel.SGR_AGENT
+        elif isinstance(agent_model, str):
+            # Try to convert string to AgentModel enum
+            try:
+                agent_model = AgentModel(agent_model)
+            except ValueError:
+                raise HTTPException(
+                    status_code=400,
+                    detail=f"Invalid model '{agent_model}'. Available models: {[m.value for m in AgentModel]}",
+                )
+
+        # Create agent using mapping
+        agent_class = AGENT_MODEL_MAPPING[agent_model]
+        agent = agent_class(task=task)
         agents_storage[agent.id] = agent
-        logger.info(f"Agent {agent.id} created and stored for task: {task[:100]}...")
+        logger.info(f"Agent {agent.id} ({agent_model.value}) created and stored for task: {task[:100]}...")
 
         _ = asyncio.create_task(agent.execute())
         return StreamingResponse(
@@ -121,11 +165,12 @@ async def create_chat_completion(request: ChatCompletionRequest):
                 "Cache-Control": "no-cache",
                 "Connection": "keep-alive",
                 "X-Agent-ID": str(agent.id),
+                "X-Agent-Model": agent_model.value,
             },
         )
 
     except ValueError as e:
         raise HTTPException(status_code=400, detail=str(e))
     except Exception as e:
         logger.error(f"Error completion: {e}")
-        raise HTTPException(status_code=500, detail="str(e)")
+        raise HTTPException(status_code=500, detail=str(e))