# 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.