alpiecode 9.0.1__tar.gz → 9.0.2__tar.gz

{alpiecode-9.0.1 → alpiecode-9.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: alpiecode
-Version: 9.0.1
+Version: 9.0.2
 Summary: AlpieCode — Autonomous AI Coding Agent CLI powered by local 169Pi GGUF VLM
 Requires-Python: >=3.9
 Requires-Dist: huggingface_hub>=0.20.0

alpiecode-9.0.2/README.md

@@ -0,0 +1,676 @@
+# ⚡ AlpieCode: Autonomous AI Software Engineering Agent & Full Developer Platform
+
+[![Python Version](https://img.shields.io/badge/python-3.9%20%7C%203.10%20%7C%203.11%20%7C%203.12-blue.svg)](https://www.python.org/)
+[![Version](https://img.shields.io/badge/alpiecode-v9.0.1-emerald.svg)](https://github.com/169Pi/codeagent-poc)
+[![VS Code Extension](https://img.shields.io/badge/vscode%20extension-v8.0.8-blueviolet.svg)](https://marketplace.visualstudio.com/)
+[![FastAPI](https://img.shields.io/badge/FastAPI-0.100%2B-009688.svg)](https://fastapi.tiangolo.com/)
+[![Jupyter & Colab](https://img.shields.io/badge/Jupyter%20%7C%20Colab-Ready-f37726.svg)](https://colab.research.google.com/)
+[![Platforms](https://img.shields.io/badge/platform-Linux%20%7C%20WSL2%20%7C%20macOS%20%7C%20Windows-lightgrey.svg)](https://github.com/169Pi/codeagent-poc)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+> **Powered by 169Pi Alpie Vision-Language-Action Models (Local GGUF & Remote Cloud API)**  
+> *An enterprise-grade, autonomous software engineering agent seamlessly integrated across the Command Line (CLI), VS Code Extension, FastAPI Backend Server, Python SDK, Jupyter Notebooks, and Google Colab.*
+
+---
+
+## 📑 Table of Contents
+1. [🌟 Overview & Capabilities](#-overview--capabilities)
+2. [🏗️ Core Architecture & Hybrid Dual-Engine](#️-core-architecture--hybrid-dual-engine)
+3. [📦 Complete Installation Guide](#-complete-installation-guide)
+4. [🚀 Backend API Server (`alpiecode serve`)](#-backend-api-server-alpiecode-serve)
+5. [⌨️ Command-Line Interface (CLI) Full Reference](#️-command-line-interface-cli-full-reference)
+6. [💻 VS Code Extension Deep-Dive](#-vs-code-extension-deep-dive)
+7. [🐍 Python SDK Reference (Programmatic Usage)](#-python-sdk-reference-programmatic-usage)
+8. [📓 Jupyter Notebooks, JupyterLab & Google Colab](#-jupyter-notebooks-jupyterlab--google-colab)
+9. [🛠️ 15 Built-In Autonomous Agent Tools](#️-15-built-in-autonomous-agent-tools)
+10. [🛡️ Safety Guardian, Git Checkpoints & Memory System](#️-safety-guardian-git-checkpoints--memory-system)
+11. [⚙️ Configuration & Environment Variables](#️-configuration--environment-variables)
+12. [❓ FAQ & Troubleshooting](#-faq--troubleshooting)
+
+---
+
+## 🌟 Overview & Capabilities
+
+**AlpieCode** is an autonomous software engineering assistant that acts as a principal developer in your repository. Rather than simply generating isolated snippets, AlpieCode operates as a full-loop agent:
+- **Discovers & Understands**: Recursively indexes codebases, reads files, and executes ripgrep regex searches.
+- **Reasons & Plans**: Formulates implementation plans, manages checkpointed deliverables, and explains complex architectures.
+- **Generates & Modifies**: Writes production code, applies surgical whitespace-accurate diff patches, and refactors existing components.
+- **Executes & Self-Heals**: Executes commands in an isolated sandbox, automatically captures build/test errors, and iterates until tests pass.
+- **Works Everywhere**: From the terminal and VS Code sidebar to automated Python scripts and interactive Google Colab notebooks.
+
+### 🎯 Feature Matrix Across Interfaces
+| Feature / Capability | CLI | VS Code Extension | Python SDK | Jupyter & Colab |
+| :--- | :---: | :---: | :---: | :---: |
+| **Autonomous Coding Loops (`run`)** | ✅ | ✅ | ✅ | ✅ |
+| **Multi-Turn Interactive Chat** | ✅ | ✅ | ✅ | ✅ |
+| **Architectural Planning (`plan`)** | ✅ | ✅ | ✅ | ✅ |
+| **Deep Code Explanation (`explain`)** | ✅ | ✅ | ✅ | ✅ |
+| **Interactive Diff / Plan-First Review** | — | ✅ (Accept/Reject/Edit) | — | — |
+| **Inline Ghost-Text Code Autocomplete** | — | ✅ (Tab to accept) | — | — |
+| **Live Token Speed & Counter Meter** | — | ✅ | — | ✅ |
+| **Multimodal Vision (Images/Screenshots)** | ✅ (`--image`) | ✅ (Paste / Upload) | ✅ | ✅ |
+| **Video & YouTube URL Analysis** | ✅ (`--video`, `--url`) | — | ✅ | — |
+| **Autonomous GitHub Repo Analysis** | ✅ (`--github`) | ✅ | ✅ | — |
+| **Proactive `.venv` & Dependency Setup** | ✅ | ✅ | ✅ | ✅ |
+| **Persistent Project Memory** | ✅ | ✅ | ✅ | ✅ |
+| **Zero-Crash Smart GGUF Fallback** | ✅ | ✅ | ✅ | ✅ |
+
+---
+
+## 🏗️ Core Architecture & Hybrid Dual-Engine
+
+AlpieCode employs an intelligent **Hybrid Dual-Engine** routing system that pairs the speed and depth of cloud Vision-Language-Action models with the resilience of completely offline local GGUF models.
+
+```
+┌────────────────────────────────────────────────────────────────────────────────────────┐
+│                                     CLIENT LAYER                                       │
+│   VS Code Extension        Terminal CLI          Python SDK       Jupyter / Colab      │
+│   (Sidebar & Ghost-Text)  (alpiecode run/chat)  (import alpiecode)   (%alpie / %%alpie)│
+└──────────────────────────┬───────────────────────┬──────────────────────┬──────────────┘
+                           │                       │                      │
+                           ▼                       ▼                      ▼
+┌────────────────────────────────────────────────────────────────────────────────────────┐
+│                        FASTAPI BACKEND SERVER (`alpiecode serve`)                      │
+│   • POST /chat (SSE Stream)   • POST /completion (Inline Ghost)   • GET /sessions      │
+│   • POST /cancel/{id}         • GET /health                       • GET /metrics       │
+└──────────────────────────────────────────┬─────────────────────────────────────────────┘
+                                           │
+                                           ▼
+┌────────────────────────────────────────────────────────────────────────────────────────┐
+│                                  AGENT ORCHESTRATOR                                    │
+│   • 5-Layer Context Assembly (System + Summary + Anchors + Turns + Request)            │
+│   • Rolling Compaction with Lazy-Cached Summaries                                      │
+│   • Session State Isolation & Reentrancy Guards                                        │
+│   • Persistent Cross-Session Memory (~/.alpiecode/memories/)                           │
+└──────────────────────────────────────────┬─────────────────────────────────────────────┘
+                                           │
+                                           ▼
+┌────────────────────────────────────────────────────────────────────────────────────────┐
+│                               HYBRID DUAL-ENGINE ROUTER                                │
+│                                                                                        │
+│                   ┌──────────────────────────────────────────────┐                     │
+│                   │        Active Internet Connectivity?         │                     │
+│                   └──────────────┬────────────────┬──────────────┘                     │
+│                                  │                │                                    │
+│                            YES (Online)       NO (Offline)                             │
+│                                  │                │                                    │
+│                                  ▼                ▼                                    │
+│                   ┌────────────────────────┐   ┌────────────────────────┐              │
+│                   │      OpenAIBackend     │   │      LocalBackend      │              │
+│                   │ (Remote 169Pi Cloud VLM│   │  (Local GGUF Engine)   │              │
+│                   │   High-Throughput API) │   │  (Zero Internet Req.)  │              │
+│                   └────────────────────────┘   └────────────────────────┘              │
+└──────────────────────────────────────────┬─────────────────────────────────────────────┘
+                                           │
+                                           ▼
+┌────────────────────────────────────────────────────────────────────────────────────────┐
+│                             15 AUTONOMOUS AGENT TOOLS                                  │
+│   write_file  •  edit_file  •  read_file  •  apply_patch  •  bash  •  list_files       │
+│   file_search •  view_image •  fetch_url  •  web_search   •  clone_repo • update_plan  │
+│   extract_memories • compact_context • diagnostics                                     │
+│                                          │                                             │
+│                                          ▼                                             │
+│                           SAFETY GUARDIAN & SANDBOX GATE                               │
+│              (Blocks destructive commands, enforces paths, sandbox execution)          │
+└────────────────────────────────────────────────────────────────────────────────────────┘
+```
+
+### ⚡ Smart Fallback Resilience
+- **Network-Aware Routing**: Local GGUF fallback triggers **only when internet is genuinely unavailable**, preventing unnecessary model loading on brief cloud API delays or transient server timeouts (which are retried automatically).
+- **Sanitized Chat Templates**: Converts complex multi-turn OpenAI tool schemas and system structures into sanitized templates compatible with local Jinja2 GGUF renderers.
+- **Zero Crashes**: If network drops mid-session, the agent gracefully recovers or provides clear diagnostic feedback.
+
+---
+
+## 📦 Complete Installation Guide
+
+### 1. Prerequisites
+- **Python**: `>= 3.9` (Recommended: Python 3.10, 3.11, or 3.12)
+- **Platforms**:
+  - **Linux**: Ubuntu 20.04+, Debian 11+, Fedora, Arch Linux
+  - **Windows**: Native Windows 10/11 or Windows Subsystem for Linux (WSL2 / Ubuntu)
+  - **macOS**: Apple Silicon (M1/M2/M3/M4) & Intel
+- **Dev Tools (Recommended)**: `git`, `curl`, `ripgrep` (optional, falls back automatically)
+
+---
+
+### 2. Python Package Installation
+
+#### Option A: Quick Install via pip (Any Virtual Environment)
+Activate any virtual environment of your choice (`venv`, `conda`, `uv`, `virtualenv`, `poetry`) and install directly:
+```bash
+# 1. Activate your preferred virtual environment (e.g. venv)
+python3 -m venv myenv
+source myenv/bin/activate       # On Windows: myenv\Scripts\activate
+
+# Or using Conda:
+# conda create -n alpie python=3.11 -y && conda activate alpie
+
+# 2. Install AlpieCode
+pip install alpiecode
+```
+
+#### Option B: From Source / Editable Mode (Recommended for Developers)
+```bash
+# Clone the repository
+git clone https://github.com/169Pi/codeagent-poc.git
+cd codeagent-poc
+
+# Create and activate a virtual environment
+python3 -m venv .venv
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+
+# Install in editable mode with all dependencies
+pip install -e .
+```
+
+#### Option C: From Wheel (.whl)
+```bash
+# Build the distribution
+python3 -m pip install --upgrade build
+python3 -m build
+
+# Install the wheel
+pip install dist/alpiecode-9.0.1-py3-none-any.whl
+```
+
+#### Verify CLI Installation:
+```bash
+alpiecode version
+# Output: alpiecode 9.0.1
+
+alpiecode doctor
+```
+
+---
+
+### 3. VS Code Extension Installation
+
+The VS Code extension provides the AI sidebar, plan-first review, and inline ghost-text completions.
+
+#### Automatic Installation (Zero Configuration)
+Simply launch the AlpieCode backend server from your terminal:
+```bash
+alpiecode serve
+```
+If the VS Code extension is not already installed, AlpieCode **automatically packages and installs the `.vsix` into VS Code**!
+
+#### Manual Installation via CLI:
+```bash
+# Using the pre-built VSIX file
+code --install-extension vscode/alpiecode-8.0.8.vsix
+```
+
+#### Manual Packaging (For Extension Developers):
+```bash
+cd vscode
+npm install
+npm run compile
+npx @vscode/vsce package
+code --install-extension alpiecode-8.0.8.vsix
+```
+
+---
+
+## 🚀 Backend API Server (`alpiecode serve`)
+
+The AlpieCode FastAPI server runs as a high-concurrency daemon connecting local development environments, VS Code sidebars, remote IDEs, and external scripts to the autonomous agent engine.
+
+### Launching the Server
+```bash
+# Default: binds to 127.0.0.1 on port 7169
+alpiecode serve
+
+# Custom Host and Port:
+alpiecode serve --host 0.0.0.0 --port 8080
+```
+
+```text
+    _    _     _      ____            _      
+   / \  | |_ _| | ___ / ___|___   __| | ___ 
+  / _ \ | | '_ \ |/ _ \ |   / _ \ / _` |/ _ \
+ / ___ \| | |_) | |  __/ |__| (_) | (_| |  __/
+/_/   \_\_|_.__/|_|\___|\____\___/ \__,_|\___|
+
+✅ AlpieCode VS Code extension is installed.
+🚀 Starting AlpieCode Server on http://127.0.0.1:7169
+INFO:     Uvicorn running on http://127.0.0.1:7169 (Press CTRL+C to quit)
+```
+
+### REST & SSE API Endpoints Reference
+
+| Method | Endpoint | Description | Payload / Parameters |
+| :--- | :--- | :--- | :--- |
+| `POST` | `/chat` | Executes an agent task, streaming events in real time via **Server-Sent Events (SSE)**. | `{"task": str, "workdir": str, "session_id": Optional[str], "image": Optional[str], "reasoning_level": "thinking"\|"high"\|"low"}` |
+| `POST` | `/completion` | Provides ultra-low-latency inline code completions (ghost text) ahead of cursor. | `{"prompt": str, "suffix": str, "language": str, "max_tokens": int}` |
+| `GET` | `/health` | Health diagnostic check reporting server uptime, backend availability, and cache stats. | *None* |
+| `GET` | `/sessions` | Lists active multi-turn sessions with token counts and workspace paths. | *None* |
+| `DELETE`| `/sessions/{session_id}` | Deletes a session container and cleans up associated resources. | `session_id` in path |
+| `POST` | `/cancel/{session_id}` | Gracefully cancels an in-progress agent task. | `session_id` in path |
+| `GET` | `/metrics` | Returns token usage, speeds, and agent execution performance statistics. | *None* |
+
+---
+
+## ⌨️ Command-Line Interface (CLI) Full Reference
+
+The `alpiecode` CLI provides a developer-friendly command suite:
+
+```text
+usage: alpiecode [-h] [-v] [--workdir WORKDIR] [--image IMAGE] [--video VIDEO]
+                 [--url URL] [--github GITHUB] [--max-turns MAX_TURNS]
+                 [--thinking] [--no-thinking] [--no-update] [--quiet] [--debug]
+                 {version,init,serve,run,chat,plan,diff,undo,doctor,explain} ...
+```
+
+---
+
+### 1. `alpiecode run "<task>"`
+Executes an end-to-end autonomous software engineering task:
+```bash
+# Standard task in the current directory:
+alpiecode run "Create a FastAPI app with SQLite auth and JWT tokens"
+
+# Specify a target project directory:
+alpiecode run "Fix all failing pytest tests" --workdir /path/to/project
+
+# Multimodal image analysis (mockup to code, UI bug fix):
+alpiecode run "Implement this dashboard layout in React and Tailwind" --image ./mockup.png
+
+# Video walkthrough or screen recording analysis:
+alpiecode run "Reproduce and fix the UI crash shown in this screen recording" --video ./bug_repro.mp4
+
+# Analyze a YouTube tutorial or demonstration URL:
+alpiecode run "Implement the architecture explained in this video" --url "https://youtube.com/watch?v=xyz"
+
+# Analyze and clone an open-source GitHub repository:
+alpiecode run "Analyze the plugin architecture of this repo and summarize it" --github "psf/requests"
+
+# Force deep reasoning mode or fast execution mode:
+alpiecode run "Audit the cryptographic security of auth.py" --thinking
+alpiecode run "Add docstrings to all functions in utils.py" --no-thinking
+
+# Show full agent discovery intelligence and tool arguments:
+alpiecode run "Refactor database migrations" --debug
+```
+
+---
+
+### 2. `alpiecode chat`
+Starts a persistent, interactive terminal REPL with multi-turn memory:
+```bash
+alpiecode chat
+```
+*Features:*
+- Retains context, variable names, and architectural decisions across turns.
+- Rolling compaction prevents context window overflow.
+- Checkpoints git state after each turn for easy rollback.
+- Exit anytime by typing `exit`, `quit`, or pressing `Ctrl+C`.
+
+---
+
+### 3. `alpiecode plan "<task>"`
+Generates an actionable architectural plan **without making file modifications**:
+```bash
+alpiecode plan "Migrate the frontend from JavaScript to TypeScript"
+```
+*Process:*
+1. Explores existing files and types (`list_files`, `file_search`, `read_file`).
+2. Synthesizes a structured checklist plan with milestones.
+3. Outputs clear implementation steps and risk assessments.
+
+---
+
+### 4. `alpiecode explain "<target>"`
+Deep-dives into a local file, function, or technical concept:
+```bash
+# Explain a local file:
+alpiecode explain src/codeagent/orchestrator.py
+
+# Explain a technical concept or codebase component:
+alpiecode explain "How does the rolling context compaction work in AlpieCode?"
+```
+
+---
+
+### 5. `alpiecode diff`
+Inspects all file changes and diffs made by AlpieCode since the last git checkpoint:
+```bash
+alpiecode diff
+```
+
+---
+
+### 6. `alpiecode undo`
+Instantly rolls back all file edits made during the last AlpieCode session:
+```bash
+alpiecode undo
+```
+
+---
+
+### 7. `alpiecode doctor`
+Runs an instant system and environment diagnostic suite:
+```bash
+alpiecode doctor
+```
+*Health Checks:*
+- **Python Runtime**: Python version and active virtual environment status.
+- **Hardware Acceleration**: CUDA availability, GPU device name, and VRAM.
+- **Network & Latency**: DNS resolution, ping latency (ms), and remote API reachability.
+- **Compilers & Dev Tools**: Presence of `gcc`, `g++`, `git`, `node`, `java`, etc.
+- **VS Code Extension**: Installation verification and version check.
+
+---
+
+### 8. `alpiecode init`
+Interactive CLI wizard to configure endpoints, API keys, models, and defaults:
+```bash
+alpiecode init
+```
+
+---
+
+## 💻 VS Code Extension Deep-Dive
+
+The AlpieCode VS Code extension integrates directly into your daily IDE workflow.
+
+```
+┌────────────────────────────────────────────────────────┐
+│  ALPIECODE CHAT                       ⚡ 48 tok/s · 1.4k│
+├────────────────────────────────────────────────────────┤
+│ 🤖 Mode: [Online Cloud VLM]    Reasoning: [High (Thinking)▼]
+│                                                        │
+│ 👤 Create a login endpoint with rate limiting.         │
+│                                                        │
+│ 🤖 ── Proposed Changes: auth.py ─────────────────────  │
+│ ┌────────────────────────────────────────────────────┐ │
+│ │ 📋 Change Plan Card                                │ │
+│ │ - from flask import Flask                          │ │
+│ │ + from flask import Flask, request, jsonify        │ │
+│ │ + from flask_limiter import Limiter                │ │
+│ │                                                    │ │
+│ │ [✅ Accept]      [❌ Reject]      [✏️ Edit Request]  │ │
+│ └────────────────────────────────────────────────────┘ │
+│                                                        │
+│ 📦 'flask_limiter' required but not installed.         │
+│ [Create .venv & Install]   [Install Globally]  [Skip]  │
+├────────────────────────────────────────────────────────┤
+│ > Type /plan, /explain, /doctor, or ask a question...  │
+│ [📎 Image] [📋 Plan-First: ON]             [Send ❯]    │
+└────────────────────────────────────────────────────────┘
+```
+
+### 1. 📋 Plan-First Review & Change Approval Workflow
+- When modifying existing files, AlpieCode presents an interactive **Change Plan Card** with side-by-side / unified diffs (`-` red / `+` green).
+- **`✅ Accept`**: Commits the change, opens the file in your active editor, and runs verification.
+- **`❌ Reject`**: Discards the modification cleanly.
+- **`✏️ Edit Request`**: Opens an inline input box to provide steering instructions (e.g. *"Use Redis backend for rate limiting"*).
+
+---
+
+### 2. 🗂️ Persistent Multi-Turn Conversation History
+- **Active Thread Context**: Each chat conversation maintains a persistent `sessionId`. The model retains all prior turns, files discussed, and tool results.
+- **History Drawer**: Click the **History** button (`🕒`) in the sidebar header to view, reload, or delete up to **50 past conversations** saved in VS Code global storage.
+
+---
+
+### 3. 🧠 Reasoning Level Selector
+Toggle model behavior directly in the sidebar dropdown:
+- 🧠 **High (Thinking)**: Maximal chain-of-thought reasoning, multi-step problem solving, and complex architectural design.
+- ⚡ **Low (Fast)**: Direct code generation with zero reasoning overhead for quick one-liners and docstring edits.
+
+---
+
+### 4. ⚡ Slash Commands (`/`)
+Type **`/`** in the chat input to invoke quick commands:
+- `📋 /plan <task>` — Creates a structured architectural plan without modifying code.
+- `💡 /explain <file>` — Explains code, architecture, or algorithms step-by-step.
+- `🩺 /doctor` — Executes full system diagnostic checks in the chat window.
+
+---
+
+### 5. 🖱️ Right-Click Context Menu Actions
+Highlight any code in your editor, right-click, and choose:
+- **Fix This Error**: Automatically aggregates language diagnostics (errors, warnings) and selected code to generate an instant fix.
+- **Generate Tests**: Writes unit tests (pytest, jest, etc.) for the selected function or class.
+- **Explain Code**: Explains the selected snippet line-by-line.
+- **Refactor / Optimize**: Cleans, modernizes, and improves the performance of the highlighted block.
+- **Ask About Selection**: Prompts for a custom question regarding the highlighted code.
+
+---
+
+### 6. 👻 Inline Ghost-Text Code Autocomplete
+As you write code in any file, AlpieCode streams inline suggestions ahead of your cursor:
+- Non-intrusive gray ghost-text suggestions.
+- Press **`Tab`** to accept the suggestion, or keep typing to ignore.
+- Intelligent debounce and circuit breakers ensure zero editor lag.
+
+---
+
+### 7. 🐍 Proactive Virtual Environment (`.venv`) Auto-Prompt
+When generated code requires external libraries (`numpy`, `pandas`, `fastapi`, etc.):
+- AlpieCode scans the AST imports before execution.
+- If packages are missing, an interactive prompt appears:
+  ```text
+  📦 'fastapi' is required but not installed in your active environment.
+  🐍 No virtual environment detected. Create one?
+
+  [Create .venv & Install]   [Install Globally]   [Skip]
+  ```
+- Choosing **Create .venv & Install** automatically spins up `.venv`, installs the packages, and runs the script using `.venv/bin/python3`.
+
+---
+
+### 8. 📊 Live Token & Speed Meter
+Displays real-time performance indicators in the sidebar header:
+`🟢 Online API` ── `⚡ 46 tok/s · 📊 1,820 tokens`
+
+---
+
+### 9. 📎 Multimodal Image Attachment
+- Drag-and-drop UI screenshots directly into the chat.
+- Paste images directly from your clipboard (**`Ctrl+V`** / **`Cmd+V`**).
+- Click **`📎 Image`** to browse and attach mockups, architecture diagrams, or error screenshots.
+
+---
+
+### 10. ⚙️ Extension Settings (`settings.json`)
+Configure AlpieCode in your VS Code settings:
+```json
+{
+  "alpiecode.serverUrl": "http://127.0.0.1:7169",
+  "alpiecode.showReasoning": true,
+  "alpiecode.enableAutocomplete": true,
+  "alpiecode.autoRunCode": true,
+  "alpiecode.autoFixErrors": true,
+  "alpiecode.planFirstReview": true,
+  "alpiecode.githubUsername": "my-github-handle",
+  "alpiecode.confirmGitPush": true
+}
+```
+
+---
+
+## 🐍 Python SDK Reference (Programmatic Usage)
+
+Automate engineering workflows directly in Python scripts and CI/CD pipelines:
+
+```python
+import alpiecode
+
+# 1. Execute an autonomous engineering task
+alpiecode.run(
+    task="Build a benchmark script comparing Polars vs Pandas on 10M rows",
+    workdir="./benchmarks",
+    reasoning_level="thinking"  # "thinking" | "high" | "low"
+)
+
+# 2. Generate an implementation plan
+alpiecode.plan(
+    task="Refactor authentication layer to use OAuth2 and JWT tokens",
+    workdir="."
+)
+
+# 3. Explain a file or architecture
+alpiecode.explain(
+    target="src/codeagent/orchestrator.py",
+    workdir="."
+)
+
+# 4. Run system health diagnostics
+status_code = alpiecode.doctor()
+```
+
+---
+
+## 📓 Jupyter Notebooks, JupyterLab & Google Colab
+
+AlpieCode delivers a first-class developer experience inside Jupyter Notebooks and Google Colab with reactive UI cards and live status badges.
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ 🤖 AlpieCode Agent  [RUNNING]                              │
+│ Task: Train an XGBoost model on iris dataset                │
+│                                                             │
+│ ✓ $ python -m pip install xgboost scikit-learn              │
+│ ✓ write_file train.py                                       │
+│ ✓ $ python train.py                                         │
+│                                                             │
+│ ✨ Code block automatically populated in next cell.        │
+│ Hit Shift+Enter to run.                                     │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### 1. Setup in Colab or Jupyter
+In any notebook cell:
+```python
+# Install AlpieCode (in Colab)
+!pip install alpiecode
+
+# Load the IPython magic extension
+%load_ext alpiecode
+```
+
+---
+
+### 2. Magic Commands
+
+#### Single-Line Magic (`%alpie`)
+```python
+%alpie Create a function to calculate Fibonacci numbers using memoization
+```
+
+#### Multi-Line Cell Magic (`%%alpie`)
+```python
+%%alpie
+Create an end-to-end data pipeline script data_pipeline.py:
+1. Load dataset from https://raw.githubusercontent.com/mwaskom/seaborn-data/master/iris.csv
+2. Preprocess features with StandardScaler
+3. Train an XGBoost classifier with 5-fold cross validation
+4. Print the mean accuracy and confusion matrix
+```
+
+#### Auto-Insert Code into Next Cell (`--insert` / `--code`)
+Use `--insert` to have AlpieCode **automatically populate the generated code into the very next notebook cell**, ready for you to press **`Shift+Enter`**:
+```python
+%alpie --insert Build a PyTorch neural network for MNIST digit classification
+```
+
+#### Specialized Notebook Magics:
+```python
+# Plan without modifying files
+%alpie_plan Build a custom PyTorch dataset loader for audio spectrograms
+
+# Explain code or notebook variables
+%alpie_explain model.py
+
+# System diagnostic check
+%alpie_doctor
+
+# Reset conversation context between notebook sections
+%alpie_reset
+```
+
+---
+
+## 🛠️ 15 Built-In Autonomous Agent Tools
+
+The AlpieCode orchestrator autonomously selects and coordinates 15 specialized tools:
+
+| # | Tool Name | Category | Description | Key Inputs |
+| :-: | :--- | :--- | :--- | :--- |
+| **1** | `write_file` | File System | Creates new files or completely overwrites existing files safely. | `path`, `content` |
+| **2** | `edit_file` | File System | Replaces specific text blocks with surgical whitespace matching. | `path`, `old_str`, `new_str` |
+| **3** | `read_file` | File System | Reads entire files or specific line ranges (`start_line`, `end_line`). | `path`, `start_line`, `end_line` |
+| **4** | `apply_patch` | File System | Applies standard unified diff format patches. | `patch` |
+| **5** | `bash` | Execution | Runs shell commands inside an isolated sandbox with safety gates. | `command`, `timeout` |
+| **6** | `list_files` | Discovery | Recursively lists repository files with pattern matching & pruning. | `path`, `pattern`, `max_depth` |
+| **7** | `file_search` | Discovery | High-speed ripgrep regex search across codebase contents. | `query`, `path`, `include` |
+| **8** | `view_image` | Vision | Inspects and analyzes images, UI mockups, and screenshots. | `path` |
+| **9** | `fetch_url` | Research | Fetches and extracts clean documentation and web pages. | `url` |
+| **10**| `web_search` | Research | Queries DuckDuckGo for live API documentation and references. | `query`, `max_results` |
+| **11**| `clone_repo` | Repository | Clones open-source repositories for local reference. | `repo_url`, `destination` |
+| **12**| `update_plan` | Planning | Updates structured milestone checklists (`[x]` / `[ ]`). | `plan` |
+| **13**| `extract_memories`| Memory | Extracts and persists project patterns and build commands. | `memories` |
+| **14**| `compact_context` | Optimization| Compresses conversation history to prevent context overflow. | `summary` |
+| **15**| `diagnostics` | Intelligence | Queries compiler and linter diagnostics for active files. | `path` |
+
+---
+
+## 🛡️ Safety Guardian, Git Checkpoints & Memory System
+
+### 1. Safety Guardian Gate (`src/codeagent/guardian.py`)
+- **Destructive Command Blocking**: Intercepts and blocks commands like `rm -rf /`, `mkfs`, raw disk partitioning, fork bombs, and system-level modifications.
+- **Sandbox Boundary Enforcement**: Prohibits writes outside the active project root directory (`workdir`).
+- **Rate-Limited Auto-Fix Loops**: Automatically stops recursive error-fixing loops after **3 attempts** to prevent token waste and infinite loops.
+
+### 2. Git Checkpointing & Undo (`src/codeagent/git_ops.py`)
+- **Automatic Checkpoints**: AlpieCode automatically creates temporary git checkpoints before executing tasks and after each multi-turn step.
+- **One-Click Rollback**: Run `alpiecode undo` or reject a proposed plan in VS Code to restore your workspace to its exact prior state.
+
+### 3. Persistent Cross-Session Memory (`src/codeagent/memory.py`)
+- Automatically captures project architecture patterns, build scripts, test conventions, and known quirks.
+- Persisted locally in `~/.alpiecode/memories/` and injected into future sessions so the agent never asks the same question twice.
+
+### 4. Cross-Platform WSL2 Path Normalization
+- Automatically translates Windows UNC paths (`\\wsl.localhost\...` and `\\wsl$\...`) to native Linux paths (`/home/...`) and routes commands through `wsl -d Ubuntu -- bash -c "..."` seamlessly.
+
+---
+
+## ⚙️ Configuration & Environment Variables
+
+Configure AlpieCode globally via `alpiecode init` or by exporting environment variables:
+
+| Environment Variable | Default Value | Description |
+| :--- | :--- | :--- |
+| `OPENAI_API_BASE` | `https://test.169pi.ai/v1` | URL for the high-throughput 169Pi cloud VLM endpoint. |
+| `OPENAI_API_KEY` | `EMPTY` | API authentication key (if required). |
+| `ALPIECODE_MODEL` | `alpie_9b` | Target model name. |
+| `ALPIECODE_SERVER_URL` | `http://127.0.0.1:7169` | Default URL for backend API server. |
+| `ALPIECODE_N_CTX` | `262144` (Online) / `32768` (Offline) | Maximum context window size in tokens. |
+| `ALPIECODE_TEMPERATURE` | `0.6` (Thinking) / `0.0` (Fast) | Model sampling temperature. |
+
+---
+
+## ❓ FAQ & Troubleshooting
+
+#### Q: How does the agent decide when to use Local GGUF vs. the Online API?
+> **A:** AlpieCode always prioritizes the high-throughput **Online Cloud API**. It only switches to the **Local GGUF Engine** if an internet check confirms the system is genuinely offline. Transient server delays or timeouts retry automatically rather than falling back.
+
+#### Q: How do I reload the VS Code extension after updating the backend?
+> **A:** In VS Code, press **`Ctrl+Shift+P`** (or **`Cmd+Shift+P`** on macOS) and select **`Developer: Reload Window`**.
+
+#### Q: Port 7169 is already in use. How do I change the port?
+> **A:** Start the server with a custom port:
+> ```bash
+> alpiecode serve --port 8080
+> ```
+> Then update the `alpiecode.serverUrl` setting in VS Code:
+> ```json
+> "alpiecode.serverUrl": "http://127.0.0.1:8080"
+> ```
+
+#### Q: Can I run AlpieCode completely offline on an airplane or air-gapped machine?
+> **A:** Yes! AlpieCode includes full offline GGUF local model execution. Simply run any CLI command (`alpiecode run "..."`) or start the local server, and it will execute locally using CPU or CUDA hardware acceleration with zero internet access required.
+
+---

{alpiecode-9.0.1 → alpiecode-9.0.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "alpiecode"
-version = "9.0.1"
+version = "9.0.2"
 description = "AlpieCode — Autonomous AI Coding Agent CLI powered by local 169Pi GGUF VLM"
 requires-python = ">=3.9"
 dependencies = [

{alpiecode-9.0.1 → alpiecode-9.0.2}/src/alpiecode.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: alpiecode
-Version: 9.0.1
+Version: 9.0.2
 Summary: AlpieCode — Autonomous AI Coding Agent CLI powered by local 169Pi GGUF VLM
 Requires-Python: >=3.9
 Requires-Dist: huggingface_hub>=0.20.0

{alpiecode-9.0.1 → alpiecode-9.0.2}/src/codeagent/__init__.py

@@ -16,7 +16,7 @@ Supports:
 from pathlib import Path
 from typing import Optional, Any, Dict
 
-__version__ = "9.0.1"
+__version__ = "9.0.2"
 
 def run(task: str, workdir: str = ".", reasoning_level: str = "thinking", **kwargs):
     """Run an autonomous coding task programmatically."""

{alpiecode-9.0.1 → alpiecode-9.0.2}/src/codeagent/backends/openai_backend.py

@@ -133,21 +133,40 @@ class OpenAIBackend:
         return self._client
 
     def _get_available_model(self, client: OpenAI) -> str:
-        """Auto-discover the served model name from /v1/models."""
+        """Auto-discover the served model name from /v1/models.
+
+        Uses a dedicated short-timeout (3s) probe to avoid blocking the agent
+        for minutes when the /v1/models endpoint is slow or unavailable.
+        Falls back instantly to the configured model name on any failure.
+        """
         if self._resolved_model:
             return self._resolved_model
         try:
-            models_list = client.models.list()
+            import httpx
+            # Use a dedicated short-timeout client for model discovery only.
+            # The shared HTTP client has a 120s read timeout which causes
+            # multi-minute hangs when /v1/models is slow or unresponsive.
+            probe_client = OpenAI(
+                base_url=self._cfg.base_url,
+                api_key=self._cfg.api_key or "not-needed",
+                http_client=httpx.Client(timeout=httpx.Timeout(3.0, connect=2.0)),
+            )
+            models_list = probe_client.models.list()
             if models_list.data:
                 for m in models_list.data:
                     if m.id == self._cfg.model or getattr(m, "root", None) == self._cfg.model:
                         self._resolved_model = m.id
+                        logger.info("Resolved model: %s", self._resolved_model)
                         return self._resolved_model
                 self._resolved_model = models_list.data[0].id
+                logger.info("Using first available model: %s", self._resolved_model)
                 return self._resolved_model
-        except Exception:
-            pass
-        return self._cfg.model
+        except Exception as e:
+            logger.debug("Model discovery failed (%.1fs timeout), using configured model '%s': %s",
+                         3.0, self._cfg.model, e)
+        # Fast fallback: use the configured model name directly
+        self._resolved_model = self._cfg.model
+        return self._resolved_model
 
     def chat_completion_stream(
         self,

alpiecode-9.0.1/README.md

@@ -1,342 +0,0 @@
-# ⚡ AlpieCode: The Autonomous AI Coding Agent & Full Developer Platform
-> **Powered by 169Pi Alpie Vision-Language-Action Models (Local GGUF & Remote Cloud API)**  
-> *Seamlessly integrated across VS Code, Command Line (CLI), Python SDK, Jupyter Notebooks, and Google Colab.*
-
----
-
-## 📑 Table of Contents
-1. [🌟 Executive Overview](#-executive-overview)
-2. [🏗️ Core Architecture & Hybrid Dual-Engine](#️-core-architecture--hybrid-dual-engine)
-3. [📦 Installation & Getting Started](#-installation--getting-started)
-4. [💻 VS Code Extension Deep-Dive](#-vs-code-extension-deep-dive)
-5. [⌨️ Command-Line Interface (CLI) Guide](#️-command-line-interface-cli-guide)
-6. [📓 Jupyter Notebooks, JupyterLab & Google Colab](#-jupyter-notebooks-jupyterlab--google-colab)
-7. [🛠️ 15 Built-In Agentic Tools](#️-15-built-in-agentic-tools)
-8. [🛡️ Safety Guardian, Virtual Environment & Guardrails](#️-safety-guardian-virtual-environment--guardrails)
-9. [❓ FAQ & Troubleshooting](#-faq--troubleshooting)
-
----
-
-## 🌟 Executive Overview
-
-**AlpieCode** is a full-stack, state-of-the-art autonomous software engineering agent designed to reason, plan, write, test, debug, and explain code across multiple environments.
-
-### 🎯 Key Capabilities at a Glance
-| Environment | Key Features |
-| :--- | :--- |
-| **VS Code Extension** | Plan-First Review Cards, Slash Commands (`/`), Reasoning Selector (`High/Med/Low`), Proactive `.venv` Auto-Prompt, Live Token/Speed Meter, Multimodal Screenshot Attachment, Inline Ghost Text (`Tab` to complete), Sandbox Output Cards |
-| **Terminal CLI** | `alpiecode serve`, `alpiecode run`, `alpiecode chat`, `alpiecode plan`, `alpiecode explain`, `alpiecode doctor`, `alpiecode diff`, `alpiecode init` |
-| **Notebooks & Colab** | `%load_ext alpiecode`, `%alpie <task>`, `%%alpie <multiline>`, `%alpie_plan`, `%alpie_explain`, `%alpie_doctor` |
-| **Python SDK** | `import alpiecode; alpiecode.run("...")`, `alpiecode.plan()`, `alpiecode.explain()`, `alpiecode.doctor()` |
-
----
-
-## 🏗️ Core Architecture & Hybrid Dual-Engine
-
-AlpieCode features an intelligent **Hybrid Dual-Engine** routing architecture:
-
-```
-                          ┌───────────────────────────┐
-                          │    User Prompt / Task     │
-                          └─────────────┬─────────────┘
-                                        │
-                                        ▼
-                          ┌───────────────────────────┐
-                          │ Server Reachability Ping  │
-                          └──────┬─────────────┬──────┘
-                                 │             │
-                    Online (Port 8000 Up)   Offline (No Connection)
-                                 │             │
-                                 ▼             ▼
-                    ┌─────────────────┐   ┌──────────────────────┐
-                    │ OpenAIBackend   │   │ LocalBackend         │
-                    │ (Azure VLM API) │   │ (Local GGUF Engine)  │
-                    │ 169Pi Remote    │   │ 169Pi Offline Model  │
-                    └────────┬────────┘   └──────────┬───────────┘
-                             │                       │
-                             └───────────┬───────────┘
-                                         ▼
-                             ┌───────────────────────┐
-                             │  Agent Orchestrator   │
-                             │  • Context Compaction │
-                             │  • Tool Executor      │
-                             │  • Memory Extraction  │
-                             └───────────┬───────────┘
-                                         ▼
-                       SSE Stream Events / Terminal Output
-```
-
-1. **Online Cloud VLM API** (`OpenAIBackend`): When connected to the network, queries the high-throughput 169Pi model hosted on cloud infrastructure.
-2. **Local GGUF Offline Engine** (`LocalBackend`): If internet is lost or the remote server is offline, AlpieCode **automatically falls back to local GGUF weights** (`169Pi/Alpie_learn_prototype_GGUF_NEW`) using CPU/GPU CUDA acceleration — zero crashes.
-
----
-
-## 📦 Installation & Getting Started
-
-### 1. Requirements
-- **Python**: `>= 3.9` (Recommended: Python 3.10 – 3.12)
-- **Platforms**: Linux (Ubuntu/Debian), Windows (Native & WSL2), macOS (Apple Silicon & Intel)
-- **Editor (Optional)**: VS Code / Cursor / VSCodium (for extension support)
-
-### 2. Python Package Installation
-```bash
-# Option A: Install from local repository (Editable Mode)
-git clone https://github.com/169Pi/codeagent-poc.git
-cd codeagent-poc
-pip install -e .
-
-# Option B: Install via pre-built Wheel
-pip install alpiecode-2.0.7-py3-none-any.whl
-```
-
-### 3. Launching the AlpieCode API Server
-The API server coordinates between the agent engine and the VS Code extension / SDK:
-```bash
-alpiecode serve
-```
-*Output:*
-```text
-    _    _     _      ____            _      
-   / \  | |_ _| | ___ / ___|___   __| | ___ 
-  / _ \ | | '_ \ |/ _ \ |   / _ \ / _` |/ _ \
- / ___ \| | |_) | |  __/ |__| (_) | (_| |  __/
-/_/   \_\_|_.__/|_|\___|\____\___/ \__,_|\___|
-
-✅ AlpieCode VS Code extension is installed.
-🚀 Starting AlpieCode Server on http://127.0.0.1:7169
-INFO:     Uvicorn running on http://127.0.0.1:7169 (Press CTRL+C to quit)
-```
-
----
-
-## 💻 VS Code Extension Deep-Dive
-
-The AlpieCode VS Code extension provides an IDE sidebar pairing modern AI interaction patterns with developer control:
-
-### 1. ⚡ Slash Commands Autocomplete (`/`)
-Type **`/`** in the chat input area to trigger a floating command palette:
-- `📋 /plan <task>` — Generate an architectural plan without making destructive file edits.
-- `💡 /explain <file>` — Explain a file, function, or concept step-by-step.
-- `🩺 /doctor` — Run full system diagnostic health checks in the chat.
-- `🧪 /test` — Automatically generate unit tests and execute verification.
-- `🔍 /diff` — Inspect recent changes made by AlpieCode in this session.
-- `🗑️ /clear` — Reset and start a fresh chat session.
-
-### 2. 🧠 169Pi Reasoning Effort Dropdown Selector (`⌃`)
-Situated directly in the bottom options bar:
-- ⚖️ **Medium (Default)**: Balanced reasoning depth and generation speed (`temperature: 0.1`).
-- 🧠 **High**: Deep chain-of-thought step-by-step reasoning, full context, maximal accuracy (`temperature: 0.2`).
-- ⚡ **Low (Fast)**: Direct code generation without reasoning traces (`temperature: 0.0`) for quick edits and one-liners.
-
-### 3. 📋 Plan-First Review & Change Approval Workflow
-- **New Files**: Written directly to disk, opened in the editor, and auto-executed in the sandbox.
-- **Modifying Existing Files**: Displays an interactive **Change Plan Card** in chat with an inline line-by-line diff preview (`-` red / `+` green):
-  - **`✅ Accept`**: Applies the change, opens the file, and runs verification.
-  - **`❌ Reject`**: Discards the proposed modification cleanly.
-  - **`✏️ Edit Request`**: Opens an inline input box to type custom instructions (e.g., *"Use an iterative approach instead of recursion"*).
-
-### 4. 🐍 Proactive Virtual Environment (`.venv`) Auto-Detection
-When generated Python code imports external packages (`numpy`, `pandas`, `flask`, etc.):
-- AlpieCode scans the AST imports before execution.
-- If the package is not installed, it pops up:
-  ```text
-  📦 'numpy' is required by matrix_multiplication.py but not installed.
-  🐍 No virtual environment found. Create one?
-
-  [Create .venv & Install]   [Install Globally]   [Skip]
-  ```
-- Selecting **Create .venv & Install** creates `.venv`, installs the package, and executes the script using `.venv/bin/python3`!
-
-### 5. 📊 Live Token & Speed Meter
-Top-right header displays real-time generation speed and token accumulation:
-`🟢 Online API` ── `⚡ 42 tok/s · 📊 1,240 tokens`
-
-### 6. 📎 Multimodal Image Attachment
-Drag-and-drop screenshots, paste from clipboard (`Ctrl+V`), or click **`📎 Image`** to send mockups, diagrams, and error screenshots to the VLM.
-
-### 7. 👻 Inline Ghost Text Code Completions
-As you type in any code editor, AlpieCode streams gray inline suggestions ahead of your cursor (press **`Tab`** to accept).
-
----
-
-## ⌨️ Command-Line Interface (CLI) Guide
-
-AlpieCode offers a complete suite of standalone terminal commands:
-
-### `alpiecode run "<task>"`
-Runs an autonomous coding task in the current repository:
-```bash
-alpiecode run "Create a FastAPI service with SQLite database and CRUD endpoints"
-```
-
-### `alpiecode chat`
-Starts an interactive terminal chat REPL with multi-turn conversation memory:
-```bash
-alpiecode chat
-```
-
-### `alpiecode plan "<task>"`
-Generates a structured implementation plan without making any file edits:
-```bash
-alpiecode plan "Refactor authentication layer to use OAuth2 and JWT tokens"
-```
-
-### `alpiecode explain "<target>"`
-Explains any file, class, function, or concept:
-```bash
-# Explain a local file:
-alpiecode explain src/codeagent/orchestrator.py
-
-# Explain a concept:
-alpiecode explain "How does the tool calling loop work in AlpieCode?"
-```
-
-### `alpiecode doctor`
-Runs an instant system health and environment diagnostic:
-```bash
-alpiecode doctor
-```
-*Checks:*
-- Python version & Virtual Environment status
-- CUDA / GPU hardware acceleration
-- General Internet connectivity (8.8.8.8) & Remote VLM latency (ms)
-- Compilers & runtimes (`gcc`, `g++`, `git`, `node`, `java`, etc.)
-- VS Code extension installation status
-
-### `alpiecode diff`
-Shows all code modifications made by AlpieCode since the last git checkpoint:
-```bash
-alpiecode diff
-```
-
-### `alpiecode init`
-Interactively configures custom model endpoints, API keys, and context parameters:
-```bash
-alpiecode init
-```
-
----
-
-## 📓 Jupyter Notebooks, JupyterLab & Google Colab
-
-### 1. 🪄 IPython Magic Commands
-
-Load AlpieCode in any Jupyter / Colab cell:
-```python
-%load_ext alpiecode
-```
-
-#### Line Magic (`%alpie`)
-```python
-%alpie create a python function to compute moving averages on a pandas Series
-```
-
-#### Cell Magic (`%%alpie`)
-```python
-%%alpie
-Create a script train_model.py that:
-1. Loads dataset from data.csv
-2. Preprocesses numerical and categorical columns with ColumnTransformer
-3. Trains an XGBoost classifier and evaluates with ROC-AUC score
-4. Saves the model with joblib
-```
-
-#### Specialized Notebook Magics:
-```python
-%alpie_plan Build a custom PyTorch dataset loader for audio spectrograms
-%alpie_explain model.py
-%alpie_doctor
-```
-
----
-
-### 2. 🐍 Python SDK API (Programmatic Usage)
-
-```python
-import alpiecode
-
-# 1. Execute task
-alpiecode.run("Create a benchmark script comparing numpy vs cupy matrix multiplication")
-
-# 2. Plan a project
-alpiecode.plan("Implement a Redis caching layer for API responses")
-
-# 3. Explain code
-alpiecode.explain("src/codeagent/tools.py")
-
-# 4. System health check
-alpiecode.doctor()
-```
-
----
-
-### 3. ☁️ Google Colab Setup Guide
-
-In Google Colab:
-```python
-# Cell 1: Install AlpieCode wheel
-!pip install alpiecode
-
-# Cell 2: Load Extension
-%load_ext alpiecode
-
-# Cell 3: Execute Task
-%alpie build a random forest regressor on housing data and display metrics
-```
-
----
-
-## 🛠️ 15 Built-In Agentic Tools
-
-The AlpieCode agent autonomously orchestrates **15 specialized tools**:
-
-| Tool Name | Category | Purpose |
-| :--- | :--- | :--- |
-| `write_file` | File System | Creates new files or overwrites existing files safely |
-| `edit_file` | File System | Precise replacement of target text blocks with exact whitespace matching |
-| `read_file` | File System | Reads complete files or specific line ranges (`start_line`, `end_line`) |
-| `apply_patch` | File System | Applies standard unified diff format patches |
-| `bash` | System Execution | Runs shell commands with environment isolation & guardian safety gate |
-| `list_files` | Workspace Discovery | Recursive directory listing with pattern filtering |
-| `file_search` | Workspace Discovery | Ripgrep regex search across the entire codebase |
-| `view_image` | Multimodal Vision | Inspects and analyzes image files and UI screenshots |
-| `fetch_url` | Web & Research | Fetches live documentation and web pages |
-| `web_search` | Web & Research | Searches technical references and API docs online |
-| `clone_repo` | Repository | Clones public git repositories into workspace for reference |
-| `update_plan` | Agent Planning | Updates structured implementation plan checkpoints (`[x]` / `[ ]`) |
-| `extract_memories` | Memory | Saves long-term user preferences and project patterns |
-| `compact_context` | Optimization | Compresses multi-turn conversation context to prevent token overflows |
-| `diagnostics` | Code Intelligence | Inspects compiler and linter diagnostics |
-
----
-
-## 🛡️ Safety Guardian, Virtual Environment & Guardrails
-
-1. **Safety Guardian Gate** (`src/codeagent/guardian.py`):
-   - Blocks destructive shell commands (e.g. `rm -rf /`, `mkfs`, raw disk writes).
-   - Enforces execution inside the designated project root directory (`workdir`).
-2. **Auto-Fix Loop Rate Limiting**:
-   - Caps automated error retry loops at **3 attempts max** to prevent infinite error-fix cycles.
-   - Prompts the user with actionable diagnostics if errors persist.
-3. **Cross-Platform WSL & Shell Normalization**:
-   - Automatically detects Windows UNC paths (`\\wsl.localhost\...` / `\\wsl$\...`) and routes commands through `wsl -e bash -c`.
-   - Native execution on PowerShell, macOS (zsh), and Linux (bash).
-4. **Context Window Compaction**:
-   - Compresses long multi-turn sessions into concise summaries when context approaches token limits.
-
----
-
-## ❓ FAQ & Troubleshooting
-
-#### Q: The extension shows "Local GGUF" even though I am connected to the internet. Why?
-> **A:** AlpieCode checks reachability of the specific remote model API (`https://test.169pi.ai/v1`). If the remote endpoint is unreachable, it automatically switches to **Local GGUF** so you can continue coding without interruption. Run `alpiecode doctor` to verify.
-
-#### Q: How do I test the extension after updates?
-> **A:** In VS Code, press **`Ctrl+Shift+P`** → select **`Developer: Reload Window`**.
-
-#### Q: Can I use AlpieCode offline without internet?
-> **A:** Yes! AlpieCode includes full offline GGUF inference (`169Pi/Alpie_learn_prototype_GGUF_NEW`) with local tool execution.
-
----
-
-*Generated by AlpieCode AI Platform — Version 2.0.7 / Extension v0.8.5*