Metadata-Version: 2.4
Name: ploop
Version: 0.1.0
Summary: Ploop (Proactive Loop), a lightweight local proactive agent for Apple Silicon.
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: mlx-lm==0.31.3
Requires-Dist: transformers==5.0.0

# Ploop

**Ploop** stands for **Proactive Loop**. It is a **local, proactive, autonomous** AI agent
running entirely on-device via **MLX** (Apple Silicon). No cloud calls: the model runs
locally, the agent decides on its own what to do on every cycle, and everything is
controllable from the `ploop` CLI.

The project rule is to stay **proactive, lightweight, and small**: prefer a few explicit
standard-library functions over agent frameworks, broad abstractions, or extra dependencies.
New code should earn its lines by directly improving the proactive loop, safety, or local
runtime behavior.

On every "cycle" the agent reads its own open goals and recent history, asks the model —
without a specific prompt from the user — "what do you do now?", and the model picks a tool
to run (write a note, read/write a file, close a goal that's been reached, or just wait). In
`loop` mode this repeats at regular intervals, indefinitely: this is the autonomous mode,
meant to run in the background without supervision.

By default the agent operates in the directory where you launch it. Use `-C /path/to/project`
to point it at another directory; its state and notes live in that directory's hidden
`.ploop/` folder.

## Requirements

- macOS on Apple Silicon (arm64) — MLX requires the Apple Silicon GPU.
- Python 3.10+
- ~3 GB of free disk space for the model weights (downloaded automatically on first run from
  Hugging Face for the default model:
  [`mlx-community/Qwen3-4B-Instruct-2507-4bit`](https://huggingface.co/mlx-community/Qwen3-4B-Instruct-2507-4bit))

## Installation

Install from PyPI:

```bash
python3 -m pip install ploop
```

This installs the `ploop` CLI command.

For local development from this source checkout:

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
```

The repo-local `./bin/ploop` wrapper also works for development.

## Quick start

```bash
ploop run "Inspect this folder and write a short note with the next useful step."
ploop status        # shows what it did
```

To run one cycle against another folder:

```bash
ploop -C /path/to/project run "Inspect this project and write the next useful step."
```

To let it run continuously in the background:

```bash
ploop loop "Monitor this folder and write useful notes when there is something worth doing next." --interval 60
```

## Model

The default model is `mlx-community/Qwen3-4B-Instruct-2507-4bit`, chosen because it is small
and supports the tool-call format Ploop expects. You can override it with any MLX-compatible
Hugging Face model id or local model directory:

```bash
ploop run "Inspect this folder" --model /Users/me/models/my-mlx-model
ploop model set /Users/me/models/my-mlx-model
ploop model show
```

Model priority is: `--model`, saved project setting, `PLOOP_MODEL`, then the default model.
Ploop intentionally stays single-backend for now: GGUF/Ollama/llama.cpp models need a future
backend adapter rather than extra framework code in the core loop.

## Documentation

The full reference (CLI commands, tools available to the model, architecture, security,
testing, troubleshooting) lives in the [`docs/`](docs/README.md) folder:

| Document | Content |
|---|---|
| [docs/architecture.md](docs/architecture.md) | How the project is built and how the proactive cycle works |
| [docs/cli.md](docs/cli.md) | Full reference of every CLI command |
| [docs/agent-tools.md](docs/agent-tools.md) | The tools the model can invoke |
| [docs/security.md](docs/security.md) | Sandboxing and what to know before running it unsupervised |
| [docs/test.md](docs/test.md) | How to run the tests |
| [docs/troubleshooting.md](docs/troubleshooting.md) | Known issues and fixes |
| [CHANGELOG.md](CHANGELOG.md) | Release history |

## Project structure

```
agent/          — agent code (llm.py, tools.py, state.py, core.py, cli.py)
bin/ploop       — CLI wrapper (uses `.venv` if present, then runs `python -m agent`)
bin/agent       — compatibility wrapper that delegates to `bin/ploop`
pyproject.toml — local editable install and `ploop` CLI entry point
tests/          — unit tests + end-to-end smoke test
docs/           — full documentation
```
