vamplabAI · EvilFreelancer · Jan 20, 2026 · Jan 5, 2026 · Jan 5, 2026 · Jan 5, 2026
diff --git a/.cursor/rules/architecture.mdc b/.cursor/rules/architecture.mdc
@@ -0,0 +1,118 @@
+---
+description: Architectural rules and boundaries for SGR Agent Core
+globs: sgr_agent_core/**/*.py
+alwaysApply: true
+---
+
+# Architectural Rules for SGR Agent Core
+
+## General Architecture
+
+The project uses **modular architecture with clear separation of concerns**. The framework implements Schema-Guided Reasoning (SGR) for building intelligent research agents.
+
+## Core Architecture Layers
+
+### Layer 1: Base Classes (No Dependencies)
+- `BaseAgent` - Base class for all agents
+- `BaseTool` - Base class for all tools (Pydantic models)
+- `MCPBaseTool` - Base class for MCP-integrated tools
+- `models.py` - Core data models (AgentContext, AgentStatesEnum, etc.)
+
+### Layer 2: Configuration and Registry
+- `agent_config.py` - GlobalConfig singleton
+- `agent_definition.py` - AgentDefinition, AgentConfig, LLMConfig, etc.
+- `services/registry.py` - AgentRegistry, ToolRegistry
+- `services/prompt_loader.py` - PromptLoader service
+
+### Layer 3: Factory and Services
+- `agent_factory.py` - AgentFactory for creating agents
+- `services/mcp_service.py` - MCP2ToolConverter
+- `services/tavily_search.py` - Tavily search service
+- `next_step_tool.py` - NextStepToolsBuilder, NextStepToolStub
+
+### Layer 4: Agent Implementations
+- `agents/sgr_agent.py` - SGRAgent (Structured Output)
+- `agents/tool_calling_agent.py` - ToolCallingAgent (Function Calling)
+- `agents/sgr_tool_calling_agent.py` - SGRToolCallingAgent (Hybrid)
+
+### Layer 5: Tools
+- `tools/reasoning_tool.py` - ReasoningTool
+- `tools/clarification_tool.py` - ClarificationTool
+- `tools/web_search_tool.py` - WebSearchTool
+- `tools/extract_page_content_tool.py` - ExtractPageContentTool
+- `tools/generate_plan_tool.py` - GeneratePlanTool
+- `tools/adapt_plan_tool.py` - AdaptPlanTool
+- `tools/create_report_tool.py` - CreateReportTool
+- `tools/final_answer_tool.py` - FinalAnswerTool
+
+### Layer 6: Server and API
+- `server/app.py` - FastAPI application
+- `server/endpoints.py` - API endpoints
+- `server/models.py` - API request/response models
+- `server/settings.py` - Server settings
+- `stream.py` - OpenAIStreamingGenerator
+
+## Agent Execution Cycle
+
+All agents follow a two-phase cycle:
+
+```python
+while agent.state not in FINISH_STATES:
+    reasoning = await agent._reasoning_phase()
+    action_tool = await agent._select_action_phase(reasoning)
+    await agent._action_phase(action_tool)
+```
+
+### Phase 1: Reasoning Phase
+- Agent analyzes current context
+- Decides on next action
+- Implementation varies by agent type (SO, FC, or Hybrid)
+
+### Phase 2: Select Action Phase
+- Selects appropriate tool based on reasoning
+- Returns tool instance ready for execution
+
+### Phase 3: Action Phase
+- Executes selected tool
+- Updates conversation history
+- Updates agent context
+
+## Module Rules
+
+### Agents (`sgr_agent_core/agents/`)
+- Must inherit from `BaseAgent`
+- Must implement `_reasoning_phase()`, `_select_action_phase()`, `_action_phase()`
+- Automatically registered in `AgentRegistry` via `AgentRegistryMixin`
+- Can override `_prepare_context()` and `_prepare_tools()` for customization
+
+### Tools (`sgr_agent_core/tools/`)
+- Must inherit from `BaseTool` or `MCPBaseTool`
+- Must be Pydantic models
+- Must implement `__call__()` method
+- Automatically registered in `ToolRegistry` via `ToolRegistryMixin`
+- Return string or JSON string from `__call__()`
+
+### Services (`sgr_agent_core/services/`)
+- Stateless utility classes
+- Provide shared functionality (prompts, MCP, search)
+- No direct dependencies on agents or tools
+
+### Configuration (`agent_config.py`, `agent_definition.py`)
+- Hierarchical configuration: GlobalConfig → AgentDefinition → AgentConfig
+- Supports YAML loading
+- Automatic inheritance and override of settings
+
+## Design Principles
+
+1. **One class at a time**: When implementing new functionality, create one class at a time, starting from lower layers
+2. **Minimal dependencies**: Each module should depend only on lower layer modules
+3. **Type hints**: Use type hints for all functions and methods
+4. **Async-first**: All I/O operations must be async
+5. **Registry pattern**: Use registries for automatic discovery of agents and tools
+6. **Configuration over code**: Prefer YAML configuration over hardcoded values
+
+## References
+
+@docs/en/framework/main-concepts.md
+@docs/en/framework/agents.md
+@README.md
diff --git a/.cursor/rules/code-style.mdc b/.cursor/rules/code-style.mdc
@@ -0,0 +1,99 @@
+---
+description: Code style and formatting rules for SGR Agent Core
+globs: **/*.py
+alwaysApply: true
+---
+
+# Code Style Rules
+
+## General Rules
+
+1. **Comments**: Write all code comments **ONLY in English**
+2. **User responses**: Respond in Russian unless user requests otherwise
+3. **Empty line at end of file**: Always add an empty line at the end of new files
+4. **Virtual environment**: Virtual environment is located in `.venv` directory
+
+## Code Formatting
+
+### Ruff and Black
+- Use `ruff` for linting and formatting
+- Line length: **120 characters** (configured in `pyproject.toml`)
+- Follow rules from `pyproject.toml` and `.ruff.toml` if present
+
+### Imports
+- Use `isort` for import sorting
+- Group imports: standard library → third-party → local
+- One import per line for long lists
+
+### Type Hints
+- **Mandatory**: Use type hints for all functions and methods
+- Prefer `T | None` over `Optional[T]` (Python 3.10+)
+- Use `Union[A, B]` for complex types when needed
+- Use `dict[str, Any]` instead of `Dict[str, Any]` (Python 3.9+)
+
+### Docstrings
+- Use docstrings in Google style format
+- All docstrings in **English**
+- Must document:
+  - Public classes and methods
+  - Complex business logic
+  - Parameters and return values
+
+Example:
+```python
+def create_agent(self, agent_def: AgentDefinition, task_messages: list[dict]) -> BaseAgent:
+    """
+    Create an agent instance from a definition.
+
+    Args:
+        agent_def: Agent definition with configuration
+        task_messages: Task messages in OpenAI format
+
+    Returns:
+        Created agent instance
+    """
+```
+
+## File Structure
+
+### Element Order in File
+1. Module docstring
+2. Imports (standard library → third-party → local)
+3. Constants
+4. Types and exceptions
+5. Classes and functions
+
+### Naming
+- **Classes**: PascalCase (`SGRAgent`, `BaseTool`)
+- **Functions and methods**: snake_case (`create_agent`, `_prepare_context`)
+- **Constants**: UPPER_SNAKE_CASE (`MAX_ITERATIONS`)
+- **Private methods**: start with `_` (`_reasoning_phase`, `_log_reasoning`)
+- **Types**: PascalCase (`AgentContext`, `AgentDefinition`)
+
+## Error Handling
+
+- Use specific exceptions, not generic `Exception`
+- Create custom exceptions for business logic when needed
+- Always include informative error messages
+- Use `Optional` or `| None` for values that may be missing
+
+## Async/Await
+
+- Use `async def` for all asynchronous operations
+- Use `await` for all async calls
+- Don't use blocking I/O in async code
+- Use `httpx` instead of `requests` for async HTTP calls
+
+## FastAPI-Specific Guidelines
+
+- Avoid global scope variables, use application state
+- Use functional components and Pydantic models for validation
+- Use declarative route definitions with clear return type annotations
+- Use `async def` for asynchronous endpoints
+- Use Pydantic's `BaseModel` for input/output validation
+- Use `HTTPException` for expected errors
+
+## References
+
+@pyproject.toml
+@pytest.ini
diff --git a/.cursor/rules/core-modules.mdc b/.cursor/rules/core-modules.mdc
@@ -0,0 +1,169 @@
+---
+description: Rules for core modules of SGR Agent Core
+globs: sgr_agent_core/**/*.py
+alwaysApply: true
+---
+
+# Rules for Core Modules
+
+## Base Classes
+
+### BaseAgent (`sgr_agent_core/base_agent.py`)
+- Parent class for all agents
+- Implements two-phase execution cycle: Reasoning → Action
+- Manages agent context, conversation history, and streaming
+- Must be subclassed to implement `_reasoning_phase()`, `_select_action_phase()`, `_action_phase()`
+- Automatically registered in `AgentRegistry` via `AgentRegistryMixin`
+
+### BaseTool (`sgr_agent_core/base_tool.py`)
+- Parent class for all tools
+- Must be a Pydantic model
+- Must implement `__call__(context, config)` method
+- Returns string or JSON string
+- Automatically registered in `ToolRegistry` via `ToolRegistryMixin`
+
+### MCPBaseTool (`sgr_agent_core/base_tool.py`)
+- Base class for MCP-integrated tools
+- Handles MCP client calls
+- Converts MCP responses to tool format
+
+## Configuration Modules
+
+### GlobalConfig (`sgr_agent_core/agent_config.py`)
+- Singleton pattern for global configuration
+- Loads from YAML files (`config.yaml`, `agents.yaml`)
+- Provides default values for all agent settings
+
+### AgentDefinition (`sgr_agent_core/agent_definition.py`)
+- Definition template for creating agents
+- Contains: name, base_class, tools, llm, prompts, execution, search, mcp configs
+- Supports YAML loading
+- Validates required fields
+
+### AgentConfig (`sgr_agent_core/agent_definition.py`)
+- Runtime configuration for agent instance
+- Combines: LLMConfig, SearchConfig, ExecutionConfig, PromptsConfig, MCPConfig
+- Supports hierarchical inheritance from GlobalConfig
+
+## Factory and Services
+
+### AgentFactory (`sgr_agent_core/agent_factory.py`)
+- Creates agent instances from AgentDefinition
+- Resolves agent classes from AgentRegistry
+- Resolves tools from ToolRegistry
+- Builds MCP tools via MCP2ToolConverter
+- Creates OpenAI client with proxy support
+
+### AgentRegistry (`sgr_agent_core/services/registry.py`)
+- Centralized registry for agent classes
+- Automatic registration via `AgentRegistryMixin`
+- Supports lookup by name (case-insensitive)
+
+### ToolRegistry (`sgr_agent_core/services/registry.py`)
+- Centralized registry for tool classes
+- Automatic registration via `ToolRegistryMixin`
+- Supports lookup by name (case-insensitive)
+
+### PromptLoader (`sgr_agent_core/services/prompt_loader.py`)
+- Loads and formats prompts from files or strings
+- Generates system prompts with tool descriptions
+- Formats initial user requests and clarification responses
+
+### MCP2ToolConverter (`sgr_agent_core/services/mcp_service.py`)
+- Converts MCP server tools to BaseTool instances
+- Handles MCP client initialization
+- Builds tools from MCP configuration
+
+## Agent Implementations
+
+### SGRAgent (`sgr_agent_core/agents/sgr_agent.py`)
+- Uses Structured Output approach
+- Creates dynamic JSON schema for tools
+- LLM returns reasoning + tool schema in one call
+- Extracts tool directly from reasoning result
+
+### ToolCallingAgent (`sgr_agent_core/agents/tool_calling_agent.py`)
+- Uses native Function Calling
+- No explicit reasoning phase
+- Uses `tool_choice="required"` for tool selection
+- Best for advanced LLM models
+
+### SGRToolCallingAgent (`sgr_agent_core/agents/sgr_tool_calling_agent.py`)
+- Hybrid approach: SGR + Function Calling
+- Uses ReasoningTool for explicit reasoning
+- Uses Function Calling for tool selection
+- Best balance for most tasks
+
+## Tools
+
+### ReasoningTool (`sgr_agent_core/tools/reasoning_tool.py`)
+- Provides structured reasoning output
+- Contains: reasoning_steps, current_situation, plan_status, enough_data, remaining_steps, task_completed
+
+### ClarificationTool (`sgr_agent_core/tools/clarification_tool.py`)
+- Requests clarification from user
+- Pauses agent execution
+- Waits for user input via `provide_clarification()`
+
+### WebSearchTool (`sgr_agent_core/tools/web_search_tool.py`)
+- Performs web search via Tavily API
+- Returns search results with sources
+- Respects max_searches limit
+
+### ExtractPageContentTool (`sgr_agent_core/tools/extract_page_content_tool.py`)
+- Extracts content from web pages
+- Uses Tavily API for content extraction
+- Respects content_limit
+
+### GeneratePlanTool (`sgr_agent_core/tools/generate_plan_tool.py`)
+- Generates research plan
+- Defines research goal and steps
+- Provides search strategies
+
+### AdaptPlanTool (`sgr_agent_core/tools/adapt_plan_tool.py`)
+- Adapts existing plan based on new information
+- Updates research goal and steps
+- Modifies search strategies
+
+### CreateReportTool (`sgr_agent_core/tools/create_report_tool.py`)
+- Creates final research report
+- Saves report to file
+- Formats report with sources
+
+### FinalAnswerTool (`sgr_agent_core/tools/final_answer_tool.py`)
+- Provides final answer to user
+- Completes agent execution
+- Sets agent state to COMPLETED
+
+## Server and API
+
+### FastAPI Application (`sgr_agent_core/server/app.py`)
+- Main FastAPI application
+- Configures CORS, middleware
+- Registers endpoints
+
+### API Endpoints (`sgr_agent_core/server/endpoints.py`)
+- `/v1/chat/completions` - OpenAI-compatible chat endpoint
+- `/v1/agents/{agent_id}/state` - Get agent state
+- `/v1/agents/{agent_id}/clarification` - Provide clarification
+- `/v1/agents` - List available agents
+
+### Streaming (`sgr_agent_core/stream.py`)
+- OpenAIStreamingGenerator for streaming responses
+- Formats events in OpenAI-compatible format
+- Handles tool calls and content chunks
+
+## General Rules for All Modules
+
+1. **Type hints**: Use type hints everywhere
+2. **Async**: All I/O operations must be async
+3. **Documentation**: Document public methods in English
+4. **Error handling**: Use specific exceptions
+5. **Registry**: Use registry pattern for discovery
+6. **Configuration**: Prefer YAML over hardcoded values
+
+## References
+
+@architecture.mdc
+@code-style.mdc
+@docs/en/framework/main-concepts.md