Metadata-Version: 2.5
Name: palapa-agent
Version: 0.1.3
Summary: Palapa — local autonomous AI agent built on Ollama
Project-URL: Homepage, https://github.com/indi9o/palapa-agent
Project-URL: Bug Tracker, https://github.com/indi9o/palapa-agent/issues
License: MIT
Keywords: agent,ai,autonomous,llm,network-operations,ollama
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: System :: Networking :: Monitoring
Requires-Python: >=3.11
Requires-Dist: beautifulsoup4>=4.15.0
Requires-Dist: ddgs>=9.14.4
Requires-Dist: fastapi>=0.115.0
Requires-Dist: httpx>=0.28.1
Requires-Dist: mcp>=1.28.0
Requires-Dist: netmiko>=4.3.0
Requires-Dist: openai>=1.0
Requires-Dist: playwright>=1.61.0
Requires-Dist: prompt-toolkit>=3.0
Requires-Dist: pydantic>=2.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0
Requires-Dist: uvicorn[standard]>=0.30.0
Description-Content-Type: text/markdown

# Palapa

Autonomous AI agent lokal berbasis Ollama. Berjalan sepenuhnya offline, tanpa cloud API, dengan arsitektur yang bisa dimodifikasi bebas.

---

## Fitur

- **ReAct agent loop** — multi-turn, tool-calling, dengan context compaction otomatis
- **6 tools bawaan** — bash, file, web search, web fetch, browser (Playwright), memory
- **3-layer memory** — episodic (SQLite FTS5) + semantic (USER.md/MEMORY.md) + procedural (skills/)
- **Skills auto-extraction** — Evaluator otomatis menulis skill baru setelah task kompleks, tanpa konfirmasi
- **Skills portabilitas** — export skills ke git repo lokal, import dari remote, sync antar mesin
- **Agent delegation** — main agent bisa mendelegasi sub-task ke child agent specialist, paralel
- **Network tools** — Mikrotik RouterOS + Ruckus ICX + Cisco/Juniper/Aruba/Huawei via Netmiko, bundled whitelist per vendor/OS, read-only
- **MCP client** — koneksi ke MCP server eksternal (stdio + HTTP)
- **CLI interaktif** — history, multi-line input, slash commands, first-run wizard
- **REST API** — FastAPI, streaming SSE, stateless per request
- **Provider configurable** — Ollama default, swap via `model.base_url` di config

---

## Instalasi

### Pengguna umum

```bash
pip install palapa-agent
palapa chat   # wizard berjalan otomatis saat pertama kali
```

### Developer

```bash
git clone https://github.com/indi9o/palapa-agent
cd palapa-agent

uv sync

# Pertama kali pakai browser tool:
uv run playwright install chromium
```

Jalankan `uv run palapa chat` — wizard otomatis muncul kalau config belum ada.

---

## Penggunaan

> **Catatan:** Contoh perintah di bawah menggunakan `palapa` langsung — berlaku setelah `pip install palapa-agent`.
> Kalau kamu pakai mode developer (`uv sync`), tambahkan prefix `uv run`: `uv run palapa`, `uv run palapa devices list`, dst.

### CLI

```bash
# Sesi interaktif
palapa

# Satu perintah, tanpa REPL
palapa --once "ringkasan interface eth0 di router X"

# Inventory perangkat jaringan
palapa devices add          # tambah perangkat secara interaktif
palapa devices list         # lihat daftar perangkat

# Kelola skills
palapa skills list
palapa skills show <nama>
palapa skills delete <nama>
palapa skills install-defaults          # install 17 bundled starter skills
palapa skills install-defaults --overwrite

# Export/import skills antar mesin
palapa skills export --repo <path>              # copy ke git repo lokal + auto-commit
palapa skills import git+<url>                  # clone dari remote, register sebagai sumber
palapa skills pull                              # update dari semua remote terdaftar
palapa skills pull <remote-name>
palapa skills remotes                           # lihat daftar remote terdaftar

# Cari sesi sebelumnya (episodic memory)
palapa sessions search <query>
```

**Slash commands di dalam `palapa chat`:**

| Command | Fungsi |
|---|---|
| `/status` | Info sesi + model aktif + token usage |
| `/clear` | Reset histori percakapan |
| `/compact` | Paksa compaction konteks sekarang |
| `/verbose` | Toggle tampilan tool call raw/ringkas |
| `/audit` | Toggle audit log tool call |
| `/skills` | Daftar skills yang ter-load sesi ini |
| `/<skill-name>` | Inject skill langsung ke agent |

### REST API

```bash
uv run uvicorn palapa.gateway.api:app --reload
```

```
POST /chat          — kirim pesan, respons streaming SSE
GET  /skills        — daftar semua skills
GET  /health        — health check
```

---

## Konfigurasi

Config dicari di dua lokasi (prioritas atas ke bawah):

1. `./config.yaml` — developer, per-project
2. `~/.palapa/config.yaml` — user install (dibuat oleh wizard)

```yaml
model:
  base_url: "http://localhost:11434/v1"   # override via env PALAPA_BASE_URL
  name: "qwen3.6:27b"
  context_length: 64000

tools:
  bash:
    enabled: true
  browser:
    enabled: true
  network:
    enabled: false              # aktifkan kalau pakai NetworkTool
    inventory_path: "~/.palapa/inventory.yaml"
    scripts_enabled: false      # opt-in eksplisit untuk run_skill_script
    # whitelist_extend:         # tambah command di luar bundled default
    #   mikrotik:
    #     ros7: ["/my-cmd"]

memory:
  skills_dir: "~/.palapa/skills/"
  db_path: "~/.palapa/sessions.db"
  user_model: "~/.palapa/USER.md"
  memory_md: "~/.palapa/MEMORY.md"
  soul_md: "~/.palapa/SOUL.md"   # persona agent, ditulis manual

audit:
  enabled: false   # catat semua tool call ke SQLite

api:
  host: "127.0.0.1"
  port: 8000

# Agent presets untuk delegation
delegation:
  max_parallel: 2
  agents:
    network-specialist:
      alias: "Budi"
      model: "qwen3.6:27b"
      exclusive: true          # tool preset hanya via delegasi, disembunyikan dari main agent
      timeout: 120
      tools: [network, bash, memory]
```

Lihat `config.yaml.example` untuk contoh lengkap.

**Inventory perangkat** tersimpan terpisah di `~/.palapa/inventory.yaml` — kelola via `palapa devices add/list` atau edit manual.

---

## Arsitektur

```
AgentLoop.run(pesan)
  → bangun system prompt (SOUL.md + USER.md + skills relevan + episodic hits)
  → LLM call
  → parse tool calls → ToolDispatcher.dispatch()
  → feed hasil → ulang sampai respons final / max iterasi
  → sesi tutup: persist ke episodic, jalankan Evaluator (background)
```

| Komponen | Tanggung jawab |
|---|---|
| `agent/core.py` | ReAct loop — prompt, LLM call, dispatch tools |
| `agent/evaluator.py` | Post-session skill extractor — skor kompleksitas, tulis SKILL.md |
| `tools/` | Satu file per tool (bash, file, web_search, web_fetch, browser, memory) |
| `tools/network.py` | NetworkTool — Netmiko, bundled whitelist, whitelist_extend |
| `tools/network_whitelist.py` | BUNDLED_WHITELIST per vendor/OS |
| `mcp/` | MCP client manager (stdio + HTTP) |
| `memory/session.py` | Episodic memory — SQLite FTS5 |
| `memory/user_model.py` | Semantic memory — USER.md dan MEMORY.md |
| `memory/skills.py` | Procedural memory — folder `{slug}/SKILL.md`, dual dir, auto-migration |
| `providers/ollama.py` | OpenAI-compat adapter ke Ollama |
| `setup/` | Wizard, devices, skills installer, skills git export/import |
| `gateway/runtime.py` | Wiring collaborator bersama (`build_agent_loop`) |
| `gateway/cli.py` | Interactive REPL + `--once` scripted mode + semua subcommand |
| `gateway/api.py` | FastAPI REST API — SSE streaming, stateless |

---

## Testing

```bash
uv run python -m pytest                          # semua test
uv run python -m pytest tests/unit/             # unit test (tidak butuh Ollama)
uv run python -m pytest tests/integration/      # integration test (butuh Ollama berjalan)
```

---

## Dokumentasi

Riset, keputusan arsitektur, eksperimen, dan progress implementasi dikelola di [palapa-wiki](https://github.com/indi9o/palapa-wiki). ADR ada di `docs/adr/`. Domain glossary ada di `CONTEXT.md`.
