Metadata-Version: 2.3
Name: consoul
Version: 0.2.1
Summary: AI-powered terminal assistant with rich TUI - brings ChatGPT/Claude to your command line
License: Apache-2.0
Keywords: ai,assistant,terminal,tui,cli,chatgpt,claude,langchain,textual
Author: GoatBytes.IO
Author-email: jared@goatbytes.io
Maintainer: GoatBytes.IO
Maintainer-email: jared@goatbytes.io
Requires-Python: >=3.10
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Terminals
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Provides-Extra: all
Provides-Extra: huggingface-local
Provides-Extra: huggingface-quantization
Provides-Extra: llamacpp
Provides-Extra: mlx
Provides-Extra: ollama-library
Provides-Extra: pdf
Provides-Extra: tui
Requires-Dist: accelerate (>=1.2.0) ; extra == "huggingface-local"
Requires-Dist: accelerate (>=1.2.0) ; extra == "huggingface-quantization"
Requires-Dist: beautifulsoup4 (>=4.12.0) ; extra == "all"
Requires-Dist: beautifulsoup4 (>=4.12.0) ; extra == "ollama-library"
Requires-Dist: bitsandbytes (>=0.45.0) ; extra == "huggingface-quantization"
Requires-Dist: click (>=8.3.1) ; extra == "all"
Requires-Dist: click (>=8.3.1) ; extra == "tui"
Requires-Dist: ddgs (>=9.9.0)
Requires-Dist: diskcache (>=5.6.3)
Requires-Dist: duckduckgo-search (>=8.1.1)
Requires-Dist: grep-ast (>=0.9.0)
Requires-Dist: langchain (>=1.0.7)
Requires-Dist: langchain-anthropic (>=1.0.4)
Requires-Dist: langchain-community (>=0.4.1,<0.5.0)
Requires-Dist: langchain-google-genai (>=3.0.3)
Requires-Dist: langchain-huggingface (>=1.0.1)
Requires-Dist: langchain-ollama (>=1.0.0)
Requires-Dist: langchain-openai (>=1.0.3)
Requires-Dist: llama-cpp-python (>=0.3.0) ; extra == "llamacpp"
Requires-Dist: mlx-lm (>=0.28.0) ; extra == "mlx"
Requires-Dist: pillow (>=10.0.0) ; extra == "all"
Requires-Dist: pillow (>=10.0.0) ; extra == "tui"
Requires-Dist: prompt-toolkit (>=3.0.52,<4.0.0)
Requires-Dist: pydantic (>=2.12.4)
Requires-Dist: pydantic-settings (>=2.12.0)
Requires-Dist: pypdf (>=6.2.0) ; extra == "all"
Requires-Dist: pypdf (>=6.2.0) ; extra == "pdf"
Requires-Dist: pyperclip (>=1.11.0) ; extra == "all"
Requires-Dist: pyperclip (>=1.11.0) ; extra == "tui"
Requires-Dist: python-dotenv (>=1.2.1)
Requires-Dist: pyyaml (>=6.0.3,<7.0.0)
Requires-Dist: requests (>=2.32.5)
Requires-Dist: rich (>=14.2.0)
Requires-Dist: textual (>=6.6.0) ; extra == "all"
Requires-Dist: textual (>=6.6.0) ; extra == "tui"
Requires-Dist: tiktoken (>=0.12.0)
Requires-Dist: torch (>=2.4.0,<2.5.0) ; extra == "huggingface-local"
Requires-Dist: torch (>=2.4.0,<2.5.0) ; extra == "huggingface-quantization"
Requires-Dist: trafilatura (>=2.0.0,<3.0.0)
Requires-Dist: transformers (>=4.45.0) ; extra == "huggingface-local"
Requires-Dist: transformers (>=4.45.0) ; extra == "huggingface-quantization"
Requires-Dist: tree-sitter (>=0.25.2)
Requires-Dist: tree-sitter-language-pack (>=0.11.0)
Project-URL: Changelog, https://github.com/goatbytes/consoul/blob/main/CHANGELOG.md
Project-URL: Documentation, https://consoul.goatbytes.io
Project-URL: Homepage, https://github.com/goatbytes/consoul
Project-URL: Issues, https://github.com/goatbytes/consoul/issues
Project-URL: Repository, https://github.com/goatbytes/consoul
Description-Content-Type: text/markdown

![Consoul Banner](.art/banner/consoul-banner-100.jpg)

# Consoul

**AI-Powered Terminal Assistant** — Beautiful TUI · Powerful CLI · Flexible SDK

Bring modern AI assistance directly to your terminal. Chat with Claude, GPT-4, Gemini, and local models using a rich interactive interface or simple CLI commands.

📖 **[Full Documentation](https://consoul.goatbytes.io)** | 🚀 [Quick Start](#quick-start) | 🎨 [Features](#features)

---

## Quick Start

### Installation

```bash
pip install consoul
```

### Set Your API Key

```bash
# Choose your provider
export ANTHROPIC_API_KEY=your-key-here  # Claude
export OPENAI_API_KEY=your-key-here     # GPT-4
export GOOGLE_API_KEY=your-key-here     # Gemini
```

### Launch the TUI

```bash
consoul tui
```

### Or Use the SDK

```python
from consoul import Consoul

console = Consoul()
print(console.chat("What is 2+2?"))
```

---

## Features

### 🎨 Beautiful TUI
Rich, interactive terminal interface powered by [Textual](https://textual.textualize.io/)

![Consoul TUI](.art/consoul-demo.gif)

- Multi-turn conversations with streaming responses
- Conversation history and search
- File attachments and image analysis
- Customizable themes (light/dark)
- Mouse and keyboard navigation

### 🤖 Multi-Provider Support
Use your favorite AI model or run locally:

- **Anthropic Claude** - Claude 4.5 Sonnet, Opus, Haiku
- **OpenAI** - GPT-5, GPT-4, GPT-3.5
- **Google Gemini** - Gemini 3 Flash, Pro
- **Ollama** - Run models locally (Llama, Qwen, GPT-OSS etc.)
- **LlamaCpp** - GGUF/MLX models with GPU acceleration

### 🛠️ AI-Powered Tools

**File Editing**
Let AI create, modify, and delete files with safety controls:
```bash
consoul ask "Add error handling to calculate_total in src/utils.py" --tools
```

**Code Search**
Navigate your codebase semantically:
```bash
consoul ask "Find all usages of deprecated_function" --tools
```

**Image Analysis**
Debug with screenshots:
```bash
consoul ask "What's wrong with this error?" --attach screenshot.png
```

**And More:**
- Bash command execution with approval workflows
- Web search and URL fetching
- Session management and history

### 📝 Simple CLI

For quick questions without the TUI:

```bash
# One-off questions
consoul ask "Explain Python decorators"

# Interactive chat mode
consoul chat
```

### 🔌 SDK Integration

Embed AI capabilities in your Python applications:

```python
from consoul import Consoul

# Enable tools for file operations and code search
console = Consoul(tools=True)

# Stateful conversation
console.chat("List all TODO comments in Python files")
console.chat("Create a summary.md file with the results")

# Rich responses with metadata
response = console.ask("Summarize this project", show_tokens=True)
print(f"Tokens: {response.tokens}")
print(f"Cost: ${console.last_cost['total_cost']:.4f}")
```

---

## Documentation

📖 **[Full Documentation](https://consoul.goatbytes.io)**

**Getting Started:**
- [Installation Guide](https://consoul.goatbytes.io/installation/)
- [Quick Start](https://consoul.goatbytes.io/quickstart/)
- [Configuration](https://consoul.goatbytes.io/user-guide/configuration/)

**TUI:**
- [Interface Guide](https://consoul.goatbytes.io/user-guide/tui/interface/)
- [Keyboard Shortcuts](https://consoul.goatbytes.io/user-guide/tui/keyboard-shortcuts/)
- [Themes](https://consoul.goatbytes.io/user-guide/tui/themes/)

**Tools:**
- [File Editing](https://consoul.goatbytes.io/user-guide/file-editing/)
- [Image Analysis](https://consoul.goatbytes.io/user-guide/image-analysis/)
- [Code Search](https://consoul.goatbytes.io/user-guide/code-search/)

**SDK:**
- [SDK Overview](https://consoul.goatbytes.io/api/)
- [Tutorial](https://consoul.goatbytes.io/api/tutorial/)
- [API Reference](https://consoul.goatbytes.io/api/reference/)

---

## Configuration

Create `~/.consoul/config.yaml`:

```yaml
# Default profile
profiles:
  default:
    model:
      provider: anthropic
      model: claude-3-5-sonnet-20241022
      temperature: 0.7

    tools:
      enabled: true
      permission_policy: balanced  # Require approval for risky operations

    conversation:
      save_history: true
      max_history: 50

  # Local model profile
  local:
    model:
      provider: ollama
      model: llama3.2:latest
```

**Switch profiles:**
```bash
consoul --profile local
```

See the [Configuration Guide](https://consoul.goatbytes.io/user-guide/configuration/) for all options.

---

## Security

Consoul includes comprehensive security controls for tool execution:

- **Permission Policies** - PARANOID, BALANCED, TRUSTING, UNRESTRICTED
- **Approval Workflows** - Interactive confirmation for dangerous operations
- **Audit Logging** - Complete execution history in JSONL format
- **Command Validation** - Pattern-based blocking of risky commands

See the [Security Policy](SECURITY.md) for best practices.

---

## Contributing

Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

---

## License

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

---

## Built With

- [Textual](https://textual.textualize.io/) - Beautiful TUI framework
- [LangChain](https://python.langchain.com/) - AI orchestration
- [Anthropic](https://www.anthropic.com/) - Claude AI models
- [OpenAI](https://openai.com/) - GPT models
- [Google AI](https://ai.google.dev/) - Gemini models

---

**Made with ❤️ by [GoatBytes.IO](https://goatbytes.io)**

