Metadata-Version: 2.4
Name: alpielocal
Version: 10.11.4
Summary: AlpieLocal
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: huggingface_hub>=0.20.0
Requires-Dist: rich>=13.0
Requires-Dist: click>=8.0
Requires-Dist: httpx[http2]>=0.24.0
Requires-Dist: beautifulsoup4>=4.12.0
Requires-Dist: yt-dlp>=2024.0.0
Requires-Dist: prompt-toolkit>=3.0.0
Requires-Dist: packaging>=23.2
Requires-Dist: Pillow>=10.0.0
Requires-Dist: imageio-ffmpeg>=0.4.0
Provides-Extra: vision
Requires-Dist: Pillow>=10.0.0; extra == "vision"
Provides-Extra: browser
Requires-Dist: playwright>=1.48.0; extra == "browser"
Provides-Extra: documents
Requires-Dist: pypdf>=5.0.0; extra == "documents"
Provides-Extra: server
Requires-Dist: fastapi>=0.100.0; extra == "server"
Requires-Dist: uvicorn>=0.20.0; extra == "server"
Requires-Dist: sse-starlette>=2.0.0; extra == "server"
Provides-Extra: ffmpeg
Requires-Dist: imageio-ffmpeg>=0.4.0; extra == "ffmpeg"

# AlpieLocal

AlpieLocal is a command-line coding agent for exploring repositories, editing code, debugging, and running verification commands. It supports online inference through a configured endpoint and offline inference with local GGUF models through llama.cpp.

## Requirements

- Python 3.9 or newer. Python 3.11 or 3.12 is a practical choice for native runtime compatibility.
- Windows, Linux, or macOS with a compatible Python architecture.
- Internet access for package installation and the initial model/runtime downloads.
- Sufficient disk space, RAM, and optional GPU memory for the selected model and context size.
- Your project's own tools, such as Git, Node.js, or a test runner, when the task requires them.

### Offline hardware guidance

The default Q3 text weights occupy approximately **4.4 GiB**, and the vision projector adds approximately **0.86 GiB**. Loading also needs memory for context/KV cache, compute buffers, the operating system, and project tools.

These are **planning estimates for text tasks at 4,096–8,192 tokens**, not certified minimum specifications:

| Execution mode | Practical starting configuration | Preferred configuration |
|---|---|---|
| CPU only | Compatible 64-bit CPU, 4 or more cores, 16 GB system RAM | Modern CPU with 8 or more cores and 32 GB RAM |
| NVIDIA CUDA | 16 GB system RAM and 6 GB VRAM with partial GPU offload | 32 GB system RAM and 8 GB or more VRAM |
| Apple Silicon Metal | Native arm64 Python and 16 GB unified memory | 24–32 GB or more unified memory |

Reserve at least **15 GB of free disk space** for model assets, the environment, and download caches; source builds and project dependencies can need more. Machines with 8 GB RAM may run into memory pressure and are not the recommended baseline. Larger contexts, images, and video frames increase memory use; the configured 262,144-token ceiling is not a laptop memory recommendation.

A dedicated GPU is optional. CPU inference is slower, and the runtime must match the CPU architecture and instruction support. Bundled CPU wheels cover supported Windows x64 and Linux x64/ARM64 platforms; Intel Macs require a compatible manual build. Apple Silicon uses shared memory rather than separate GPU VRAM. Development probes loaded the model on an RTX 3050 with 6 GB VRAM using partial offload and a 16,384-token context; this does not establish compatibility with every 6 GB GPU.

To force CPU operation, set the variable before starting chat:

```powershell
# Windows PowerShell
$env:ALPIELOCAL_CPU = "1"
alpielocal chat --offline --no-thinking --ctx-size 8192
```

```bash
# Linux or macOS
ALPIELOCAL_CPU=1 alpielocal chat --offline --no-thinking --ctx-size 8192
```

## Installation

### Global command with pipx

[pipx](https://pipx.pypa.io/latest/how-to/install-pipx.html) makes `alpielocal` available across projects while keeping its Python dependencies in a dedicated environment.

**Windows PowerShell**

```powershell
py -m pip install --user pipx
py -m pipx ensurepath
```

**Linux, Ubuntu or Debian**

```bash
sudo apt update
sudo apt install pipx
pipx ensurepath
```

**macOS, with Homebrew**

```bash
brew install pipx
pipx ensurepath
```

Open a new terminal, then install and check the command:

```bash
pipx install alpielocal
alpielocal --version
```

For other Linux distributions, use the pipx installation guide linked above. A pipx installation is available from your terminal without activating a project environment.

### Python virtual environment

**Windows PowerShell**

```powershell
py -3.12 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install alpielocal
```

If PowerShell blocks activation, install and run through the environment's interpreter directly:

```powershell
.\.venv\Scripts\python.exe -m pip install alpielocal
.\.venv\Scripts\alpielocal.exe --version
```

**Linux or macOS**

```bash
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install alpielocal
```

On Debian or Ubuntu, install `python3-venv` if creating the environment fails. Use an installed Python version in place of `py -3.12` when necessary.

### Install with uv

Install [uv](https://docs.astral.sh/uv/getting-started/installation/) using the command for your platform.

**Windows PowerShell**

```powershell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```

**Linux or macOS**

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

Open a new terminal. To make AlpieLocal available across projects in a managed tool environment:

```bash
uv tool install --python 3.12 alpielocal
uv tool update-shell
```

Reopen the terminal if PATH was updated, then run `alpielocal --version`. Alternatively, create a project environment:

```bash
uv venv --python 3.12 .venv
```

Activate `.venv` using the Windows or Linux/macOS activation command above, then run:

```bash
uv pip install alpielocal
alpielocal --version
```

uv environments do not need pip installed to use `uv pip`. Choose either a global tool installation or a project environment so it is clear which CLI and runtime you are using. See the [uv tools guide](https://docs.astral.sh/uv/guides/tools/) for details.

### Existing environments

Activate your existing `venv`, virtualenv, Conda, uv, or Poetry environment, then install into its Python interpreter:

```bash
python -m pip install --upgrade alpielocal
python -c "import sys; print(sys.executable)"
alpielocal --version
```

If the environment has no pip, use its package manager; for example, `uv pip install alpielocal` or `poetry add alpielocal`. AlpieLocal does not require a uv-created environment. Its runtime installer may use uv when available, but targets the interpreter running AlpieLocal.

### From this repository

From the repository root, with your chosen environment activated:

```bash
python -m pip install -e .
alpielocal --version
```

For a global command from the checkout, use `pipx install .` instead. Source installation includes changes that may not yet be available in a published package.

## First use

### Start interactive chat

Run AlpieLocal from the project you want to work on:

```bash
cd path/to/project
alpielocal
```

The explicit chat command is equivalent:

```bash
alpielocal chat
```

After completing offline initialization, start local chat with:

```bash
alpielocal chat --offline --no-thinking --ctx-size 8192
```

Type your request at the prompt. Use `/help` for chat commands, `/status` for session diagnostics, and `exit` or `quit` to leave. If installed into a virtual environment, activate it before starting chat.

### Run a single task

Submit a task directly when an interactive conversation is unnecessary:

```bash
alpielocal run "Investigate the failing tests, make a targeted fix, and verify it."
```

Online mode uses the configured inference endpoint. To select your own deployment:

```bash
alpielocal run "Explain this repository." --endpoint "https://your-server.example/v1" --model "your-model"
```

Offline mode requires the setup below.

## Offline setup

### Initialize models and llama.cpp

While connected to the internet, run this once from your intended workspace:

```bash
alpielocal init
```

Initialization saves configuration, downloads missing model files, and installs or checks `llama-cpp-python`, the Python binding used to run llama.cpp. A separate llama.cpp CLI installation is not required.

The default assets are:

| Asset | File |
|---|---|
| Text model | `alpie-vl-text-q3_k_m.gguf` |
| Vision projector | `alpie-vl-mmproj-f16.gguf` |
| Model repository | `169Pi/alpie_learn_gguf` |
| Automatic runtime version | `llama-cpp-python 0.3.35` |

The default model distribution resolves its built-in credential automatically; users do not normally need to enter `HF_TOKEN`. Downloads still require valid repository access. Custom private repositories require an authorized Hugging Face login or token.

The automatic installer selects compatible, hash-checked wheels and checks that the runtime imports. It does not compile native code. Setup can be cancelled and rerun; completed downloads are reused. An import check does not establish model generation or task accuracy.

### Windows

Use 64-bit Python for the bundled Windows x64 wheels. In PowerShell, activate the environment where AlpieLocal is installed, then run:

```powershell
alpielocal init
alpielocal run "Say hello" --offline --no-thinking --ctx-size 8192
```

The installer tries compatible NVIDIA CUDA, Vulkan, and CPU runtimes. GPU use depends on the selected wheel and installed drivers. Native Windows and WSL have separate Python environments and runtime installations; run setup inside the environment you will use.

### Linux

Activate your environment and run:

```bash
alpielocal init
alpielocal run "Say hello" --offline --no-thinking --ctx-size 8192
```

The installer selects wheels matching the interpreter architecture and Linux platform. NVIDIA systems can use CUDA; compatible Vulkan and CPU builds are also considered. Linux ARM64 CPU wheels are included for supported platforms.

### macOS

On Apple Silicon, use a native arm64 Python installation. Check its architecture:

```bash
python -c "import platform; print(platform.machine())"
alpielocal init
alpielocal run "Say hello" --offline --no-thinking --ctx-size 8192
```

Apple Silicon should report `arm64`; setup tries Metal, then CPU. An x86_64 Python running under Rosetta does not match the bundled arm64 wheels. The pinned automatic runtime has no Intel Mac wheel; Intel users need a compatible manual runtime installation.

### Manual llama.cpp runtime installation

Use `alpielocal init` first. If your platform has no supported bundled wheel, install a compatible `llama-cpp-python` into the same environment, then rerun initialization.

The commands below target an activated Python environment. In an activated uv environment without pip, replace `python -m pip` with `uv pip`.

**NVIDIA CUDA: Windows x64**

Check that `nvidia-smi` detects your GPU. The pinned runtime uses a CUDA 12.4 build and needs a compatible NVIDIA driver and GPU. Install the matching wheel:

```powershell
python -m pip install --force-reinstall --no-cache-dir --only-binary=:all: "https://github.com/abetlen/llama-cpp-python/releases/download/v0.3.35-cu124/llama_cpp_python-0.3.35-py3-none-win_amd64.whl#sha256=84f7218c1e9cf21014b9770c65064c5a3674dd2f4fbc312c5d6bb40cec0fb269"
```

**NVIDIA CUDA: Linux x64**

This bundled CUDA wheel targets glibc 2.35 or newer. On another platform, let initialization select an alternative or use the upstream build instructions.

```bash
python -m pip install --force-reinstall --no-cache-dir --only-binary=:all: "https://github.com/abetlen/llama-cpp-python/releases/download/v0.3.35-cu124/llama_cpp_python-0.3.35-py3-none-manylinux_2_35_x86_64.whl#sha256=62fc788a4ecee5a579f40708ccfe0c4d566dd5c9959497bdc0544dbba94d82aa"
```

**Apple Silicon: macOS Metal**

Use native arm64 Python and install the Metal wheel. CUDA is for NVIDIA GPUs; Apple Silicon acceleration uses Metal.

```bash
python -m pip install --force-reinstall --no-cache-dir --only-binary=:all: "https://github.com/abetlen/llama-cpp-python/releases/download/v0.3.35-metal/llama_cpp_python-0.3.35-py3-none-macosx_11_0_arm64.whl#sha256=faf9a2b38df5cbf9427a074f974c00abbb799185753c474672fd461c198b7a0a"
```

**CPU or source build**

For an available CPU wheel, try:

```bash
python -m pip install --only-binary=:all: llama-cpp-python==0.3.35 --extra-index-url https://abetlen.github.io/llama-cpp-python/whl/cpu
```

If no compatible wheel exists, a source build requires a native compiler and build tools. A CPU build can be installed with:

```bash
python -m pip install --no-binary=llama-cpp-python llama-cpp-python==0.3.35
```

Source builds require a C/C++ toolchain on Windows, GCC or Clang on Linux, or Xcode command-line tools on macOS. See the upstream [llama-cpp-python installation documentation](https://llama-cpp-python.readthedocs.io/en/latest/#installation) for CUDA, Metal, and other build options.

Verify the environment afterward:

```bash
python -c "from llama_cpp import Llama; print('Runtime import OK')"
alpielocal init
```

For pipx installations, use `pipx runpip alpielocal install` in place of `python -m pip install` so the runtime is installed into AlpieLocal's environment. For a global uv tool installation, prefer `alpielocal init`, which targets that environment automatically. For manual installation, run `uv tool dir`, locate `alpielocal/bin/python` on Linux/macOS or `alpielocal/Scripts/python.exe` on Windows beneath that directory, and use `uv pip install --python "/full/path/to/that/python"` with the wheel URL above.

To check whether the installed runtime supports GPU offload:

```bash
python -c "import llama_cpp; print('GPU offload support:', llama_cpp.llama_supports_gpu_offload())"
```

This reports build capability. Confirm actual device use in the model-loading output when starting offline chat. Run import checks through the same environment's Python; a global tool environment is separate from your project's Python.

### Run without networking

Once the package, model files, runtime, and project dependencies are installed:

```bash
alpielocal --offline --no-thinking --ctx-size 8192
alpielocal run "Fix the failing tests and verify the changes." --offline --no-thinking --ctx-size 8192
```

Use `alpielocal --network-policy deny init` to check existing setup assets without downloading them. Offline inference does not provide online services or download missing project dependencies.

`--network-policy deny` disables network-aware agent tools and selects local inference. Arbitrary shell subprocesses require operating-system isolation for an enforced network boundary. On Linux with bubblewrap installed:

```bash
alpielocal run "Inspect and repair the failing test." --offline --no-thinking --sandbox --ctx-size 8192
```

The configured context ceiling is 262,144 tokens in both modes, with a maximum output setting of 65,537 tokens. Actual generation is constrained by task budgets, available context, model support, and memory. The smaller examples above reduce local memory requirements. Native offline structured tool calls currently require non-thinking generation; use `--no-thinking` for local coding tasks.

## Essential commands

| Command | Purpose |
|---|---|
| `alpielocal` | Start interactive chat in the current directory |
| `alpielocal run "TASK"` | Execute a task |
| `alpielocal plan "TASK"` | Prepare a plan without editing files |
| `alpielocal explain path/to/file.py` | Explain a file or concept |
| `alpielocal diff` | Inspect recorded changes |
| `alpielocal undo` | Restore file-tool changes from the last session where possible |
| `alpielocal sessions` | List saved sessions |
| `alpielocal resume SESSION_ID` | Resume a saved session |
| `alpielocal doctor` | Check the environment and available tools |
| `alpielocal --help` | Show available commands and options |

Use `--workdir path/to/project` to select another workspace. In chat, `/help` lists commands and `/status` shows the active model, mode, context usage, and attachments.

## Images, video, and optional tools

Attach media to a task using quoted paths:

```bash
alpielocal run "Explain the error shown in this screenshot." --image "screenshot.png"
alpielocal run "Summarize the concepts shown in this video." --video "lesson.mp4" --offline --no-thinking --ctx-size 16384
```

In chat, use `/image "path/to/image.png"` or `/video "path/to/video.mp4"`, then submit your request. Image understanding requires a working vision model/projector. Video analysis samples frames; it does not establish full video or audio understanding. Video extraction uses system FFmpeg when available, otherwise the included `imageio-ffmpeg` binary on supported platforms.

Optional integrations:

| Tool | Installation or prerequisite |
|---|---|
| Browser interaction checks | `python -m pip install "alpielocal[browser]"`, then `python -m playwright install chromium` |
| PDF text extraction | `python -m pip install "alpielocal[documents]"` |
| Local speech transcription | Installed `whisper-cli`, FFmpeg, and local weights selected by `ALPIELOCAL_WHISPER_MODEL` |
| Language-server diagnostics | An installed server configured through `ALPIELOCAL_LSP_COMMAND` as a JSON argument list |

For pipx, expose Playwright's command when installing browser support:

```bash
pipx inject --include-apps alpielocal playwright
playwright install chromium
pipx inject alpielocal pypdf
```

Optional runtimes and weights must also be prepared before disconnecting. See the [pipx inject reference](https://pipx.pypa.io/stable/reference/cli.html#pipx-inject) for environment management.

## Configuration

Configuration normally lives in `.alpielocal/config.json` under the setup directory. Existing `.alpiecode` configuration and caches remain readable. Model lookup reuses existing home-directory caches or the workspace cache; setup prints the selected path.

| Environment variable | Purpose |
|---|---|
| `ALPIELOCAL_HOME` | State and configuration directory |
| `ALPIELOCAL_MODELS_DIR` | Model cache directory |
| `ALPIELOCAL_MODEL_PATH` | Explicit local text-model GGUF file |
| `ALPIELOCAL_BASE_URL` | Online inference endpoint |
| `ALPIELOCAL_API_KEY` | Online endpoint authentication |
| `ALPIELOCAL_MODEL` | Online model identifier |
| `ALPIELOCAL_CPU=1` | Disable GPU offload |

Set a persistent `ALPIELOCAL_HOME` before initialization if you want to share one setup across workspaces. Keep credentials out of version control.

## Troubleshooting

- **Command not found:** reopen the terminal after `pipx ensurepath`, or activate the environment containing AlpieLocal. Check its interpreter with `python -c "import sys; print(sys.executable)"`.
- **Runtime installed in another environment:** install or initialize using the same interpreter as the CLI. A pipx installation and a project virtual environment are separate.
- **Wheel extraction or hash error:** the installer retries a fresh download once. If it still fails, check the reported asset and platform, update AlpieLocal, and rerun `alpielocal init`. Do not bypass integrity checks.
- **Model authentication error:** cached models may work even when fresh downloads cannot authenticate. Check repository access and the installed distribution's credential configuration.
- **Insufficient memory:** reduce `--ctx-size`, reduce GPU offload with `ALPIELOCAL_GPU_LAYERS`, or select CPU mode with `ALPIELOCAL_CPU=1`.
- **Video extraction unavailable:** install or update `imageio-ffmpeg` in the environment running AlpieLocal.

## Upgrade AlpieLocal

Use the upgrade command matching your installation method:

| Installation | Upgrade command |
|---|---|
| Global uv tool | `uv tool upgrade alpielocal` |
| Global pipx tool | `pipx upgrade alpielocal` |
| Python/pip environment | `python -m pip install --upgrade alpielocal` |
| Activated uv environment | `uv pip install --upgrade alpielocal` |
| Editable source checkout | Update the checkout, then run `python -m pip install -e .` or `uv pip install -e .` |

Close existing AlpieLocal sessions before upgrading. Activate the relevant environment for environment-based installs, then verify and check offline setup:

```bash
alpielocal --version
alpielocal init
```

Initialization reuses valid cached model files. Upgrading the CLI does not automatically replace existing model weights or guarantee a different runtime build; use the runtime installation instructions when changing acceleration backends.

## Verification

AlpieLocal records file mutations and command results, requires behavioral acceptance checks for coding completion, and reruns relevant verification. Review the resulting diff and tests before relying on generated changes. Undo protects detected concurrent edits, but does not cover every arbitrary shell mutation or external side effect.
