Content
<p align="center">
<a href="https://www.vectorly.app/"><img src="https://img.shields.io/badge/Website-Vectorly.app-0ea5e9?style=for-the-badge&logo=googlechrome&logoColor=white" /></a>
<a href="https://console.vectorly.app"><img src="https://img.shields.io/badge/Console-console.vectorly.app-8b5cf6?style=for-the-badge&logo=googlechrome&logoColor=white" /></a>
<a href="https://vectorly.app/discord-invite"><img src="https://img.shields.io/badge/Discord-Join%20our%20server-5865F2?style=for-the-badge&logo=discord&logoColor=white" /></a>
<a href="https://www.youtube.com/@VectorlyAI"><img src="https://img.shields.io/badge/YouTube-@VectorlyAI-ff0000?style=for-the-badge&logo=youtube&logoColor=white" /></a>
<a href="https://www.apache.org/licenses/LICENSE-2.0"><img src="https://img.shields.io/badge/License-Apache%202.0-10b981?style=for-the-badge&logo=apache&logoColor=white" /></a>
# bluebox 🟦
Index the world's undocumented APIs.
**Why "Blue Box"?** Named after the [phone phreaking devices](https://en.wikipedia.org/wiki/Blue_box) that let tech enthusiasts in the 1960s and 70s explore telephone networks.
**You are in the right place if you ...**
* need to scrape data behind UI interactions
* are dealing with closed APIs
* want to reverse engineer websites
## Tutorial
https://github.com/user-attachments/assets/934728e1-1384-4b44-a7b0-d93480d329de
## Prerequisites
- Python 3.12+
- Vectorly API key (required, used by `bluebox` agent for web data extraction)
- Sign up at [console.vectorly.app](https://console.vectorly.app)
- macOS/Linux: `export VECTORLY_SERVICE_TOKEN="your-key"`
- Windows (PowerShell): `setx VECTORLY_SERVICE_TOKEN "your-key"`
- Or add it to your `.env` file: `VECTORLY_SERVICE_TOKEN=your-key`
- LLM provider API key (required, used by `bluebox` agent for orchestration)
- Configure one of the following:
- OpenAI (default):
- macOS/Linux: `export OPENAI_API_KEY="your-key"`
- Windows (PowerShell): `setx OPENAI_API_KEY "your-key"`
- `.env`: `OPENAI_API_KEY=your-key`
- Anthropic:
- macOS/Linux: `export ANTHROPIC_API_KEY="your-key"`
- Windows (PowerShell): `setx ANTHROPIC_API_KEY "your-key"`
- `.env`: `ANTHROPIC_API_KEY=your-key`
- [uv](https://github.com/astral-sh/uv) (optional, for dependency management)
- macOS/Linux: `curl -LsSf https://astral.sh/uv/install.sh | sh`
- Windows (PowerShell): `iwr https://astral.sh/uv/install.ps1 -UseBasicParsing | iex`
## Installation
```bash
# Clone the repository
git clone https://github.com/VectorlyApp/bluebox.git
cd bluebox
# Create and activate virtual environment
python3 -m venv bluebox-env
source bluebox-env/bin/activate # On Windows: bluebox-env\Scripts\activate
# Install in editable mode
pip install -e .
# Or using uv (faster)
uv venv bluebox-env
source bluebox-env/bin/activate
uv pip install -e .
```
## Bluebox agent
The `bluebox` agent is a conversational AI agent that automates web data extraction. It searches the Vectorly web routine index for relevant web APIs, executes matched endpoints in parallel, and falls back to a live AI browser agent when no suitable pre-built routine is available.
### Quickstart
```bash
# run with OpenAI models
bluebox-agent --model gpt-5.2
# run with Anthropic models
bluebox-agent --model claude-opus-4-5
```
**What it does:**
- Interprets natural language requests and maps them to relevant routines
- Executes multiple routines concurrently for faster results
- Falls back to an AI browser agent for tasks without predefined routines
- Post-processes outputs using Python (CSV, JSON, etc.)
- Saves generated files to a local workspace
- Generates reusable context files to replay successful sessions instantly
Ask it anything: *"Run a price analysis on Rolex Sea Dweller 16600"* — the agent automatically selects the right routine, runs it, and delivers structured results.
### Context (session replay)
After a successful session, run `/generate_context` to save a snapshot of what worked — the goal, routines called (with exact parameters), any Python post-processing code, and output descriptions. Context files are saved to the workspace `context/` directory in both JSON and Markdown formats.
When the agent starts a new session, it automatically loads the most recent context file and injects it into the system prompt. This lets the agent skip trial and error and directly replay the known-good path, adjusting parameters as needed for the new request.
You can also load a specific context file explicitly:
```bash
bluebox-agent --context-file path/to/agent_context.json
```
## Create your own routines
To learn about the core technology powering BlueBox, see [routine_discovery.md](docs/routine_discovery.md).
## Contributing 🤝
We welcome contributions! Here's how to get started:
1. **Report bugs or request features** — Open an [issue](https://github.com/VectorlyApp/bluebox/issues)
2. **Submit code** — Fork the repo and open a [pull request](https://github.com/VectorlyApp/bluebox/pulls)
3. **Test your code** — Add unit tests and make sure all tests pass:
```bash
python -m pytest tests/ -v
```
Please follow existing code style and include tests for new features.
