acorn-agent 2.1.0__tar.gz

acorn_agent-2.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andama Godwin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

acorn_agent-2.1.0/PKG-INFO

@@ -0,0 +1,345 @@
+Metadata-Version: 2.4
+Name: acorn-agent
+Version: 2.1.0
+Summary: An autonomous coding agent that lives in your terminal — powered by Gemini 3.1 Pro
+Home-page: https://github.com/andamagodwin/Acorn
+Author: Andama Godwin
+Author-email: Andama Godwin <andamagodwin@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/andamagodwin/acorn
+Project-URL: Repository, https://github.com/andamagodwin/acorn
+Project-URL: Issues, https://github.com/andamagodwin/acorn/issues
+Keywords: ai,coding-agent,gemini,vertex-ai,cli,autonomous
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Intended Audience :: Developers
+Classifier: Environment :: Console
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: google-genai>=1.0.0
+Dynamic: author
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-python
+
+# Acorn
+
+**An autonomous coding agent that lives in your terminal.**
+
+Acorn reads your code, writes files, runs commands, and refactors across your entire codebase — powered by Google's Gemini 3.1 Pro via Vertex AI.
+
+```
+     █████╗  ██████╗ ██████╗ ██████╗ ███╗   ██╗
+    ██╔══██╗██╔════╝██╔═══██╗██╔══██╗████╗  ██║
+    ███████║██║     ██║   ██║██████╔╝██╔██╗ ██║
+    ██╔══██║██║     ██║   ██║██╔══██╗██║╚██╗██║
+    ██║  ██║╚██████╗╚██████╔╝██║  ██║██║ ╚████║
+    ╚═╝  ╚═╝ ╚═════╝ ╚═════╝ ╚═╝  ╚═╝╚═╝  ╚═══╝
+```
+
+## Features
+
+- **Streaming responses** — see output as it's generated
+- **Smart model routing** — Flash for simple questions, Pro for complex tasks
+- **Surgical file editing** — modifies specific lines, not entire files
+- **Multi-file refactoring** — reads and edits across your whole codebase
+- **Image/screenshot analysis** — attach images for the model to analyze
+- **Auto-retry with error recovery** — adapts when things fail
+- **Session persistence** — resume conversations where you left off
+- **Undo support** — revert the last file change instantly
+- **Cost tracking** — see what you're spending per session
+- **Project config** — per-repo `.acorn.toml` for custom settings
+- **Permission system** — 3-tier safety (safe/ask/deny)
+- **Git-aware** — understands your branch, status, and project structure
+
+---
+
+## Quick Start
+
+```bash
+# Install from PyPI (easiest)
+pip install acorn-agent
+
+# Or install from GitHub
+pip install git+https://github.com/andamagodwin/acorn.git
+
+# Run it
+acorn
+```
+
+On first run it will ask for your GCP project ID. That's it.
+
+---
+
+## Installation (Full Guide)
+
+### Prerequisites
+
+| Requirement | Why |
+|-------------|-----|
+| Python 3.11+ | Runtime |
+| Google Cloud account | Vertex AI access |
+| `gcloud` CLI | Authentication |
+
+### Step 1: Clone and Install
+
+```bash
+git clone https://github.com/andamagodwin/acorn.git
+cd acorn
+pip install -e .
+```
+
+This installs `acorn` as a global command you can run from anywhere.
+
+### Step 2: Set Up Google Cloud
+
+You need a GCP project with Vertex AI API enabled and authentication configured.
+
+```bash
+# Install gcloud CLI if you don't have it
+# https://cloud.google.com/sdk/docs/install
+
+# Login to Google Cloud
+gcloud auth login
+gcloud auth application-default login
+
+# Set your project
+gcloud config set project YOUR_PROJECT_ID
+```
+
+### Step 3: Enable Vertex AI API
+
+```bash
+gcloud services enable aiplatform.googleapis.com
+```
+
+Or enable it in the console: https://console.cloud.google.com/apis/library/aiplatform.googleapis.com
+
+### Step 4: Configure Your Project ID
+
+Edit `acorn/config/settings.py` and set your project:
+
+```python
+project: str = "your-gcp-project-id"
+```
+
+Or use the CLI flag:
+
+```bash
+acorn --project your-gcp-project-id
+```
+
+Or use a `.acorn.toml` in your repo (see below).
+
+### Step 5: Run
+
+```bash
+cd ~/your-project
+acorn
+```
+
+---
+
+## Usage
+
+```bash
+# Start in current directory
+acorn
+
+# Use a specific model
+acorn --model gemini-2.5-flash
+
+# List available models
+acorn --models
+
+# Disable streaming
+acorn --no-stream
+
+# Disable smart routing (always use Pro)
+acorn --no-routing
+
+# Auto-approve all file writes (careful!)
+acorn --unsafe
+
+# Override GCP project
+acorn --project my-project-id
+
+# Help
+acorn --help
+```
+
+### Attach Images
+
+Just include an image path in your message:
+
+```
+> what's wrong in screenshot.png
+> implement the design in mockup.jpg
+```
+
+Gemini will analyze the image and respond accordingly.
+
+---
+
+## Commands
+
+| Command | What it does |
+|---------|--------------|
+| `/help` | Show all commands |
+| `/model <name>` | Switch model (or list available) |
+| `/cost` | Show session cost breakdown |
+| `/status` | Token usage, routing stats, cost |
+| `/plan` | Show current task execution plan |
+| `/undo` | Revert the last file change |
+| `/clear` | Reset context and session |
+| `/sessions` | List saved sessions |
+| `/routing on\|off` | Toggle smart routing |
+| `/exit` | Quit |
+
+---
+
+## Project Configuration
+
+Drop a `.acorn.toml` in any project root to customize Acorn's behavior for that repo:
+
+```toml
+[model]
+pro = "gemini-2.5-pro"
+flash = "gemini-2.5-flash"
+temperature = 0.2
+max_output_tokens = 65536
+
+[routing]
+enabled = true
+threshold = 200
+
+[project]
+gcp_project = "your-project-id"
+location = "us-central1"
+
+[permissions]
+safe_commands = [
+    "npm run", "npm test", "cargo build",
+    "python -m pytest", "make",
+]
+```
+
+Acorn auto-detects this file by walking up from your working directory.
+
+---
+
+## For Collaborators
+
+### Joining the Project
+
+1. Get added as a collaborator on the GitHub repo
+2. Clone and install:
+   ```bash
+   git clone https://github.com/andamagodwin/acorn.git
+   cd acorn
+   pip install -e .
+   ```
+3. Set up GCP authentication:
+   ```bash
+   gcloud auth login
+   gcloud auth application-default login
+   ```
+4. Ask the project owner to add you to the GCP project with the **"Vertex AI User"** role in IAM
+5. Run `acorn` from any directory
+
+### IAM Setup (For Project Owner)
+
+To add a collaborator to your GCP project:
+
+```bash
+gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
+  --member="user:their-email@gmail.com" \
+  --role="roles/aiplatform.user"
+```
+
+Or in the console: IAM & Admin > IAM > Grant Access > Role: "Vertex AI User"
+
+---
+
+## Architecture
+
+```
+acorn/
+├── config/
+│   ├── settings.py        — Models, permissions, safety rules
+│   └── project_config.py  — .acorn.toml loader
+├── core/
+│   ├── agent.py           — Main brain: streaming agentic loop
+│   ├── context.py         — Context window with auto-compaction
+│   ├── costs.py           — Token usage and cost tracking
+│   ├── planner.py         — Multi-step task planning
+│   ├── router.py          — Smart model routing (Flash vs Pro)
+│   └── session.py         — Session persistence to ~/.acorn/sessions/
+├── tools/
+│   ├── filesystem.py      — Read, write, edit, search, list
+│   ├── terminal.py        — Command execution with timeout
+│   └── git_tools.py       — Git-aware project understanding
+├── ui/
+│   └── terminal_ui.py     — Terminal UI with markdown rendering
+└── main.py                — CLI entry point
+```
+
+---
+
+## How It Works
+
+1. You type a message
+2. Acorn routes it to Flash (simple) or Pro (complex)
+3. The model calls tools — reads files, edits code, runs commands
+4. Tool results feed back for up to 25 iterations per turn
+5. If something fails, it sees the error and adapts
+6. Final response renders with markdown formatting
+
+---
+
+## Safety
+
+| Layer | What it does |
+|-------|--------------|
+| Blocked commands | `rm -rf /`, `mkfs`, fork bombs — permanently blocked |
+| Safe commands | `ls`, `git status`, `grep` — auto-execute |
+| Permission prompts | File writes, unknown commands — asks you first |
+| File backups | Every edit is backed up for `/undo` |
+| Context isolation | Won't touch `.env` files or expose secrets |
+
+---
+
+## Cost
+
+| Model | Input | Output | Typical session |
+|-------|-------|--------|-----------------|
+| Gemini 3.1 Pro | $1.25/M tokens | $10.00/M tokens | $0.50–$2.00 |
+| Gemini 2.5 Flash | $0.15/M tokens | $0.60/M tokens | $0.02–$0.10 |
+
+Smart routing saves ~70% by using Flash for greetings, questions, and simple lookups.
+
+Use `/cost` to see your spending mid-session.
+
+---
+
+## Troubleshooting
+
+| Problem | Fix |
+|---------|-----|
+| `ModuleNotFoundError: No module named 'acorn'` | Run `pip install -e .` from the acorn directory |
+| `404 NOT_FOUND` model error | Gemini 3.1 requires `location="global"` (already set). If using 2.5 models only, you can use `us-central1` |
+| `Permission denied` on gcloud | Run `gcloud auth application-default login` |
+| `Vertex AI API not enabled` | Run `gcloud services enable aiplatform.googleapis.com` |
+| Session won't resume | Delete `~/.acorn/sessions/` and restart |
+
+---
+
+## License
+
+MIT

acorn_agent-2.1.0/README.md

@@ -0,0 +1,315 @@
+# Acorn
+
+**An autonomous coding agent that lives in your terminal.**
+
+Acorn reads your code, writes files, runs commands, and refactors across your entire codebase — powered by Google's Gemini 3.1 Pro via Vertex AI.
+
+```
+     █████╗  ██████╗ ██████╗ ██████╗ ███╗   ██╗
+    ██╔══██╗██╔════╝██╔═══██╗██╔══██╗████╗  ██║
+    ███████║██║     ██║   ██║██████╔╝██╔██╗ ██║
+    ██╔══██║██║     ██║   ██║██╔══██╗██║╚██╗██║
+    ██║  ██║╚██████╗╚██████╔╝██║  ██║██║ ╚████║
+    ╚═╝  ╚═╝ ╚═════╝ ╚═════╝ ╚═╝  ╚═╝╚═╝  ╚═══╝
+```
+
+## Features
+
+- **Streaming responses** — see output as it's generated
+- **Smart model routing** — Flash for simple questions, Pro for complex tasks
+- **Surgical file editing** — modifies specific lines, not entire files
+- **Multi-file refactoring** — reads and edits across your whole codebase
+- **Image/screenshot analysis** — attach images for the model to analyze
+- **Auto-retry with error recovery** — adapts when things fail
+- **Session persistence** — resume conversations where you left off
+- **Undo support** — revert the last file change instantly
+- **Cost tracking** — see what you're spending per session
+- **Project config** — per-repo `.acorn.toml` for custom settings
+- **Permission system** — 3-tier safety (safe/ask/deny)
+- **Git-aware** — understands your branch, status, and project structure
+
+---
+
+## Quick Start
+
+```bash
+# Install from PyPI (easiest)
+pip install acorn-agent
+
+# Or install from GitHub
+pip install git+https://github.com/andamagodwin/acorn.git
+
+# Run it
+acorn
+```
+
+On first run it will ask for your GCP project ID. That's it.
+
+---
+
+## Installation (Full Guide)
+
+### Prerequisites
+
+| Requirement | Why |
+|-------------|-----|
+| Python 3.11+ | Runtime |
+| Google Cloud account | Vertex AI access |
+| `gcloud` CLI | Authentication |
+
+### Step 1: Clone and Install
+
+```bash
+git clone https://github.com/andamagodwin/acorn.git
+cd acorn
+pip install -e .
+```
+
+This installs `acorn` as a global command you can run from anywhere.
+
+### Step 2: Set Up Google Cloud
+
+You need a GCP project with Vertex AI API enabled and authentication configured.
+
+```bash
+# Install gcloud CLI if you don't have it
+# https://cloud.google.com/sdk/docs/install
+
+# Login to Google Cloud
+gcloud auth login
+gcloud auth application-default login
+
+# Set your project
+gcloud config set project YOUR_PROJECT_ID
+```
+
+### Step 3: Enable Vertex AI API
+
+```bash
+gcloud services enable aiplatform.googleapis.com
+```
+
+Or enable it in the console: https://console.cloud.google.com/apis/library/aiplatform.googleapis.com
+
+### Step 4: Configure Your Project ID
+
+Edit `acorn/config/settings.py` and set your project:
+
+```python
+project: str = "your-gcp-project-id"
+```
+
+Or use the CLI flag:
+
+```bash
+acorn --project your-gcp-project-id
+```
+
+Or use a `.acorn.toml` in your repo (see below).
+
+### Step 5: Run
+
+```bash
+cd ~/your-project
+acorn
+```
+
+---
+
+## Usage
+
+```bash
+# Start in current directory
+acorn
+
+# Use a specific model
+acorn --model gemini-2.5-flash
+
+# List available models
+acorn --models
+
+# Disable streaming
+acorn --no-stream
+
+# Disable smart routing (always use Pro)
+acorn --no-routing
+
+# Auto-approve all file writes (careful!)
+acorn --unsafe
+
+# Override GCP project
+acorn --project my-project-id
+
+# Help
+acorn --help
+```
+
+### Attach Images
+
+Just include an image path in your message:
+
+```
+> what's wrong in screenshot.png
+> implement the design in mockup.jpg
+```
+
+Gemini will analyze the image and respond accordingly.
+
+---
+
+## Commands
+
+| Command | What it does |
+|---------|--------------|
+| `/help` | Show all commands |
+| `/model <name>` | Switch model (or list available) |
+| `/cost` | Show session cost breakdown |
+| `/status` | Token usage, routing stats, cost |
+| `/plan` | Show current task execution plan |
+| `/undo` | Revert the last file change |
+| `/clear` | Reset context and session |
+| `/sessions` | List saved sessions |
+| `/routing on\|off` | Toggle smart routing |
+| `/exit` | Quit |
+
+---
+
+## Project Configuration
+
+Drop a `.acorn.toml` in any project root to customize Acorn's behavior for that repo:
+
+```toml
+[model]
+pro = "gemini-2.5-pro"
+flash = "gemini-2.5-flash"
+temperature = 0.2
+max_output_tokens = 65536
+
+[routing]
+enabled = true
+threshold = 200
+
+[project]
+gcp_project = "your-project-id"
+location = "us-central1"
+
+[permissions]
+safe_commands = [
+    "npm run", "npm test", "cargo build",
+    "python -m pytest", "make",
+]
+```
+
+Acorn auto-detects this file by walking up from your working directory.
+
+---
+
+## For Collaborators
+
+### Joining the Project
+
+1. Get added as a collaborator on the GitHub repo
+2. Clone and install:
+   ```bash
+   git clone https://github.com/andamagodwin/acorn.git
+   cd acorn
+   pip install -e .
+   ```
+3. Set up GCP authentication:
+   ```bash
+   gcloud auth login
+   gcloud auth application-default login
+   ```
+4. Ask the project owner to add you to the GCP project with the **"Vertex AI User"** role in IAM
+5. Run `acorn` from any directory
+
+### IAM Setup (For Project Owner)
+
+To add a collaborator to your GCP project:
+
+```bash
+gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
+  --member="user:their-email@gmail.com" \
+  --role="roles/aiplatform.user"
+```
+
+Or in the console: IAM & Admin > IAM > Grant Access > Role: "Vertex AI User"
+
+---
+
+## Architecture
+
+```
+acorn/
+├── config/
+│   ├── settings.py        — Models, permissions, safety rules
+│   └── project_config.py  — .acorn.toml loader
+├── core/
+│   ├── agent.py           — Main brain: streaming agentic loop
+│   ├── context.py         — Context window with auto-compaction
+│   ├── costs.py           — Token usage and cost tracking
+│   ├── planner.py         — Multi-step task planning
+│   ├── router.py          — Smart model routing (Flash vs Pro)
+│   └── session.py         — Session persistence to ~/.acorn/sessions/
+├── tools/
+│   ├── filesystem.py      — Read, write, edit, search, list
+│   ├── terminal.py        — Command execution with timeout
+│   └── git_tools.py       — Git-aware project understanding
+├── ui/
+│   └── terminal_ui.py     — Terminal UI with markdown rendering
+└── main.py                — CLI entry point
+```
+
+---
+
+## How It Works
+
+1. You type a message
+2. Acorn routes it to Flash (simple) or Pro (complex)
+3. The model calls tools — reads files, edits code, runs commands
+4. Tool results feed back for up to 25 iterations per turn
+5. If something fails, it sees the error and adapts
+6. Final response renders with markdown formatting
+
+---
+
+## Safety
+
+| Layer | What it does |
+|-------|--------------|
+| Blocked commands | `rm -rf /`, `mkfs`, fork bombs — permanently blocked |
+| Safe commands | `ls`, `git status`, `grep` — auto-execute |
+| Permission prompts | File writes, unknown commands — asks you first |
+| File backups | Every edit is backed up for `/undo` |
+| Context isolation | Won't touch `.env` files or expose secrets |
+
+---
+
+## Cost
+
+| Model | Input | Output | Typical session |
+|-------|-------|--------|-----------------|
+| Gemini 3.1 Pro | $1.25/M tokens | $10.00/M tokens | $0.50–$2.00 |
+| Gemini 2.5 Flash | $0.15/M tokens | $0.60/M tokens | $0.02–$0.10 |
+
+Smart routing saves ~70% by using Flash for greetings, questions, and simple lookups.
+
+Use `/cost` to see your spending mid-session.
+
+---
+
+## Troubleshooting
+
+| Problem | Fix |
+|---------|-----|
+| `ModuleNotFoundError: No module named 'acorn'` | Run `pip install -e .` from the acorn directory |
+| `404 NOT_FOUND` model error | Gemini 3.1 requires `location="global"` (already set). If using 2.5 models only, you can use `us-central1` |
+| `Permission denied` on gcloud | Run `gcloud auth application-default login` |
+| `Vertex AI API not enabled` | Run `gcloud services enable aiplatform.googleapis.com` |
+| Session won't resume | Delete `~/.acorn/sessions/` and restart |
+
+---
+
+## License
+
+MIT

acorn_agent-2.1.0/acorn/__init__.py

@@ -0,0 +1,2 @@
+"""Acorn — an autonomous coding agent powered by Vertex AI."""
+__version__ = "2.0.0"