Metadata-Version: 2.4
Name: nexus-ai-agent
Version: 1.0.0
Summary: Intelligent Agentic File Assistant powered by Claude
Home-page: https://github.com/Remote-Skills/nexus
Author: Chiheb Nabil
Author-email: Chiheb Nabil <hi@remoteskills.io>
Maintainer-email: Chiheb Nabil <hi@remoteskills.io>
License-Expression: MIT
Project-URL: Homepage, https://github.com/Remote-Skills/nexus
Project-URL: Documentation, https://github.com/Remote-Skills/nexus#readme
Project-URL: Repository, https://github.com/Remote-Skills/nexus
Project-URL: Bug Tracker, https://github.com/Remote-Skills/nexus/issues
Keywords: ai,agent,claude,anthropic,automation,agentic,file-operations
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: anthropic>=0.25.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: rich>=13.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: flake8>=6.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# Nexus - Intelligent Agentic File Assistant

A powerful AI agent powered by Claude that plans and executes complex file operations step-by-step with built-in safety mechanisms.

## Features

### Agentic Planning

- **Automatic Planning**: Creates a TODO list before executing tasks
- **Step-by-Step Execution**: Executes each step methodically
- **Loop Detection**: Prevents infinite loops and repeated actions
- **Adaptive Planning**: Adjusts plan if something fails
- **Progress Tracking**: Shows thinking, progress, and stats

### Smart File Operations

- **Create/Read/Edit/Delete files** with intelligent handling
- **Smart Reading**: Line ranges, previews, search within files
- **Smart Search**: Find files by name pattern or content
- **Directory Exclusions**: Automatically skips .git, node_modules, **pycache**, etc.
- **Token Optimization**: 10K character limit prevents token explosion

### Safety Mechanisms

- **Iteration Limits**: Max 15 iterations to prevent runaway
- **Loop Detection**: Detects and warns about repeated actions
- **Action Tracking**: Prevents duplicate operations
- **Error Handling**: Graceful failure with helpful messages

## Project Structure

```
agent/
├── agent.py              # Core agentic logic with planning
├── tools.py              # Tool definitions for Anthropic API
├── tool_functions.py     # Tool implementations
├── examples.py           # Usage examples
├── .env                  # Configuration (API key)
└── README.md            # This file
```

## Quick Start

### 1. Installation

```bash
pip install anthropic python-dotenv
```

### 2. Configuration

Create a `.env` file:

```env
ANTHROPIC_API_KEY=your_api_key_here
ANTHROPIC_MODEL=claude-sonnet-4-5-20250929
ANTHROPIC_MAX_TOKENS=4096
```

### 3. Usage

#### Agentic Mode (Recommended)

```python
from agent import chat_with_tools_agentic

# Complex multi-step task with automatic planning
chat_with_tools_agentic(
    "Create a Python project with main.py, requirements.txt, and README.md. "
    "The main.py should have a hello world function."
)
```

#### Smple Mode

```python
from agent import chat_with_tools

# Direct tool usage without planning
chat_with_tools("Create a file called test.txt with hello world")
```

## How It Works

### Agentic Mode Flow

```
User Request
    ↓
1. Agent analyzes task
    ↓
2. Creates TODO listi/plan
    ↓
3. Shows plan to user
    ↓
4. Executes step-by-step
    ↓
5. Checks results
    ↓
6. Adapts if needed
    ↓
7. Final summary
```

### Safety Features

1. **Loop Detection**: Tracks all actions and prevents repeats
2. **Iteration Limit**: Max 15 iterations (configurable)
3. **Pattern Detection**: Warns if same tools used 3+ times
4. **Action History**: Remembers completed actions

## Available Tools

| Tool           | Description                                     |
| -------------- | ----------------------------------------------- |
| `create_file`  | Create files with content                       |
| `read_file`    | Smart reading with line ranges, search, preview |
| `edit_file`    | Replace or append content                       |
| `delete_file`  | Delete files                                    |
| `list_files`   | List directory contents (excludes build dirs)   |
| `smart_search` | Search by filename or content (recursive)       |

### Smart Reading Features

```python
# Preview a large file
"Preview the file 'large_dataset.csv'"

# Read specific lines
"Read lines 100 to 200 from 'app.log'"

# Search within file
"Find all ERROR messages in 'debug.log'"

# Character limit
"Read config.json but limit to 5000 characters"
```

## Example Tasks

### Project Creation

```python
chat_with_tools_agentic(
    "Create a Flask web app with proper structure: "
    "app.py, requirements.txt, README.md, and a templates folder"
)
```

### Code Analysis

```python
chat_with_tools_agentic(
    "Analyze all Python files, find TODO comments, "
    "and create a summary in todos.md"
)
```

### Refactoring

```python
chat_with_tools_agentic(
    "Find all files with 'old_function_name' and create a plan "
    "to refactor them to 'new_function_name'"
)
```

## Best Practices

### Do:

- Use agentic mode for complex multi-step tasks
- Let the agent create a plan first
- Provide clear, specific task descriptions
- Break down very large tasks into smaller ones

### Don't:

- Request tasks that would require >15 iterations
- Ask for operations on extremely large files without using smart reading
- Request recursive operations without clear boundaries

## Debugging

The agent shows detailed output:

- **Agent Thinking**: Planning and reasoning
- **Tool Used**: Which tool is being called
- **Input**: Tool parameters
- **Result**: Tool output
- **Stats**: Iterations and actions performed

## Safety & Limitations

- **Iteration Limit**: 15 iterations maximum
- **File Size**: 50KB+ files trigger warnings
- **Character Limit**: 10K default for reads
- **Loop Detection**: Prevents infinite loops
- **Excluded Dirs**: Skips .git, node_modules, etc.

## Contributing

Feel free to add new tools or improve the planning logic!

## License

MIT License - Feel free to use and modify!
