144 lines
5.6 KiB
Markdown
144 lines
5.6 KiB
Markdown
# Hermes Reasoning Module
|
|
|
|
This module implements advanced reasoning capabilities as a production-ready ahserver module that complements the harnessed_agent execution layer. It provides intelligent context analysis, multi-step planning, tool coordination, and error recovery while maintaining strict safety boundaries.
|
|
|
|
## Architecture Overview
|
|
|
|
### Reasoning Layer (harnessed_reasoning) + Execution Layer (harnessed_agent)
|
|
|
|
```
|
|
User Request
|
|
│
|
|
▼
|
|
[Hermes Reasoning Module] ←→ Intelligent Context (Memory/Sessions/Skills)
|
|
│
|
|
▼
|
|
Execution Plan with Safety Checks
|
|
│
|
|
▼
|
|
[Hermes Agent Module] ←→ Database/Tools/Remote Skills
|
|
│
|
|
▼
|
|
Execution Results → User Response
|
|
```
|
|
|
|
## Core Capabilities
|
|
|
|
### 1. Context-Aware Reasoning
|
|
- **Intelligent Context Gathering**: Automatically retrieves relevant memory, sessions, and skills
|
|
- **Cross-Session Integration**: Searches past conversations for relevant context
|
|
- **User Preference Awareness**: Respects stored user preferences and constraints
|
|
- **Token-Optimized Context**: Manages context within token limits
|
|
|
|
### 2. Advanced Planning & Decomposition
|
|
- **Task Decomposition**: Breaks complex requests into manageable subtasks
|
|
- **Multi-Step Planning**: Creates detailed execution plans with dependencies
|
|
- **Tool Selection Intelligence**: Selects appropriate tools based on task requirements
|
|
- **Confidence Scoring**: Provides confidence metrics for decision quality
|
|
|
|
### 3. Safety & Security
|
|
- **Strict Safety Mode**: Blocks dangerous operations (file deletion, system commands)
|
|
- **Moderate Safety Mode**: Allows common operations with caution
|
|
- **Lenient Safety Mode**: Minimal restrictions for trusted environments
|
|
- **User Preference Enforcement**: Respects user-defined safety constraints
|
|
|
|
### 4. Error Recovery & Resilience
|
|
- **Automatic Error Detection**: Identifies failed tool executions
|
|
- **Recovery Strategy Selection**: Applies appropriate recovery strategies
|
|
- **Alternative Path Execution**: Tries alternative approaches when primary fails
|
|
- **Graceful Degradation**: Continues with partial success when possible
|
|
|
|
### 5. Production Features
|
|
- **Full Multi-User Isolation**: Complete data separation between users
|
|
- **Persistent Session Storage**: All reasoning sessions stored in database
|
|
- **Audit Trail**: Complete history of reasoning decisions and executions
|
|
- **Configuration Management**: Runtime-configurable reasoning parameters
|
|
|
|
## Integration with Hermes Agent
|
|
|
|
The harnessed_reasoning module is designed to work seamlessly with harnessed_agent:
|
|
|
|
- **Shared Database Schema**: Both modules use compatible database structures
|
|
- **Common Authentication**: Integrates with same RBAC and user context system
|
|
- **Complementary APIs**: Reasoning functions feed execution functions
|
|
- **Unified Frontend**: Combined UI through bricks-framework integration
|
|
|
|
## Database Schema
|
|
|
|
Single table following `database-table-definition-spec`:
|
|
|
|
- **harnessed_reasoning_sessions**: Complete reasoning session records with execution plans, safety violations, and status tracking
|
|
|
|
## Frontend Integration
|
|
|
|
All interfaces follow `bricks-framework` requirements:
|
|
- Pure JSON format (.ui files)
|
|
- Tab-based navigation for organized interface
|
|
- Standard CRUD operations with proper parameter validation
|
|
- User context automatically propagated
|
|
|
|
## Installation
|
|
|
|
1. Install harnessed_agent first (required dependency)
|
|
2. Clone this repository to your `~/repos` directory
|
|
3. Install the module: `pip install -e .`
|
|
4. The module loads automatically via `load_harnessed_reasoning()` function
|
|
5. Access at `/harnessed_reasoning/harnessed_reasoning.ui`
|
|
|
|
## Dependencies
|
|
|
|
- **harnessed_agent >=1.0.0** (required)
|
|
- **ahserver >=1.0.0** (with user context support)
|
|
- **appPublic >=1.0.0**
|
|
- **sqlor-database-module >=1.0.0**
|
|
|
|
## Configuration Options
|
|
|
|
- `max_reasoning_steps`: Maximum steps per reasoning session (default: 10)
|
|
- `max_tool_calls_per_step`: Maximum concurrent tool calls (default: 5)
|
|
- `enable_cross_session_search`: Auto-search past sessions (default: true)
|
|
- `enable_skill_auto_loading`: Auto-load relevant skills (default: true)
|
|
- `safety_mode`: Security level (strict/moderate/lenient, default: strict)
|
|
- `max_context_tokens`: Context token limit (default: 4000)
|
|
- `enable_error_recovery`: Auto-recovery from errors (default: true)
|
|
|
|
## Verification Checklist
|
|
|
|
- [x] Module loads correctly via load_harnessed_reasoning() function
|
|
- [x] All functions work with user context propagation
|
|
- [x] Database operations follow sqlor specifications with user isolation
|
|
- [x] Frontend renders correctly with bricks-framework
|
|
- [x] CRUD operations function as defined with automatic user filtering
|
|
- [x] Package builds successfully with pyproject.toml
|
|
- [x] Follows all three specification skills exactly
|
|
- [x] Production-ready with no example code
|
|
- [x] Multi-user isolation verified and secure
|
|
- [x] RBAC integration works seamlessly
|
|
- [x] Safety modes properly implemented and tested
|
|
- [x] Error recovery mechanisms functional
|
|
- [x] Full integration with harnessed_agent module
|
|
|
|
## Usage Examples
|
|
|
|
### Basic Reasoning and Execution
|
|
```python
|
|
result = await hermes_reason_and_execute(
|
|
"Create a new Python module for data processing",
|
|
execute_immediately=True
|
|
)
|
|
```
|
|
|
|
### Planning Only (No Execution)
|
|
```python
|
|
plan = await hermes_reason_and_execute(
|
|
"Analyze the security implications of this code",
|
|
execute_immediately=False
|
|
)
|
|
```
|
|
|
|
### Session Retrieval
|
|
```python
|
|
session = await hermes_get_reasoning_session("session_123")
|
|
```
|
|
|
|
This implementation represents a complete, production-ready reasoning engine that transforms natural language requests into safe, executable plans while maintaining full context awareness and user isolation. |