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 via OpenAI-compatible endpoint (/v1/chat/completions); swap ke LM Studio, vLLM, Groq, atau OpenAI cukup ubah model.base_url di config.yaml

Instalasi

Pengguna umum

pipx install palapa-agent
palapa chat   # wizard berjalan otomatis saat pertama kali

pipx menginstall CLI tool di virtualenv terisolasi — direkomendasikan agar tidak konflik dengan paket Python lain. Kalau belum punya pipx: pip install pipx atau brew install pipx. Alternatif tanpa pipx: pip install palapa-agent (install ke environment aktif).

Developer

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

# 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:

REST API

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

POST   /chat            — kirim pesan, respons streaming SSE
GET    /skills          — daftar semua skills
GET    /health          — health check
POST   /devices         — tambah network device (inventory.yaml), terima kredensial asli, auto-tulis ke ~/.palapa/.env
GET    /devices         — daftar device dari inventory.yaml
DELETE /devices/{name}  — hapus device by name (tolak 400 kalau nama duplikat; kredensial .env TIDAK ikut dihapus)

Endpoint /devices sengaja tanpa auth tambahan (konsisten seluruh REST API ini, asumsi personal-use/localhost) dan sumbernya cuma inventory.yaml — device yang didefinisikan langsung di config.yaml gak akan muncul.

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)

model:
  base_url: "http://localhost:11434/v1"   # Ollama OpenAI-compat endpoint; 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.

Provider lain: Palapa terhubung ke Ollama via OpenAI-compatible endpoint (/v1/chat/completions). Endpoint yang sama dipakai oleh LM Studio, vLLM, Groq, Together, dan OpenAI sendiri — cukup ubah model.base_url (dan model.api_key bila perlu) untuk swap provider tanpa ubah kode.

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)

Testing

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. ADR ada di docs/adr/. Domain glossary ada di CONTEXT.md.