diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..e61df5e --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,99 @@ +# Introduction + +**In this project, we follow the principle of "Code over Conversations" and recommend that all newcomers adhere to this approach as well.** + +We believe that the best discussions arise around working code, not abstract ideas. Here you don't need to ask for permission or go through quests to create tasks. Just start β€” and your Pull Request will become the best beginning for discussion. + +## Now let's break it down point by point... + +![Alt text](docs/dev_workflow.png "Optional Title") + +### **Have an idea and want to implement something?** + +``` +Your path will look like this: +1. Clone the repository to your local machine +2. Create and switch to your branch +3. Sync and create a PR with [WIP] prefix +4. In the description, write what and why you're doing it +5. Make your changes +6. Push to your remote branch +7. Update the PR +``` + +______________________________________________________________________ + +![Alt text](docs/idea_workflow.png "Optional Title") + +### **Have an idea you just want to share?** + +``` +Your path will look like this: +1. Go to the "Issues" tab +2. Create an issue and start the discussion +3. Communicate your idea with the community +``` + +______________________________________________________________________ + +![Alt text](docs/works_workflow.png "Optional Title") + +### **Or just want to build something manually...** + +``` +Your path will look like this: +1. Go to the "Issues" tab +2. Choose a task that interests you +3. Clone the repository +4. Create your branch +5. Switch to it +6. Sync and create a PR with [WIP] prefix +7. In the description, write what and why you're doing it +8. Make your changes +9. Push to your remote branch +10. Update the PR +``` + +______________________________________________________________________ + +### Review process for any code you want to merge + +``` +- Maintainers and community will provide feedback in comments +- Make changes and push to the same branch β€” PR will update +- When everything is ready, remove [WIP] from the title +- After approval and passing tests, the PR will be merged +``` + +______________________________________________________________________ + +### Code requirements + +``` +- Code follows project style // we use PEP8 +- Tests added (if applicable) +- Documentation updated +- All tests pass +- Description clearly explains the changes +``` + +______________________________________________________________________ + +### Project protection + +``` +- `main` branch is protected β€” only maintainers can merge +- All changes go through code review and automatic checks +- Branches are automatically deleted after PR merge +``` + +______________________________________________________________________ + +### Communication + +``` +All communication takes place in several places: +- "Issues" tab + relevant topic +- PR + relevant request +- TG group @sgr-community +``` diff --git a/README.md b/README.md index 794c7bb..3a5cee8 100644 --- a/README.md +++ b/README.md @@ -1,700 +1,52 @@ -# 🧠 SGR Deep Research - Open-Source Schema-Guided Reasoning System +# SGR Deep Research - Open-Source Schema-Guided Reasoning System -## SGR Deep Research is an agent-driven research system with a chat interface. It is can run with small LLMs for a fully local mode. +## Description -This project is developed by the **neuraldeep** community. It is inspired by the Schema-Guided Reasoning (SGR) work and [SGR Agent Demo](https://abdullin.com/schema-guided-reasoning/demo) delivered by "LLM Under the Hood" community and AI R&D Hub of [TIMETOACT GROUP Γ–sterreich](https://www.timetoact-group.at) - -If you have any questions - feel free to reach out to [Valerii Kovalskii](https://www.linkedin.com/in/vakovalskii/). - -Web Interface Video - -https://github.com/user-attachments/assets/9e1c46c0-0c13-45dd-8b35-a3198f946451 - -Terminal CLI Video - -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. tool_calling_agent** | ❌ Absent | ❌ Absent | 6 basic | 1 | FC "required" | -| **3. sgr_tool_calling_agent** | FC Tool enforced | βœ… First step FC | 7 (6 + ReasoningTool) | 2 | FC β†’ FC TOP AGENT | -| **4. sgr_auto_tool_calling_agent** | FC Tool optional | βœ… At model's choice | 7 (6 + ReasoningTool) | 1–2 | FC "auto" | -| **5. sgr_so_tool_calling_agent** | 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: - -- **SGR Concept Creator**: [@abdullin](https://t.me/llm_under_hood) - Original Schema-Guided Reasoning concept -- **Project Coordinator & Vision**: [@VaKovaLskii](https://t.me/neuraldeep) - Team coordination and project direction -- **Lead Core Developer**: [@virrius](https://t.me/virrius_tech) - Complete system rewrite and core implementation -- **API Development**: [Pavel Zloi](https://t.me/evilfreelancer) - OpenAI-compatible API layer -- **Hybrid FC Mode**: [@Shadekss](https://t.me/Shadekss) - Dmitry Sirakov \[Shade\] - SGR integration into Function Calling for Agentic-capable models -- **DevOps & Deployment**: [@mixaill76](https://t.me/mixaill76) - Infrastructure and build management - -*All development is driven by pure enthusiasm and open-source community collaboration. We welcome contributors of all skill levels!* - -## πŸš€ Quick Start - -### Prerequisites - -First, install UV (modern Python package manager): - -```bash -# Install UV -curl -LsSf https://astral.sh/uv/install.sh | sh -# or on Windows: -# powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" -``` - -### Local Development - -```bash -# 1. Setup configuration -cp config.yaml.example config.yaml -# Edit config.yaml with your API keys - -# 2. Change to src directory and install dependencies -uv sync - -# 3. Run the server -uv run python sgr_deep_research -``` - -### Docker Deployment - -```bash -# 1. Setup configuration -cp config.yaml.example config.yaml -# Edit config.yaml with your API keys - -# 2. Go to the services folder -cd services - -# 3. Building docker images -docker-compose build - -# 4. Deploy with Docker Compose -docker-compose up -d - -# 3. Check health -curl http://localhost:8010/health -``` - -______________________________________________________________________ - -## πŸ“š Integration & Examples - -
-πŸš€ Python OpenAI Client Examples - Complete integration guide with streaming & clarifications - -Simple Python examples for using OpenAI client with SGR Deep Research system. - -## Prerequisites - -```bash -pip install openai -``` - -## Example 1: Basic Research Request - -Simple research query without clarifications. - -```python -from openai import OpenAI - -# Initialize client -client = OpenAI( - base_url="http://localhost:8010/v1", - api_key="dummy", # Not required for local server -) - -# Make research request -response = client.chat.completions.create( - model="sgr_agent", - messages=[{"role": "user", "content": "Research BMW X6 2025 prices in Russia"}], - stream=True, - temperature=0.4, -) - -# Print streaming response -for chunk in response: - if chunk.choices[0].delta.content: - print(chunk.choices[0].delta.content, end="") -``` - -## Example 2: Research with Clarification Support - -Handle agent clarification requests and continue conversation. - -```python -import json -from openai import OpenAI - -client = OpenAI(base_url="http://localhost:8010/v1", api_key="dummy") +![SGR Concept Architecture](docs/sgr_concept.png) +Open-source framework for building intelligent research agents using Schema-Guided Reasoning. The project provides a core library with a extendable BaseAgent interface implementing a two-phase architecture and multiple ready-to-use research agent implementations built on top of it. -# Step 1: Initial research request -print("Starting research...") -response = client.chat.completions.create( - model="sgr_agent", - messages=[{"role": "user", "content": "Research AI market trends"}], - stream=True, - temperature=0, -) - -agent_id = None -clarification_questions = [] - -# Process streaming response -for chunk in response: - # Extract agent ID from model field - if chunk.model and chunk.model.startswith("sgr_agent_"): - agent_id = chunk.model - print(f"\nAgent ID: {agent_id}") - - # Check for clarification requests - if chunk.choices[0].delta.tool_calls: - for tool_call in chunk.choices[0].delta.tool_calls: - if tool_call.function and tool_call.function.name == "clarification": - args = json.loads(tool_call.function.arguments) - clarification_questions = args.get("questions", []) - - # Print content - if chunk.choices[0].delta.content: - print(chunk.choices[0].delta.content, end="") - -# Step 2: Handle clarification if needed -if clarification_questions and agent_id: - print(f"\n\nClarification needed:") - for i, question in enumerate(clarification_questions, 1): - print(f"{i}. {question}") - - # Provide clarification - clarification = "Focus on LLM market trends for 2024-2025, global perspective" - print(f"\nProviding clarification: {clarification}") - - # Continue with agent ID - response = client.chat.completions.create( - model=agent_id, # Use agent ID as model - messages=[{"role": "user", "content": clarification}], - stream=True, - temperature=0, - ) - - # Print final response - for chunk in response: - if chunk.choices[0].delta.content: - print(chunk.choices[0].delta.content, end="") - -print("\n\nResearch completed!") -``` - -## Usage Notes - -- Replace `localhost:8010` with your server URL -- The `api_key` can be any string for local server -- Agent ID is returned in the `model` field during streaming -- Clarification questions are sent via `tool_calls` with function name `clarification` -- Use the agent ID as model name to continue conversation - -
+The library includes extensible tools for search, reasoning, and clarification, real-time streaming responses, OpenAI-compatible REST API. Works with any OpenAI-compatible LLM, including local models for fully private research. ______________________________________________________________________ -
-⚑ cURL API Examples - Direct HTTP requests with agent interruption & clarification flow - -The system provides a fully OpenAI-compatible API with advanced agent interruption and clarification capabilities. - -### Basic Research Request - -```bash -curl -X POST "http://localhost:8010/v1/chat/completions" \ - -H "Content-Type: application/json" \ - -d '{ - "model": "sgr_agent", - "messages": [{"role": "user", "content": "Research BMW X6 2025 prices in Russia"}], - "stream": true, - "max_tokens": 1500, - "temperature": 0.4 - }' -``` - -### πŸ”„ Agent Interruption & Clarification Flow - -When the agent needs clarification, it returns a unique agent ID in the streaming response model field. You can then continue the conversation using this agent ID. - -#### Step 1: Initial Request - -```bash -curl -X POST "http://localhost:8010/v1/chat/completions" \ - -H "Content-Type: application/json" \ - -d '{ - "model": "sgr_agent", - "messages": [{"role": "user", "content": "Research AI market trends"}], - "stream": true, - "max_tokens": 1500, - "temperature": 0 - }' -``` - -#### Step 2: Agent Requests Clarification - -The streaming response includes the agent ID in the model field: - -```json -{ - "model": "sgr_agent_b84d5a01-c394-4499-97be-dad6a5d2cb86", - "choices": [{ - "delta": { - "tool_calls": [{ - "function": { - "name": "clarification", - "arguments": "{\"questions\":[\"Which specific AI market segment are you interested in (LLM, computer vision, robotics)?\", \"What time period should I focus on (2024, next 5 years)?\", \"Are you looking for global trends or specific geographic regions?\", \"Do you need technical analysis or business/investment perspective?\"]}" - } - }] - } - }] -} -``` - -#### Step 3: Continue with Agent ID +## Documentation -```bash -curl -X POST "http://localhost:8010/v1/chat/completions" \ - -H "Content-Type: application/json" \ - -d '{ - "model": "sgr_agent_b84d5a01-c394-4499-97be-dad6a5d2cb86", - "messages": [{"role": "user", "content": "Focus on LLM market trends for 2024-2025, global perspective, business analysis"}], - "stream": true, - "max_tokens": 1500, - "temperature": 0 - }' -``` +> **Get started quickly with our documentation:** -### Agent Management - -```bash -# Get all active agents -curl http://localhost:8010/agents - -# Get specific agent state -curl http://localhost:8010/agents/{agent_id}/state - -# Direct clarification endpoint -curl -X POST "http://localhost:8010/agents/{agent_id}/provide_clarification" \ - -H "Content-Type: application/json" \ - -d '{ - "messages": [{"role": "user", "content": "Focus on luxury models only"}], - "stream": true - }' -``` - -
+- **[Project Wiki](https://github.com/vamplabAI/sgr-deep-research/wiki)** - Complete project documentation +- **[Quick Start Guide](https://github.com/vamplabAI/sgr-deep-research/wiki/SGR-Quick-Start)** - Get up and running in minutes +- **[API Documentation](https://github.com/vamplabAI/sgr-deep-research/wiki/SGR-Description-API)** - REST API reference with examples ______________________________________________________________________ -## πŸ“Š SGR Agent Workflow - -### Agent Execution Sequence - -The following diagram shows the complete SGR agent workflow with interruption and clarification support: - -```mermaid -sequenceDiagram - participant Client - participant API as FastAPI Server - participant Agent as SGR Agent - participant LLM as LLM - participant Tools as Research Tools - - Note over Client, Tools: SGR Deep Research - Agent Workflow - - Client->>API: POST /v1/chat/completions
{"model": "sgr_agent", "messages": [...]} - - API->>Agent: Create new SGR Agent
with unique ID - Note over Agent: State: INITED - - Agent->>Agent: Initialize context
and conversation history - - loop SGR Reasoning Loop (max 6 steps) - Agent->>Agent: Prepare tools based on
current context limits - Agent->>LLM: Structured Output Request
with NextStep schema - - LLM-->>API: Streaming chunks - API-->>Client: SSE stream with
agent_id in model field - - LLM->>Agent: Parsed NextStep result - - alt Tool: Clarification - Note over Agent: State: WAITING_FOR_CLARIFICATION - Agent->>Tools: Execute clarification tool - Tools->>API: Return clarifying questions - API-->>Client: Stream clarification questions - - Client->>API: POST /v1/chat/completions
{"model": "agent_id", "messages": [...]} - API->>Agent: provide_clarification() - Note over Agent: State: RESEARCHING - Agent->>Agent: Add clarification to context - - else Tool: GeneratePlan - Agent->>Tools: Execute plan generation - Tools->>Agent: Research plan created - - else Tool: WebSearch - Agent->>Tools: Execute web search - Tools->>Tools: Tavily API call - Tools->>Agent: Search results + sources - Agent->>Agent: Update context with sources - - else Tool: AdaptPlan - Agent->>Tools: Execute plan adaptation - Tools->>Agent: Updated research plan - - else Tool: CreateReport - Agent->>Tools: Execute report creation - Tools->>Tools: Generate comprehensive
report with citations - Tools->>Agent: Final research report - - else Tool: ReportCompletion - Note over Agent: State: COMPLETED - Agent->>Tools: Execute completion - Tools->>Agent: Task completion status - end - - Agent->>Agent: Add tool result to
conversation history - API-->>Client: Stream tool execution result - - break Task Completed - Agent->>Agent: Break execution loop - end - end +## Benchmarking - Agent->>API: Finish streaming - API-->>Client: Close SSE stream +![SimpleQA Benchmark Comparison](docs/simpleqa_benchmark_comparison.png) - Note over Client, Tools: Agent remains accessible
via agent_id for further clarifications -``` - -### Schema-Guided Reasoning Capabilities: - -1. **πŸ€” Clarification** - clarifying questions when unclear -2. **πŸ“‹ Plan Generation** - research plan creation -3. **πŸ” Web Search** - internet information search -4. **πŸ”„ Plan Adaptation** - plan adaptation based on results -5. **πŸ“ Report Creation** - detailed report creation -6. **βœ… Completion** - task completion - -## 🧠 SGR vs Function Calling: When to Use Each Approach - -### The Problem with Function Calling on Local Models (ReAct Agents) - -**Reality Check:** Function Calling works great on OpenAI/Anthropic (80+ [BFCL](https://gorilla.cs.berkeley.edu/leaderboard.html) scores) but fails dramatically on local models \<32B parameters when using true ReAct agents with `tool_mode="auto"`, where the model itself decides when to call tools. - -**BFCL Benchmark Results for Qwen3 Models:** - -- `Qwen3-8B (FC)`: Only 15% accuracy in Agentic Web Search mode ([BFCL](https://gorilla.cs.berkeley.edu/leaderboard.html) benchmark) -- `Qwen3-4B (FC)`: Only 2% accuracy in Agentic Web Search mode -- `Qwen3-1.7B (FC)`: Only 4.5% accuracy in Agentic Web Search mode -- Even with native FC support, smaller models struggle with deciding **WHEN** to call tools -- Common result: `{"tool_calls": null, "content": "Text instead of tool call"}` - -**Note:** Our team is currently working on creating a specialized benchmark for SGR vs ReAct performance on smaller models. Initial testing confirms that the SGR pipeline enables even smaller models to follow complex task workflows. - -### SGR Solution: Forced Reasoning β†’ Deterministic Execution - -```python -# Phase 1: Structured Output reasoning (100% reliable) -reasoning = model.generate(format="json_schema") -# {"action": "search", "query": "BMW X6 prices", "reason": "need current data"} - -# Phase 2: Deterministic execution (no model uncertainty) -result = execute_plan(reasoning.actions) -``` - -### Architecture by Model Size - -| Model Size | Recommended Approach | FC Accuracy | Why Choose This | -| ---------- | ---------------------------- | ----------- | ----------------------- | -| **\<14B** | Pure SGR + Structured Output | 15-25% | FC practically unusable | -| **14-32B** | SGR + FC hybrid | 45-65% | Best of both worlds | -| **32B+** | Native FC with SGR fallback | 85%+ | FC works reliably | - -### When to Use SGR vs Function Calling - -| Use Case | Best Approach | Why | -| ------------------------------- | ---------------- | ------------------------------------------------ | -| **Data analysis & structuring** | SGR | Controlled reasoning with visibility | -| **Document processing** | SGR | Step-by-step analysis with justification | -| **Local models (\<32B)** | SGR | Forces reasoning regardless of model limitations | -| **Multi-agent systems** | Function Calling | Native agent interruption support | -| **External API interactions** | Function Calling | Direct tool access pattern | -| **Production monitoring** | SGR | All reasoning steps visible and loggable | - -### Real-World Results - -**Initial Testing Results:** - -- SGR enables even small models to follow structured workflows -- SGR pipeline provides deterministic execution regardless of model size -- SGR forces reasoning steps that ReAct leaves to model discretion - -**Planned Benchmarking:** - -- We're developing a comprehensive benchmark comparing SGR vs ReAct across model sizes -- Initial testing shows promising results for SGR on models as small as 4B parameters -- Full metrics and performance comparison coming soon - -### Hybrid Approach: The Best of Both Worlds - -The optimal solution for many production systems is a hybrid approach: - -1. **SGR for decision making** - Determine which tools to use -2. **Function Calling for execution** - Get data and provide agent-like experience -3. **SGR for final processing** - Structure and format results - -This hybrid approach works particularly well for models in the 14-32B range, where Function Calling works sometimes but isn't fully reliable. - -**Bottom Line:** Don't force \<32B models to pretend they're GPT-4o in ReAct-style agentic workflows with `tool_mode="auto"`. Let them think structurally through SGR, then execute deterministically. - -## βš™οΈ Configuration - -### Setup Configuration File - -1. **Create config.yaml from template:** - -```bash -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: - max_results: 10 # Maximum number of search results - -# Scraping Settings -scraping: - enabled: false # Enable full text scraping of found pages - max_pages: 5 # Maximum pages to scrape per search - content_limit: 1500 # Character limit for full content per source - -# Execution Settings -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 - tool_function_prompt_file: "tool_function_prompt.txt" # Tool function prompt file - system_prompt_file: "system_prompt.txt" # System prompt file -``` - -### Server Configuration - -```bash -# Custom host and port -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_tool_calling_agent` | SGR + Function Calling hybrid | -| `sgr_auto_tool_calling_agent` | SGR + Auto Function Calling | -| `sgr_so_tool_calling_agent` | SGR + Structured Output | -| `tool_calling_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: - -``` -reports/YYYYMMDD_HHMMSS_Task_Name.md -``` - -### Report Structure - -- πŸ“‹ **Executive Summary** - Key insights overview -- πŸ” **Technical Analysis** - Detailed findings with citations -- πŸ“Š **Key Findings** - Main conclusions -- πŸ“Ž **Sources** - All reference links - -### Example Report - -See `docs/example_report.md` for a complete sample of SGR research output. - -______________________________________________________________________ - -## πŸ“Š Benchmarking with SimpleQA - -We conducted a comprehensive benchmark evaluation using the [SimpleQA](https://huggingface.co/datasets/basicv8vc/SimpleQA) dataset - a factuality benchmark that measures the ability of language models to answer short, fact-seeking questions. - -### Our Benchmark Results - -![SimpleQA Benchmark Comparison](assets/simpleqa_benchmark_comparison.png) - -**Performance Metrics:** +**Performance Metrics on gpt-4.1-mini:** - **Accuracy:** 86.08% - **Correct:** 3,724 answers - **Incorrect:** 554 answers - **Not Attempted:** 48 answers -**For detailed information** about benchmark configuration, how to run it, and technical details, see the **[Benchmark Documentation](benchmark/simpleqa_benchmark_results.md)**. +More detailed benchmark results are available [here](benchmark/simpleqa_benchmark_results.md). ______________________________________________________________________ -
-πŸ› οΈ Advanced Integration Examples - Production-ready code for streaming, monitoring & state management - -### Python Client - -```python -import httpx - - -async def research_query(query: str): - async with httpx.AsyncClient() as client: - async with client.stream( - "POST", - "http://localhost:8010/v1/chat/completions", - json={"messages": [{"role": "user", "content": query}], "stream": True}, - ) as response: - async for chunk in response.aiter_text(): - print(chunk, end="") -``` - -### Curl with Streaming - -```bash -curl -N -X POST "http://localhost:8010/v1/chat/completions" \ - -H "Content-Type: application/json" \ - -d '{ - "messages": [{"role": "user", "content": "Research current AI trends"}], - "stream": true - }' -``` - -### Agent State Monitoring - -```python -import httpx - - -async def monitor_agent(agent_id: str): - async with httpx.AsyncClient() as client: - response = await client.get(f"http://localhost:8010/agents/{agent_id}/state") - state = response.json() +## Open-Source Development Team - print(f"Task: {state['task']}") - print(f"State: {state['state']}") - print(f"Searches used: {state['searches_used']}") - print(f"Sources found: {state['sources_count']}") -``` - -
- -______________________________________________________________________ - -## 🎯 Example Research Tasks - -The SGR system excels at various research scenarios: - -- **Market Research**: "Analyze BMW X6 2025 pricing across European markets" -- **Technology Trends**: "Research current developments in quantum computing" -- **Competitive Analysis**: "Compare features of top 5 CRM systems in 2024" -- **Industry Reports**: "Investigate renewable energy adoption in Germany" - -## πŸš€ Future Development Plans - -Our team is actively working on several exciting enhancements to the SGR Deep Research platform: - -### πŸ”„ Hybrid Mode Integration - -- Implementing a hybrid SGR+FC mode directly in the current functionality -- Allowing seamless switching between SGR and Function Calling based on model capabilities -- Optimizing performance for mid-range models (14-32B parameters) - -### πŸ“Š Comprehensive Benchmarking - -- Developing a specialized benchmark suite for comparing SGR vs ReAct approaches -- Testing across various model sizes and architectures -- Measuring performance, accuracy, and reliability metrics - -### 🧠 MCP Functionality - -- Adding support for [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) functionality -- Standardizing agent tooling and reasoning interfaces -- Enhancing interoperability with other agent frameworks - -## 🀝 Open-Source Contributing - -We welcome contributions from the community! SGR Deep Research is an open-source project designed as a production-ready service with extensible architecture. - -### How to Contribute +*All development is driven by pure enthusiasm and open-source community collaboration. We welcome contributors of all skill levels!* -1. **Fork the repository** -2. **Create a feature branch** - ```bash - git checkout -b feature/your-feature-name - ``` -3. **Make your changes** -4. **Test thoroughly** - ```bash - cd src - uv sync - uv run python sgr_deep_research - # Test your changes - ``` -5. **Submit a pull request** +- **SGR Concept Creator** // [@abdullin](https://t.me/llm_under_hood) +- **Project Coordinator & Vision** // [@VaKovaLskii](https://t.me/neuraldeep) +- **Lead Core Developer** // [@virrius](https://t.me/virrius_tech) +- **API Development** // [Pavel Zloi](https://t.me/evilfreelancer) +- **Hybrid FC research** // [@Shadekss](https://t.me/Shadekss) +- **DevOps & Deployment** // [@mixaill76](https://t.me/mixaill76) -### Areas for Contribution +If you have any questions - feel free to reach out to [Valerii Kovalskii](https://www.linkedin.com/in/vakovalskii/). -- 🧠 **New reasoning schemas** for specialized research domains -- πŸ” **Additional search providers** (Google, Bing, etc.) -- πŸ› οΈ **Tool integrations** (databases, APIs, file systems) -- πŸ“Š **Enhanced reporting formats** (PDF, HTML, structured data) -- πŸ”§ **Performance optimizations** and caching strategies +## Special Thanks To: -______________________________________________________________________ - -🧠 **Production-ready Schema-Guided Reasoning for automated research!** +This project is developed by the **neuraldeep** community. It is inspired by the Schema-Guided Reasoning (SGR) work and [SGR Agent Demo](https://abdullin.com/schema-guided-reasoning/demo) delivered by "LLM Under the Hood" community and AI R&D Hub of [TIMETOACT GROUP Γ–sterreich](https://www.timetoact-group.at) diff --git a/benchmark/simpleqa_benchmark_results.md b/benchmark/simpleqa_benchmark_results.md index 8a97a95..11615df 100644 --- a/benchmark/simpleqa_benchmark_results.md +++ b/benchmark/simpleqa_benchmark_results.md @@ -57,7 +57,7 @@ Last version project exist on commit - 06a418bbb63728fe56bda27894ec263be4ceab81. # Results -![alt text](../assets/simpleqa_benchmark_comparison.png) +![bench image](../docs/simpleqa_benchmark_comparison.png) As a result, our agent achieved an Accuracy = 0.861 diff --git a/docs/WIKI.md b/docs/WIKI.md new file mode 100644 index 0000000..7ca4dc0 --- /dev/null +++ b/docs/WIKI.md @@ -0,0 +1,681 @@ +# 🧠 SGR Deep Research - Open-Source Schema-Guided Reasoning System + +## SGR Deep Research is an agent-driven research system with a chat interface. It is can run with small LLMs for a fully local mode. + +This project is developed by the **neuraldeep** community. It is inspired by the Schema-Guided Reasoning (SGR) work and [SGR Agent Demo](https://abdullin.com/schema-guided-reasoning/demo) delivered by "LLM Under the Hood" community and AI R&D Hub of [TIMETOACT GROUP Γ–sterreich](https://www.timetoact-group.at) + +If you have any questions - feel free to reach out to [Valerii Kovalskii](https://www.linkedin.com/in/vakovalskii/). + +Web Interface Video + +https://github.com/user-attachments/assets/9e1c46c0-0c13-45dd-8b35-a3198f946451 + +Terminal CLI Video + +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 TOP AGENT | +| **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: + +- **SGR Concept Creator**: [@abdullin](https://t.me/llm_under_hood) - Original Schema-Guided Reasoning concept +- **Project Coordinator & Vision**: [@VaKovaLskii](https://t.me/neuraldeep) - Team coordination and project direction +- **Lead Core Developer**: [@virrius](https://t.me/virrius_tech) - Complete system rewrite and core implementation +- **API Development**: [Pavel Zloi](https://t.me/evilfreelancer) - OpenAI-compatible API layer +- **Hybrid FC Mode**: [@Shadekss](https://t.me/Shadekss) - Dmitry Sirakov \[Shade\] - SGR integration into Function Calling for Agentic-capable models +- **DevOps & Deployment**: [@mixaill76](https://t.me/mixaill76) - Infrastructure and build management + +*All development is driven by pure enthusiasm and open-source community collaboration. We welcome contributors of all skill levels!* + +## πŸš€ Quick Start + +### Prerequisites + +First, install UV (modern Python package manager): + +```bash +# Install UV +curl -LsSf https://astral.sh/uv/install.sh | sh +# or on Windows: +# powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" +``` + +### Local Development + +```bash +# 1. Setup configuration +cp config.yaml.example config.yaml +# Edit config.yaml with your API keys + +# 2. Change to src directory and install dependencies +uv sync + +# 3. Run the server +uv run python sgr_deep_research +``` + +### Docker Deployment + +```bash +# 1. Setup configuration +cp config.yaml.example config.yaml +# Edit config.yaml with your API keys + +# 2. Go to the services folder +cd services + +# 3. Building docker images +docker-compose build + +# 4. Deploy with Docker Compose +docker-compose up -d + +# 3. Check health +curl http://localhost:8010/health +``` + +______________________________________________________________________ + +## πŸ“š Integration & Examples + +
+πŸš€ Python OpenAI Client Examples - Complete integration guide with streaming & clarifications + +Simple Python examples for using OpenAI client with SGR Deep Research system. + +## Prerequisites + +```bash +pip install openai +``` + +## Example 1: Basic Research Request + +Simple research query without clarifications. + +```python +from openai import OpenAI + +# Initialize client +client = OpenAI( + base_url="http://localhost:8010/v1", + api_key="dummy", # Not required for local server +) + +# Make research request +response = client.chat.completions.create( + model="sgr-agent", + messages=[{"role": "user", "content": "Research BMW X6 2025 prices in Russia"}], + stream=True, + temperature=0.4, +) + +# Print streaming response +for chunk in response: + if chunk.choices[0].delta.content: + print(chunk.choices[0].delta.content, end="") +``` + +## Example 2: Research with Clarification Support + +Handle agent clarification requests and continue conversation. + +```python +import json +from openai import OpenAI + +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-agent", + messages=[{"role": "user", "content": "Research AI market trends"}], + stream=True, + temperature=0, +) + +agent_id = None +clarification_questions = [] + +# Process streaming response +for chunk in response: + # Extract agent ID from model field + if chunk.model and chunk.model.startswith("sgr_agent_"): + agent_id = chunk.model + print(f"\nAgent ID: {agent_id}") + + # Check for clarification requests + if chunk.choices[0].delta.tool_calls: + for tool_call in chunk.choices[0].delta.tool_calls: + if tool_call.function and tool_call.function.name == "clarification": + args = json.loads(tool_call.function.arguments) + clarification_questions = args.get("questions", []) + + # Print content + if chunk.choices[0].delta.content: + print(chunk.choices[0].delta.content, end="") + +# Step 2: Handle clarification if needed +if clarification_questions and agent_id: + print(f"\n\nClarification needed:") + for i, question in enumerate(clarification_questions, 1): + print(f"{i}. {question}") + + # Provide clarification + clarification = "Focus on LLM market trends for 2024-2025, global perspective" + print(f"\nProviding clarification: {clarification}") + + # Continue with agent ID + response = client.chat.completions.create( + model=agent_id, # Use agent ID as model + messages=[{"role": "user", "content": clarification}], + stream=True, + temperature=0, + ) + + # Print final response + for chunk in response: + if chunk.choices[0].delta.content: + print(chunk.choices[0].delta.content, end="") + +print("\n\nResearch completed!") +``` + +## Usage Notes + +- Replace `localhost:8010` with your server URL +- The `api_key` can be any string for local server +- Agent ID is returned in the `model` field during streaming +- Clarification questions are sent via `tool_calls` with function name `clarification` +- Use the agent ID as model name to continue conversation + +
+ +______________________________________________________________________ + +
+⚑ cURL API Examples - Direct HTTP requests with agent interruption & clarification flow + +The system provides a fully OpenAI-compatible API with advanced agent interruption and clarification capabilities. + +### Basic Research Request + +```bash +curl -X POST "http://localhost:8010/v1/chat/completions" \ + -H "Content-Type: application/json" \ + -d '{ + "model": "sgr_agent", + "messages": [{"role": "user", "content": "Research BMW X6 2025 prices in Russia"}], + "stream": true, + "max_tokens": 1500, + "temperature": 0.4 + }' +``` + +### πŸ”„ Agent Interruption & Clarification Flow + +When the agent needs clarification, it returns a unique agent ID in the streaming response model field. You can then continue the conversation using this agent ID. + +#### Step 1: Initial Request + +```bash +curl -X POST "http://localhost:8010/v1/chat/completions" \ + -H "Content-Type: application/json" \ + -d '{ + "model": "sgr_agent", + "messages": [{"role": "user", "content": "Research AI market trends"}], + "stream": true, + "max_tokens": 1500, + "temperature": 0 + }' +``` + +#### Step 2: Agent Requests Clarification + +The streaming response includes the agent ID in the model field: + +```json +{ + "model": "sgr_agent_b84d5a01-c394-4499-97be-dad6a5d2cb86", + "choices": [{ + "delta": { + "tool_calls": [{ + "function": { + "name": "clarification", + "arguments": "{\"questions\":[\"Which specific AI market segment are you interested in (LLM, computer vision, robotics)?\", \"What time period should I focus on (2024, next 5 years)?\", \"Are you looking for global trends or specific geographic regions?\", \"Do you need technical analysis or business/investment perspective?\"]}" + } + }] + } + }] +} +``` + +#### Step 3: Continue with Agent ID + +```bash +curl -X POST "http://localhost:8010/v1/chat/completions" \ + -H "Content-Type: application/json" \ + -d '{ + "model": "sgr_agent_b84d5a01-c394-4499-97be-dad6a5d2cb86", + "messages": [{"role": "user", "content": "Focus on LLM market trends for 2024-2025, global perspective, business analysis"}], + "stream": true, + "max_tokens": 1500, + "temperature": 0 + }' +``` + +### Agent Management + +```bash +# Get all active agents +curl http://localhost:8010/agents + +# Get specific agent state +curl http://localhost:8010/agents/{agent_id}/state + +# Direct clarification endpoint +curl -X POST "http://localhost:8010/agents/{agent_id}/provide_clarification" \ + -H "Content-Type: application/json" \ + -d '{ + "messages": [{"role": "user", "content": "Focus on luxury models only"}], + "stream": true + }' +``` + +
+ +______________________________________________________________________ + +## πŸ“Š SGR Agent Workflow + +### Agent Execution Sequence + +The following diagram shows the complete SGR agent workflow with interruption and clarification support: + +```mermaid +sequenceDiagram + participant Client + participant API as FastAPI Server + participant Agent as SGR Agent + participant LLM as LLM + participant Tools as Research Tools + + Note over Client, Tools: SGR Deep Research - Agent Workflow + + Client->>API: POST /v1/chat/completions
{"model": "sgr_agent", "messages": [...]} + + API->>Agent: Create new SGR Agent
with unique ID + Note over Agent: State: INITED + + Agent->>Agent: Initialize context
and conversation history + + loop SGR Reasoning Loop (max 6 steps) + Agent->>Agent: Prepare tools based on
current context limits + Agent->>LLM: Structured Output Request
with NextStep schema + + LLM-->>API: Streaming chunks + API-->>Client: SSE stream with
agent_id in model field + + LLM->>Agent: Parsed NextStep result + + alt Tool: Clarification + Note over Agent: State: WAITING_FOR_CLARIFICATION + Agent->>Tools: Execute clarification tool + Tools->>API: Return clarifying questions + API-->>Client: Stream clarification questions + + Client->>API: POST /v1/chat/completions
{"model": "agent_id", "messages": [...]} + API->>Agent: provide_clarification() + Note over Agent: State: RESEARCHING + Agent->>Agent: Add clarification to context + + else Tool: GeneratePlan + Agent->>Tools: Execute plan generation + Tools->>Agent: Research plan created + + else Tool: WebSearch + Agent->>Tools: Execute web search + Tools->>Tools: Tavily API call + Tools->>Agent: Search results + sources + Agent->>Agent: Update context with sources + + else Tool: AdaptPlan + Agent->>Tools: Execute plan adaptation + Tools->>Agent: Updated research plan + + else Tool: CreateReport + Agent->>Tools: Execute report creation + Tools->>Tools: Generate comprehensive
report with citations + Tools->>Agent: Final research report + + else Tool: ReportCompletion + Note over Agent: State: COMPLETED + Agent->>Tools: Execute completion + Tools->>Agent: Task completion status + end + + Agent->>Agent: Add tool result to
conversation history + API-->>Client: Stream tool execution result + + break Task Completed + Agent->>Agent: Break execution loop + end + end + + Agent->>API: Finish streaming + API-->>Client: Close SSE stream + + Note over Client, Tools: Agent remains accessible
via agent_id for further clarifications +``` + +### Schema-Guided Reasoning Capabilities: + +1. **πŸ€” Clarification** - clarifying questions when unclear +2. **πŸ“‹ Plan Generation** - research plan creation +3. **πŸ” Web Search** - internet information search +4. **πŸ”„ Plan Adaptation** - plan adaptation based on results +5. **πŸ“ Report Creation** - detailed report creation +6. **βœ… Completion** - task completion + +## 🧠 SGR vs Function Calling: When to Use Each Approach + +### The Problem with Function Calling on Local Models (ReAct Agents) + +**Reality Check:** Function Calling works great on OpenAI/Anthropic (80+ [BFCL](https://gorilla.cs.berkeley.edu/leaderboard.html) scores) but fails dramatically on local models \<32B parameters when using true ReAct agents with `tool_mode="auto"`, where the model itself decides when to call tools. + +**BFCL Benchmark Results for Qwen3 Models:** + +- `Qwen3-8B (FC)`: Only 15% accuracy in Agentic Web Search mode ([BFCL](https://gorilla.cs.berkeley.edu/leaderboard.html) benchmark) +- `Qwen3-4B (FC)`: Only 2% accuracy in Agentic Web Search mode +- `Qwen3-1.7B (FC)`: Only 4.5% accuracy in Agentic Web Search mode +- Even with native FC support, smaller models struggle with deciding **WHEN** to call tools +- Common result: `{"tool_calls": null, "content": "Text instead of tool call"}` + +**Note:** Our team is currently working on creating a specialized benchmark for SGR vs ReAct performance on smaller models. Initial testing confirms that the SGR pipeline enables even smaller models to follow complex task workflows. + +### SGR Solution: Forced Reasoning β†’ Deterministic Execution + +```python +# Phase 1: Structured Output reasoning (100% reliable) +reasoning = model.generate(format="json_schema") +# {"action": "search", "query": "BMW X6 prices", "reason": "need current data"} + +# Phase 2: Deterministic execution (no model uncertainty) +result = execute_plan(reasoning.actions) +``` + +### Architecture by Model Size + +| Model Size | Recommended Approach | FC Accuracy | Why Choose This | +| ---------- | ---------------------------- | ----------- | ----------------------- | +| **\<14B** | Pure SGR + Structured Output | 15-25% | FC practically unusable | +| **14-32B** | SGR + FC hybrid | 45-65% | Best of both worlds | +| **32B+** | Native FC with SGR fallback | 85%+ | FC works reliably | + +### When to Use SGR vs Function Calling + +| Use Case | Best Approach | Why | +| ------------------------------- | ---------------- | ------------------------------------------------ | +| **Data analysis & structuring** | SGR | Controlled reasoning with visibility | +| **Document processing** | SGR | Step-by-step analysis with justification | +| **Local models (\<32B)** | SGR | Forces reasoning regardless of model limitations | +| **Multi-agent systems** | Function Calling | Native agent interruption support | +| **External API interactions** | Function Calling | Direct tool access pattern | +| **Production monitoring** | SGR | All reasoning steps visible and loggable | + +### Real-World Results + +**Initial Testing Results:** + +- SGR enables even small models to follow structured workflows +- SGR pipeline provides deterministic execution regardless of model size +- SGR forces reasoning steps that ReAct leaves to model discretion + +**Planned Benchmarking:** + +- We're developing a comprehensive benchmark comparing SGR vs ReAct across model sizes +- Initial testing shows promising results for SGR on models as small as 4B parameters +- Full metrics and performance comparison coming soon + +### Hybrid Approach: The Best of Both Worlds + +The optimal solution for many production systems is a hybrid approach: + +1. **SGR for decision making** - Determine which tools to use +2. **Function Calling for execution** - Get data and provide agent-like experience +3. **SGR for final processing** - Structure and format results + +This hybrid approach works particularly well for models in the 14-32B range, where Function Calling works sometimes but isn't fully reliable. + +**Bottom Line:** Don't force \<32B models to pretend they're GPT-4o in ReAct-style agentic workflows with `tool_mode="auto"`. Let them think structurally through SGR, then execute deterministically. + +## βš™οΈ Configuration + +### Setup Configuration File + +1. **Create config.yaml from template:** + +```bash +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: + max_results: 10 # Maximum number of search results + +# Scraping Settings +scraping: + enabled: false # Enable full text scraping of found pages + max_pages: 5 # Maximum pages to scrape per search + content_limit: 1500 # Character limit for full content per source + +# Execution Settings +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 + tool_function_prompt_file: "tool_function_prompt.txt" # Tool function prompt file + system_prompt_file: "system_prompt.txt" # System prompt file +``` + +### Server Configuration + +```bash +# Custom host and port +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: + +``` +reports/YYYYMMDD_HHMMSS_Task_Name.md +``` + +### Report Structure + +- πŸ“‹ **Executive Summary** - Key insights overview +- πŸ” **Technical Analysis** - Detailed findings with citations +- πŸ“Š **Key Findings** - Main conclusions +- πŸ“Ž **Sources** - All reference links + +### Example Report + +See `docs/example_report.md` for a complete sample of SGR research output. + +______________________________________________________________________ + +
+πŸ› οΈ Advanced Integration Examples - Production-ready code for streaming, monitoring & state management + +### Python Client + +```python +import httpx + + +async def research_query(query: str): + async with httpx.AsyncClient() as client: + async with client.stream( + "POST", + "http://localhost:8010/v1/chat/completions", + json={"messages": [{"role": "user", "content": query}], "stream": True}, + ) as response: + async for chunk in response.aiter_text(): + print(chunk, end="") +``` + +### Curl with Streaming + +```bash +curl -N -X POST "http://localhost:8010/v1/chat/completions" \ + -H "Content-Type: application/json" \ + -d '{ + "messages": [{"role": "user", "content": "Research current AI trends"}], + "stream": true + }' +``` + +### Agent State Monitoring + +```python +import httpx + + +async def monitor_agent(agent_id: str): + async with httpx.AsyncClient() as client: + response = await client.get(f"http://localhost:8010/agents/{agent_id}/state") + state = response.json() + + print(f"Task: {state['task']}") + print(f"State: {state['state']}") + print(f"Searches used: {state['searches_used']}") + print(f"Sources found: {state['sources_count']}") +``` + +
+ +______________________________________________________________________ + +## 🎯 Example Research Tasks + +The SGR system excels at various research scenarios: + +- **Market Research**: "Analyze BMW X6 2025 pricing across European markets" +- **Technology Trends**: "Research current developments in quantum computing" +- **Competitive Analysis**: "Compare features of top 5 CRM systems in 2024" +- **Industry Reports**: "Investigate renewable energy adoption in Germany" + +## πŸš€ Future Development Plans + +Our team is actively working on several exciting enhancements to the SGR Deep Research platform: + +### πŸ”„ Hybrid Mode Integration + +- Implementing a hybrid SGR+FC mode directly in the current functionality +- Allowing seamless switching between SGR and Function Calling based on model capabilities +- Optimizing performance for mid-range models (14-32B parameters) + +### πŸ“Š Comprehensive Benchmarking + +- Developing a specialized benchmark suite for comparing SGR vs ReAct approaches +- Testing across various model sizes and architectures +- Measuring performance, accuracy, and reliability metrics + +### 🧠 MCP Functionality + +- Adding support for [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) functionality +- Standardizing agent tooling and reasoning interfaces +- Enhancing interoperability with other agent frameworks + +## 🀝 Open-Source Contributing + +We welcome contributions from the community! SGR Deep Research is an open-source project designed as a production-ready service with extensible architecture. + +### How to Contribute + +1. **Fork the repository** +2. **Create a feature branch** + ```bash + git checkout -b feature/your-feature-name + ``` +3. **Make your changes** +4. **Test thoroughly** + ```bash + cd src + uv sync + uv run python sgr_deep_research + # Test your changes + ``` +5. **Submit a pull request** + +### Areas for Contribution + +- 🧠 **New reasoning schemas** for specialized research domains +- πŸ” **Additional search providers** (Google, Bing, etc.) +- πŸ› οΈ **Tool integrations** (databases, APIs, file systems) +- πŸ“Š **Enhanced reporting formats** (PDF, HTML, structured data) +- πŸ”§ **Performance optimizations** and caching strategies + +______________________________________________________________________ + +🧠 **Production-ready Schema-Guided Reasoning for automated research!** diff --git a/docs/dev_workflow.png b/docs/dev_workflow.png new file mode 100644 index 0000000..15990f3 Binary files /dev/null and b/docs/dev_workflow.png differ diff --git a/docs/idea_workflow.png b/docs/idea_workflow.png new file mode 100644 index 0000000..cc7c9d9 Binary files /dev/null and b/docs/idea_workflow.png differ diff --git a/docs/sgr_concept.png b/docs/sgr_concept.png new file mode 100644 index 0000000..c9042c4 Binary files /dev/null and b/docs/sgr_concept.png differ diff --git a/assets/simpleqa_benchmark_comparison.png b/docs/simpleqa_benchmark_comparison.png similarity index 100% rename from assets/simpleqa_benchmark_comparison.png rename to docs/simpleqa_benchmark_comparison.png diff --git a/docs/workflow.png b/docs/workflow.png new file mode 100644 index 0000000..829f9e2 Binary files /dev/null and b/docs/workflow.png differ diff --git a/docs/works_workflow.png b/docs/works_workflow.png new file mode 100644 index 0000000..46a193e Binary files /dev/null and b/docs/works_workflow.png differ diff --git a/examples/basic_research_request.py b/examples/basic_research_request.py new file mode 100644 index 0000000..5b73335 --- /dev/null +++ b/examples/basic_research_request.py @@ -0,0 +1,20 @@ +from openai import OpenAI + +# Initialize client +client = OpenAI( + base_url="http://localhost:8010/v1", + api_key="dummy", # Not required for local server +) + +# Make research request +response = client.chat.completions.create( + model="sgr-agent", + messages=[{"role": "user", "content": "Research BMW X6 2025 prices in Russia"}], + stream=True, + temperature=0.4, +) + +# Print streaming response +for chunk in response: + if chunk.choices[0].delta.content: + print(chunk.choices[0].delta.content, end="") diff --git a/examples/research_with_clarification.py b/examples/research_with_clarification.py new file mode 100644 index 0000000..f0ae56f --- /dev/null +++ b/examples/research_with_clarification.py @@ -0,0 +1,60 @@ +import json + +from openai import OpenAI + +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-agent", + messages=[{"role": "user", "content": "Research AI market trends"}], + stream=True, + temperature=0, +) + +agent_id = None +clarification_questions = [] + +# Process streaming response +for chunk in response: + # Extract agent ID from model field + if chunk.model and chunk.model.startswith("sgr_agent_"): + agent_id = chunk.model + print(f"\nAgent ID: {agent_id}") + + # Check for clarification requests + if chunk.choices[0].delta.tool_calls: + for tool_call in chunk.choices[0].delta.tool_calls: + if tool_call.function and tool_call.function.name == "clarification": + args = json.loads(tool_call.function.arguments) + clarification_questions = args.get("questions", []) + + # Print content + if chunk.choices[0].delta.content: + print(chunk.choices[0].delta.content, end="") + +# Step 2: Handle clarification if needed +if clarification_questions and agent_id: + print("\n\nClarification needed:") + for i, question in enumerate(clarification_questions, 1): + print(f"{i}. {question}") + + # Provide clarification + clarification = "Focus on LLM market trends for 2024-2025, global perspective" + print(f"\nProviding clarification: {clarification}") + + # Continue with agent ID + response = client.chat.completions.create( + model=agent_id, # Use agent ID as model + messages=[{"role": "user", "content": clarification}], + stream=True, + temperature=0, + ) + + # Print final response + for chunk in response: + if chunk.choices[0].delta.content: + print(chunk.choices[0].delta.content, end="") + +print("\n\nResearch completed!")