Metadata-Version: 2.4
Name: beamlab
Version: 0.2.3
Summary: A production-grade CLI AI coding agent
Project-URL: Homepage, https://github.com/devxyasir
Project-URL: Repository, https://github.com/devxyasir/beamlab
Project-URL: Bug Tracker, https://github.com/devxyasir/beamlab/issues
Author-email: "Muhammad Yasir (devxyasir)" <jamyasir0535@gmail.com>
Maintainer-email: devxyasir <jamyasir0535@gmail.com>
License: MIT
Keywords: agent,ai,cli,coding,llm
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.11
Requires-Dist: aiohttp>=3.9.0
Requires-Dist: anthropic>=0.28.0
Requires-Dist: ddgs>=9.0.0
Requires-Dist: faiss-cpu>=1.8.0
Requires-Dist: google-genai>=0.1.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: numpy>=1.26.0
Requires-Dist: openai>=1.30.0
Requires-Dist: prompt-toolkit>=3.0.43
Requires-Dist: python-dotenv>=1.0.1
Requires-Dist: rank-bm25>=0.2.2
Requires-Dist: rich>=13.7.0
Requires-Dist: sentence-transformers>=3.0.0
Requires-Dist: tomli>=2.0.1
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest-mock>=3.14.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# ⚡ BeamLab CLI

**A production-grade, autonomous AI coding agent for your terminal.**

BeamLab is a high-performance CLI agent designed to live in your codebase. It doesn't just chat—it searches, reads, reasons, and executes code changes with surgical precision. Powered by a multi-provider "cascade", it ensures you always have a brain online, even when APIs are down.

---

## 🚀 Quick Start

### 1. Installation
Install directly via pip:
```bash
pip install beamlab
```

### 2. Configure Your Keys
BeamLab uses environment variables for security. Add these to your shell profile (`.zshrc`, `.bashrc`, or PowerShell `$PROFILE`):

```bash
export LONGCAT_API_KEY="your-key-here"
```

Or use the `.agent.toml` configuration file in your project root:

```toml
[model]
longcat_api_key = "your-key-here"
```

### 3. Launch
Navigate to any project directory and start the session:
```bash
beamlab
```

---

## 🧠 Functional Overview

BeamLab operates as a **Stateful Agentic Loop**. When you give it a task, it follows a rigorous internal cycle:
1.  **Context Retrieval**: It perform semantic searches across your repo using a local **FAISS** vector store.
2.  **Reasoning**: It uses "Thinking" models to architect a solution.
3.  **Tool Execution**: It uses specialized tools for file I/O, code searching, shell commands, and web research.
4.  **Verification**: It can run tests and verify its own changes before handing the reins back to you.

---

## � Usage Guide

### Starting a Session

When you launch BeamLab in a project directory, it will:
- Load or create a session for that project
- Restore your previous conversation history (if any)
- Initialize the context with your project files

### Session Management

Sessions are isolated per project. Each session maintains its own:
- Conversation history
- Context files
- File modification undo stack

Use these commands to manage sessions:

| Command | Description | Usage |
| :--- | :--- | :--- |
| `/new` | Start a fresh session | `/new "Fixing Bug"` |
| `/sessions` | List all stored sessions | `/sessions` |
| `/switch` | Switch to a different session | `/switch 2` |
| `/clear` | Wipe current chat history | `/clear` |

### Model Selection

View available models and switch between them:

```
/model
```

Switch to a specific model:
```
/model longcat:Flash-Thinking
```

### Context Management

Add files to the context for the agent to reference:

```
/add src/main.py
/add tests/test_*.py
```

You can also reference files inline in your prompts:
```
Explain how @main.py works
```

### File Operations

BeamLab can read, write, and edit files. All write operations require approval by default.

To undo the last file modification:
```
/undo
```

---

## �🛠️ Interactive Slash Commands

While in the BeamLab REPL, you can use `/` commands to manage your session:

| Command | Description | Usage |
| :--- | :--- | :--- |
| `/help` | List all available commands | `/help` |
| `/sessions` | List all stored sessions for this project | `/sessions` |
| `/new` | Start a fresh named session | `/new "Fixing Bug"` |
| `/switch` | Switch to a different session by ID or number | `/switch 2` |
| `/model` | Show or change the active LLM | `/model` |
| `/add` | Manually pin a file to the context | `/add src/main.py` |
| `/undo` | Roll back the last file modification | `/undo` |
| `/clear` | Wipe the current chat history | `/clear` |

---

## ⚙️ Configuration (`.agent.toml`)

BeamLab looks for a `.agent.toml` file in your project root for local overrides.

```toml
[model]
primary     = "LongCat-Flash-Chat"
temperature = 0.1

[safety]
require_approval_for_writes = true   # Set to false for full autonomy
require_approval_for_shell  = true

[indexing]
exclude = [".git", "node_modules", "dist"]
```

### Configuration Options

**Model Settings:**
- `primary`: The primary model to use
- `temperature`: Sampling temperature (0.0 to 1.0)
- `longcat_api_key`: Your LongCat API key (can also use env var)

**Safety Settings:**
- `require_approval_for_writes`: Require confirmation before file writes
- `require_approval_for_shell`: Require confirmation before shell commands

**Indexing Settings:**
- `exclude`: Patterns to exclude from codebase indexing

---

## 🛡️ Safety First

BeamLab is built with a **Security-First** mindset:
- **Write Guard**: Every file modification requires your explicit approval by default.
- **Shell Guard**: No `rm -rf` or arbitrary commands run without a "Y/N" confirmation.
- **Path Restricted**: The agent is restricted to working within your project root unless specified otherwise.

---

## 🔧 Advanced Features

### Provider Cascade

BeamLab automatically handles provider failures by cascading to available alternatives:
1. **LongCat** (primary) - Your main provider
2. **Ollama** (local) - Running locally for offline usage

If the primary provider fails, BeamLab will automatically try the next available provider.

### Session Persistence

Your sessions are automatically saved and restored:
- Sessions persist across restarts
- Each project has isolated sessions
- Switch between sessions without losing context

### Intelligent Context

BeamLab builds context intelligently:
- Indexes your codebase for semantic search
- Tracks file references in conversation
- Maintains conversation history within sessions

---

## 👤 Author

**Muhammad Yasir (devxyasir)**  
Email: [jamyasir0535@gmail.com](mailto:jamyasir0535@gmail.com)  
GitHub: [devxyasir/beamlab](https://github.com/devxyasir/beamlab)

---

*Developed with love for the Python community. ⚡🚀*