Metadata-Version: 2.4
Name: exobrain
Version: 0.0.8
Summary: A personal AI assistant with agent capabilities, knowledge retrieval, and file system access
Project-URL: Homepage, https://github.com/visualDust/exobrain
Project-URL: Repository, https://github.com/visualDust/exobrain
Author-email: VisualDust <gavin@gong.host>
License-Expression: MIT
License-File: LICENSE
Keywords: agent,ai,assistant,cli,knowledge-base
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: <4,>=3.10
Requires-Dist: aiofiles<24,>=23.2.1
Requires-Dist: beautifulsoup4<5,>=4.12.0
Requires-Dist: click<9,>=8.1.7
Requires-Dist: ddgs>=9.5.2
Requires-Dist: httpx<0.27,>=0.26.0
Requires-Dist: lxml<6,>=5.0.0
Requires-Dist: pre-commit>=3.8.0
Requires-Dist: pydantic-settings<3,>=2.1.0
Requires-Dist: pydantic<3,>=2.5.0
Requires-Dist: python-dotenv<2,>=1.0.0
Requires-Dist: pyyaml<7,>=6.0.1
Requires-Dist: rich<14,>=13.7.0
Requires-Dist: textual>=0.89.0
Provides-Extra: all
Requires-Dist: anthropic<0.9,>=0.8.0; extra == 'all'
Requires-Dist: openai<2,>=1.7.0; extra == 'all'
Provides-Extra: anthropic
Requires-Dist: anthropic<0.9,>=0.8.0; extra == 'anthropic'
Provides-Extra: openai
Requires-Dist: openai<2,>=1.7.0; extra == 'openai'
Description-Content-Type: text/markdown

# ExoBrain

![PyPI - Version](https://img.shields.io/pypi/v/exobrain)
[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A powerful personal AI assistant with agent capabilities, featuring knowledge retrieval, file system access, and highly configurable extensibility. Made with ❤️.

## ✨ Features

### 🤖 Core Capabilities

- **Multi-Model Support**: Local open-source models (via LM Studio, Ollama) and cloud APIs (OpenAI, Google Gemini)
- **Agent Skills**: Integrated Anthropic Skills including document processing (PDF/Word/Excel/PPT), MCP development, frontend design, and more
- **Hierarchical Configuration**: Project-level and user-level config with clear priority
- **Session Management**: Separate project and user session storage with smart management
- **Constitutional AI**: Built-in constitution file support for behavioral guidelines

### 🛠️ Tool System

- **File System Access**: Secure file reading/writing with granular permissions
- **Web Search & Fetch**: Built-in web search and page content extraction
- **Shell Execution**: Controlled command execution with whitelist/blacklist
- **Knowledge Base**: Vector database-based semantic search and RAG
- **Progressive Exposure**: Smart tool exposure based on context

### 🔒 Privacy & Security

- **Permission System**: Runtime permission requests with once/session/always scopes
- **Access Control**: Fine-grained path and command restrictions
- **Local-First**: Optional local model inference and data storage
- **Audit Logging**: Complete operation tracking

### 💻 User Experience

- **Rich CLI**: Friendly command-line interface with markdown rendering
- **Streaming Responses**: Real-time output for better interactivity
- **Verbose Mode**: Detailed tool execution info for debugging
- **Session History**: Browse and resume previous conversations
- **MCP Support**: Model Context Protocol integration

## 🚀 Quick Start

### Installation

Install ExoBrain via pip:

```bash
pip install exobrain
```

Or install from source (development mode):

```bash
# Clone the repository
git clone https://github.com/visualdust/exobrain.git
cd exobrain

# Initialize Skills submodule
git submodule update --init --recursive

# Install with uv (recommended)
uv sync

# Or with pip
pip install -e .
```

### Initial Setup

Run the interactive configuration wizard:

```bash
exobrain config init
```

This will guide you through:

- Selecting AI model providers (OpenAI, Gemini, or local models)
- Configuring API keys
- Setting up basic features and permissions

### Basic Usage

```bash
# Start interactive chat
exobrain chat

# Ask a single question
exobrain ask "What is the weather today?"

# Use verbose mode to see tool execution details
exobrain ask "Search for latest AI news" --verbose

# Chat with specific model
exobrain chat --model openai/gpt-4o

# Use project-level or global sessions
exobrain chat --project   # Store in ./.exobrain/conversations
exobrain chat --global    # Store in ~/.exobrain/data/conversations
exobrain chat --continue  # Continue last session (auto-detect)
```

## 📋 Configuration

ExoBrain uses a hierarchical configuration system with the following priority (highest to lowest):

1. **Project-level config**: `./.exobrain/config.yaml` (highest priority)
2. **Global user config**: `~/.config/exobrain/config.yaml`
3. **Default config**: Built-in defaults

### Configuration File Structure

```yaml
# Model Configuration
models:
  default: openai/gpt-5-mini
  providers:
    openai:
      api_key: sk-...
      base_url: https://api.openai.com/v1
      models:
        - gpt-5-pro
        - gpt-5-mini
        - gpt-4o
    local:
      base_url: http://localhost:8000/v1
      models:
        - Qwen/Qwen3-30B-A3B-Instruct-2507-FP8

# Agent Configuration
agent:
  system_prompt: "You are ExoBrain, a personal AI assistant..."
  constitution_file: CONSTITUTION.md # Behavioral guidelines
  max_conversation_turns: 20
  max_iterations: 100 # Maximum tool calling iterations per message
  stream: true

# Tools Configuration
tools:
  file_system: true
  web_access: true
  shell_execution: true
  time_management: true

# Permissions Configuration
permissions:
  file_system:
    enabled: true
    allowed_paths:
      - ~/Documents
      - ~/repos
    denied_paths:
      - ~/.ssh
      - ~/.aws
    confirm_write: true
    confirm_delete: true

  shell_execution:
    enabled: true
    confirm_execution: false
    allowed_directories:
      - ~/repos
    denied_directories:
      - ~/.ssh
      - /etc
    allowed_commands:
      - ls *
      - git *
      - python *
    denied_commands:
      - rm -rf /
      - sudo *

  web_access:
    enabled: true
    max_results: 5
    max_content_length: 10000

# Skills Configuration
skills:
  enabled: true
  skills_dir: ~/.exobrain/skills
  builtin_skills:
    - note_manager
  auto_load: true
```

### Managing Configuration

Exobrain checks for configuration files in the following locations:

- Global configuration file is located at `~/.config/exobrain/config.yaml`.
- Project-level config can be created in your project directory at `./.exobrain/config.yaml`.

```bash
# View current configuration
exobrain config show

# Edit configuration in editor
exobrain config edit

# Set specific value
exobrain config set agent.max_iterations 50

# Get specific value
exobrain config get models.default

# List available models
exobrain models list

# Set default model
exobrain models use openai/gpt-5-pro
```

## 🎯 Core Features

### Session Management

ExoBrain supports both project-level and user-level session storage:

```bash
# List all sessions (shows both project and user sessions)
exobrain sessions list

# Show session details
exobrain sessions show <session-id>

# Delete sessions
exobrain sessions delete <session-id-1> <session-id-2>
exobrain sessions delete --all --yes

# Chat in specific mode
exobrain chat --project    # Project-level session
exobrain chat --global     # User-level session (global)
exobrain chat --continue   # Continue last session (auto-detect)
```

### Knowledge Base (still under development)

```bash
# Add documents to knowledge base
exobrain knowledge add ~/Documents/notes/

# Search knowledge base
exobrain knowledge search "Python decorators"

# List indexed documents
exobrain knowledge list

# Remove documents
exobrain knowledge remove <doc-id>
```

### Skills System

```bash
# List available skills
exobrain skills list

# Search skills
exobrain skills list --search "pdf"

# Show skill details
exobrain skills show mcp-builder

# Skills are automatically activated during conversation
exobrain chat
You: Help me create a PDF report
# Agent automatically uses the pdf skill
```

### Web Search

Enable web access in your config:

```yaml
tools:
  web_access: true

permissions:
  web_access:
    enabled: true
```

Then use naturally in conversation:

```bash
exobrain ask "Search for latest developments in quantum computing"
exobrain ask "Fetch the content from https://example.com"
```

## 🔧 Advanced Usage

### Verbose Mode

See detailed tool execution information:

```bash
exobrain ask "What files are in my Documents folder?" --verbose
```

Output shows tool calls and their results (first 3 lines):

```
[TOOL RESULT] list_directory:
dir           0 Projects
dir           0 Notes
... (45 more lines)
```

### Permission System

ExoBrain requests permission for sensitive operations:

- **Once**: Grant permission for this operation only
- **Session**: Grant for this chat session
- **Always**: Add to config permanently

Example:

```
╭─────────────── Permission Request ───────────────╮
│ ⚠️  Permission Required                          │
│                                                  │
│   Tool      shell_execute                        │
│   Action    Execute shell command                │
│   Resource  git status                           │
│   Reason    Command not in allowed list          │
│                                                  │
│  Grant permission for this action?               │
│                                                  │
│    [y] Yes, once       [n] No                    │
│    [s] Yes, session    [a] Yes, always           │
╰──────────────────────────────────────────────────╯

Your choice [y/n/s/a] (n):
```

### Constitutional AI

Create a `CONSTITUTION.md` file to define behavioral guidelines:

```markdown
# ExoBrain Constitution

## Core Principles

1. Be helpful, harmless, and honest
2. Respect user privacy and data security
3. Provide accurate and verifiable information

## Behavioral Guidelines

- Always explain your reasoning
- Admit when you don't know something
- Suggest multiple approaches when possible
  ...
```

Reference it in your config:

```yaml
agent:
  constitution_file: CONSTITUTION.md
```

CLI also manages constitution:

```bash
> exobrain constitution

Usage: exobrain constitution [OPTIONS] COMMAND [ARGS]...

  Manage agent constitutions (personalities).

Options:
  --help  Show this message and exit.

Commands:
  create      Create a new constitution file.
  deactivate  Deactivate constitution (no personality will be sent to the...
  edit        Edit a constitution file.
  list        List all available constitutions.
  path        Show the path to the constitutions directory.
  show        Show the content of a constitution.
  use         Switch to a different constitution (personality).
```

## 🏗️ Project Structure

```
exobrain/
├── exobrain/
│   ├── agent/          # Core agent implementation
│   ├── cli/            # Command-line interface
│   ├── config.py       # Configuration management
│   ├── models/         # Model providers (OpenAI, Gemini, Local)
│   ├── tools/          # Built-in tools (file, web, shell, etc.)
│   ├── skills/         # Skills system and Anthropic Skills
│   ├── knowledge/      # Knowledge base and RAG
│   ├── memory/         # Conversation persistence
│   └── mcp/            # Model Context Protocol integration
├── config.yaml         # Project configuration (development)
├── CONSTITUTION.md     # Behavioral guidelines
└── README.md          # This file
```

## 🛠️ Development

### Setting Up Development Environment

```bash
# Clone repository
git clone https://github.com/visualdust/exobrain.git
cd exobrain

# Install with development dependencies
uv sync

# Install pre-commit hooks
uv run pre-commit install

# Run tests
pytest

# Format code
black .
ruff check --fix .

# Type checking
mypy exobrain
```

### Running Tests

```bash
# Run all tests
pytest

# Run with coverage
pytest --cov=exobrain --cov-report=html

# Run specific test file
pytest tests/test_agent.py
```

### Contributing

We welcome contributions! Please:

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## 📚 Documentation

Most documentations are generated by AI.

- [Architecture Design](docs/ARCHITECTURE.md) - System architecture and design principles
- [Technical Specifications](docs/SPECIFICATIONS.md) - Detailed technical specs and APIs
- [Skills Integration Guide](docs/SKILLS_INTEGRATION.md) - Using and developing Anthropic Skills
- [Skills Development](exobrain/skills/README.md) - Creating custom skills
- [Knowledge Base](exobrain/knowledge/README.md) - Knowledge base system
- [MCP Integration](exobrain/mcp/README.md) - MCP server integration guide

## 🙏 Acknowledgements

See also:

- [LangChain](https://github.com/langchain-ai/langchain)
- [AutoGPT](https://github.com/Significant-Gravitas/AutoGPT)
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [Anthropic Skills](https://github.com/anthropics/skills)

## 📄 License

MIT License - see the [LICENSE](LICENSE) file for details.
