agent-maxim/README.md

# Agent Maxim

AI-powered agent system with intelligent task planning, web search capabilities, and a modern mobile dashboard.

## Overview

Agent Maxim is an autonomous AI agent that can:
- **Understand complex tasks** using natural language processing
- **Plan multi-step solutions** with automatic tool selection
- **Execute web searches** with intelligent query enhancement
- **Process and analyze information** from multiple sources
- **Provide structured responses** through a clean chat interface

## Architecture

The system consists of three main components:

### 1. Agent Core (`agent/`)
- **Planning System**: Breaks down complex goals into executable steps
- **Tool Registry**: Manages available tools (web_search, web_fetch, etc.)
- **Runtime Executor**: Handles tool execution with safety guards
- **State Management**: Tracks agent progress and decisions

### 2. Bridge API (`bridge/`)
- **FastAPI Server**: RESTful API endpoint
- **Request Routing**: Forces agent-only execution (no direct LLM calls)
- **Policy Guards**: Security and safety checks
- **Run Management**: Persistent execution state

### 3. Dashboard (`simple_dashboard.py`)
- **WhatsApp-style UI**: Modern mobile-friendly interface
- **Real-time Communication**: Direct agent interaction
- **Responsive Design**: Works on all screen sizes
- **Visual Feedback**: Loading states, formatted results

## Installation

### Prerequisites
- Python 3.10+
- pip package manager

### Setup
```bash
# Clone the repository
git clone <repository-url>
cd agent-maxim

# Install dependencies
pip install -r requirements.txt
```

## Usage

### Starting the Backend API
```bash
cd bridge
python app.py
```

The API will start on `http://localhost:8000`

### Starting the Dashboard
```bash
python simple_dashboard.py
```

The dashboard will start on `http://localhost:8610`

### Running the Agent Directly
```bash
cd agent
python main.py --goal "найди новости OpenAI"
python main.py --goal "inspect project"
python main.py --goal "create file hello.txt with text hello world"
```

## API Endpoints

### POST /runs
Execute a one-shot agent run.

**Request:**
```json
{
  "goal": "найди новости OpenAI",
  "adapter": "agent"
}
```

**Response:**
```json
{
  "run_id": "unique-id",
  "status": "completed",
  "goal": "найди новости OpenAI",
  "adapter": "agent",
  "response": "Agent response..."
}
```

### GET /health
Check server status and adapter configuration.

## Features

### Intelligent Web Search
- **Query Enhancement**: Automatically improves search queries
- **Context Extraction**: Removes instruction prefixes
- **Source Filtering**: Focuses on quality tech sources
- **Result Formatting**: Clean presentation of search results

### Planning System
- **Multi-step reasoning**: Breaks down complex tasks
- **Tool selection**: Chooses appropriate tools automatically
- **Fallback handling**: Graceful degradation on failures
- **State tracking**: Maintains execution context

### Security & Safety
- **Workspace isolation**: File operations restricted to workspace
- **Command filtering**: Prevents dangerous operations
- **Policy guards**: Input validation and sanitization
- **Execution limits**: Timeout and resource constraints

## Development

### Project Structure
```
agent-maxim/
├── agent/                 # Agent core system
│   ├── core/             # Planning and execution logic
│   ├── runtime/          # Tool execution environment
│   └── main.py           # Direct agent entry point
├── bridge/              # API server
│   ├── api/             # REST endpoints
│   ├── adapters/        # Backend adapters
│   └── app.py           # Server entry point
├── simple_dashboard.py   # Mobile dashboard UI
└── requirements.txt      # Python dependencies
```

### Testing
```bash
# Run all tests
pytest

# Run specific tests
pytest tests/test_web_search.py
```

## Configuration

### Environment Variables
- `OLLAMA_MODEL`: Default Ollama model (default: "qwen2.5:7b")
- `WORKSPACE_ROOT`: Workspace directory for file operations

### Dashboard Configuration
The dashboard connects to the backend API at `/runs` endpoint. 
Ensure the API server is running before starting the dashboard.

## Deployment

### Production Server
The system is currently deployed on:
- **API**: https://openclaw.kotkanagrilli.fi (port 8000)
- **Dashboard**: https://max-dashboard.kotkanagrilli.fi (port 8610)

### Server Setup
```bash
# On production server
cd /home/anton/clear
# Start backend
cd bridge && python app.py
# Start dashboard (in separate terminal)
python simple_dashboard.py
```

## Example Use Cases

### Web Search
```
User: "найди новости OpenAI"
Agent: Performs enhanced search for latest OpenAI news
      Returns formatted results with titles, snippets, and URLs
```

### Understanding Projects
```
User: "inspect project"
Agent: Analyzes codebase structure
      Provides overview of files and directories
```

### Task Planning
```
User: "create a Python file that calculates factorial"
Agent: Plans steps:
      1. Create file structure
      2. Write factorial function
      3. Add test cases
      Executes steps sequentially
```

## Troubleshooting

### Common Issues

**Dashboard not connecting to API**
- Ensure backend API is running on port 8000
- Check firewall settings
- Verify API endpoint is accessible

**Agent not responding**
- Check backend logs for errors
- Verify agent dependencies are installed
- Ensure workspace directory exists and is writable

**Web search returning poor results**
- Check internet connectivity
- Verify search API is accessible
- Review query enhancement logs

## Contributing

Contributions are welcome! Please follow these guidelines:
- Use the existing code style (4 spaces, max 100 char lines)
- Add tests for new features
- Update documentation for API changes
- Follow security best practices

## License

This project is part of the Agent Maxim system.

## Support

For issues and questions:
- Check existing documentation
- Review code comments and docstrings
- Examine execution logs for debugging

---

**Agent Maxim** - Intelligent AI Agent for Task Automation and Information Retrieval