palapa-agent 0.1.0__tar.gz

palapa_agent-0.1.0/.claude/settings.local.json

@@ -0,0 +1,18 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(git *)",
+      "Bash(systemctl is-active *)",
+      "Bash(curl -s http://localhost:11434/api/tags)",
+      "Bash(curl -s -m 5 http://10.45.185.253:11494/v1/models)",
+      "Bash(uv run *)",
+      "Bash(uv pip *)",
+      "Bash(uv cache *)",
+      "Read(//home/alan/.cache/uv/**)",
+      "Bash(uvx mcp-server-time *)",
+      "Bash(uvx --no-cache --refresh mcp-server-time --help)",
+      "Bash(uvx *)",
+      "Bash(python3 *)"
+    ]
+  }
+}

palapa_agent-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+__pycache__/
+*.pyc
+config.yaml
+.env
+.pytest_cache/
+*.egg-info/

palapa_agent-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

palapa_agent-0.1.0/AGENTS.md

@@ -0,0 +1,83 @@
+# Palapa — Agent Instructions
+
+Palapa is a locally-running autonomous AI agent framework built in Python. It runs against Ollama models via the OpenAI-compatible endpoint and uses a three-layer memory system (episodic, semantic, procedural). Read `CONTEXT.md` for domain terminology before making changes.
+
+## Relationship to palapa-wiki
+
+This repo (`palapa-agent/`) is basecode only — implementation, not planning. All research, architecture decisions, and Fase/progress tracking live in the sibling repo `../palapa-wiki/` (governed by its own `CLAUDE.md`, not this file).
+
+Before implementing anything non-trivial here, check `palapa-wiki/wiki/overview.md` for current Fase status and `palapa-wiki/wiki/architecture/` + `palapa-wiki/wiki/research/` for the decisions that should inform the approach. Every entry in this file (setup, the architecture table below, code conventions) reflects a decision already recorded in palapa-wiki — it is not invented here. If a change in this repo implies a new convention or design decision, record it in palapa-wiki first (or in the same session), then update this file to match — don't let the two drift apart.
+
+GitHub milestones/issues for this repo are also managed from palapa-wiki's side (its `CLAUDE.md` "Sinkronisasi GitHub milestone/issue" workflow) — this file doesn't duplicate that procedure.
+
+Standing rules from the user (recorded in palapa-wiki's `CLAUDE.md` under "Aturan Tetap dari Feedback User") apply in this repo too. The ones that matter most when working from here:
+
+- **Milestone before code** — always create the GitHub milestone before starting any fase implementation, no matter how small.
+- **Pros AND cons for every option** — when presenting design or implementation choices, spell out trade-offs for each option, not just descriptions.
+
+## Setup
+
+```bash
+uv sync                    # install dependencies
+cp config.yaml.example config.yaml   # first-time setup
+```
+
+Requires Ollama running locally with a tool-calling capable model (e.g. `qwen3.6:27b`).
+
+## Commands
+
+```bash
+uv run pytest              # run all tests
+uv run pytest tests/integration/   # integration tests only (requires Ollama)
+uv run pytest tests/unit/          # unit tests only (no Ollama needed)
+
+uv run palapa chat                       # start interactive CLI session
+uv run palapa chat --once "message"      # single scripted turn, no REPL
+uv run uvicorn palapa.gateway.api:app --reload   # start REST API (host/port from config.yaml `api:` section)
+uv run palapa skills list                # list all skills
+uv run palapa skills show <name>         # print a skill's content
+uv run palapa skills delete <name>       # delete a skill
+uv run palapa sessions search <query>    # query episodic memory (SQLite FTS5)
+```
+
+## Architecture
+
+| Component | Responsibility |
+|-----------|---------------|
+| `agent/core.py` | ReAct agent loop — builds prompt, calls LLM, dispatches tools, repeats |
+| `agent/evaluator.py` | Post-session skill extractor — scores complexity, writes skill files with `auto_extracted` marker, update-or-new LLM decision, never overwrites user-created skills |
+| `tools/` | One file per tool: `bash`, `file`, `web_search`, `web_fetch`, `browser`, `memory` |
+| `tools/registry.py` | Tool registration and schema aggregation for LLM |
+| `memory/session.py` | SQLite FTS5 episodic memory — stores and searches past sessions |
+| `memory/user_model.py` | Reads and writes `USER.md` and `MEMORY.md` |
+| `memory/skills.py` | Agent Skills store — folder format (`{slug}/SKILL.md`), dual dirs (global + `.palapa/skills/`), auto-migration from flat `.md`, relevance matching |
+| `providers/ollama.py` | OpenAI-compat adapter — wraps `openai` SDK with configurable `base_url` |
+| `gateway/runtime.py` | Shared collaborator wiring (`build_agent_loop`) — used by both `gateway/cli.py` and `gateway/api.py` |
+| `gateway/` | Gateway layer — user-facing entry points ke agent |
+| `gateway/cli.py` | `palapa chat` — interactive REPL / `--once` scripted mode |
+| `gateway/api.py` | FastAPI REST API — `POST /chat` (SSE streaming, stateless per ADR-0006), `GET /skills`, `GET /health` |
+| `config.yaml` | Runtime config: model name, base URL, tool flags, memory paths, API host/port |
+
+Flow: `AgentLoop.run(message)` → build system prompt (config + USER.md + relevant skills + episodic hits) → LLM call → parse tool calls → `ToolDispatcher.dispatch()` → feed results back → repeat until final response or max iterations.
+
+## Code Conventions
+
+- **Type hints required** on all function signatures — no bare `def f(x)`.
+- **Pydantic v2** for anything validated from external input (config, LLM output) — e.g. `PalapaConfig`, `EvaluatorConfig`. Plain `@dataclass` is fine for internal, read-only containers that never validate raw input (e.g. `SkillMeta` in `memory/skills.py`, built from already-parsed YAML). When in doubt, default to Pydantic.
+- **No comments except non-obvious WHY** — code must be self-documenting via naming. Never explain what the code does; only explain hidden constraints, subtle invariants, or workarounds.
+- Python 3.11+. Use `uv` for dependency management — do not use `pip` directly.
+
+## Do
+
+- Read `CONTEXT.md` to understand domain terms before writing or renaming anything.
+- Use the `Provider` ABC when adding new LLM backends — never call `openai` directly from the Agent Loop.
+- Write tests at the highest seam possible: prefer `AgentLoop.run()` integration tests over unit tests of internal steps.
+- Keep tool implementations stateless — side effects only, no internal state between calls.
+
+## Do Not
+
+- **Do not modify `config.yaml`** — it is the user's runtime config, not a project file.
+- **Do not hardcode model names** — always read from config. The model is user-controlled.
+- **Do not write to `~/.palapa/`** — that is the user's runtime data directory. Tests must use temp directories.
+- **Do not run the agent loop directly** during development or tests without explicit isolation — it can trigger real bash execution, browser automation, and filesystem writes.
+- **Do not add dependencies** without checking `pyproject.toml` first and confirming the addition is necessary.

palapa_agent-0.1.0/CONTEXT.md

@@ -0,0 +1,99 @@
+# Palapa — Domain Glossary
+
+## Core Concepts
+
+**Agent Loop**
+Owns both a Session's lifecycle and the ReAct-style execution of each Turn within it — one class, mirroring Hermes Agent's `AIAgent` (see ADR-0006). Per Session: assembles the system prompt once at start (Semantic + Procedural + Episodic Memory) and keeps it frozen; accumulates conversation history across Turns; when the session closes, persists it (Episodic Memory) and invokes the Evaluator in the background. Per Turn: call LLM → parse tool calls → dispatch tools → feed results back → repeat until a final response or a configured max iteration count is reached.
+
+**Tool**
+A discrete, named capability the Agent Loop can invoke. Each tool exposes a JSON schema for the LLM and an `execute()` implementation. Tools are stateless; side effects are their whole purpose.
+
+**Skill**
+A reusable reasoning pattern extracted automatically after a complex task completes. Stored as a `.md` file in `skills/`. Loaded into the system prompt at the start of each session if deemed relevant. Distinct from a Tool — a Skill is prose guidance, not executable code.
+
+**Turn**
+One call to the Agent Loop for a single user message — the full ReAct cycle (which may include several internal tool-call iterations) needed to produce one final response. A Session is composed of one or more Turns.
+_Avoid_: "task" — Hermes Agent's own docs use "task" for two unrelated things (the skill-extraction trigger, and its `/background` sub-sessions); Palapa doesn't use "task" as a domain term to avoid the same overload.
+
+**Grace Call**
+One extra, otherwise-identical iteration granted at the end of a Turn when its iteration budget is exhausted, in place of an immediate hard stop — the model can still call a tool if it wants to; nothing is forced or restricted. After that one bonus iteration the loop stops regardless of outcome. Mirrors Hermes Agent's actual `agent/conversation_loop.py` mechanism, verified from source (ADR-0007).
+
+**Context Compaction**
+The process of shortening an Agent Loop's accumulated message history once it crosses a threshold of `context_length`, so a long Session doesn't overflow the model's context window. Always preserves the most recent messages intact and keeps a tool-call and its result together as one unit; anything compacted away is persisted to Episodic Memory first. Two thresholds trigger it, at increasing aggressiveness (ADR-0007).
+
+**Session**
+One continuous interaction from the user's first message until the user ends the conversation, composed of one or more Turns. Sessions are summarized and persisted to Episodic Memory, and evaluated by the Evaluator for Skill extraction, when the session closes — not after each Turn.
+
+**Provider**
+An adapter that wraps an LLM backend behind a common interface. The default Provider targets an Ollama instance via the OpenAI-compatible endpoint (`/v1`). Swapping providers must not require changes to the Agent Loop.
+
+**Config**
+A `config.yaml` file at the project root controlling: model name, provider base URL, context length, tool enable/disable flags, and memory paths.
+
+## Memory Layers
+
+**Episodic Memory**
+A SQLite database with FTS5 full-text search storing summarized past sessions. The Agent Loop queries it at session start to retrieve relevant prior context.
+
+**Semantic Memory**
+Two flat files:
+- `USER.md` — persistent model of the user: preferences, expertise, recurring goals.
+- `MEMORY.md` — general facts the agent has learned that aren't user-specific.
+
+**Procedural Memory**
+The `skills/` directory. Each `.md` file encodes a named, reusable task pattern. Skills are auto-extracted by the Evaluator after complex tasks.
+
+## Components
+
+**Evaluator**
+A post-session subprocess that assesses whether a completed Session was complex and novel enough to warrant Skill extraction. If yes, calls the LLM to write a Skill file. Runs fully automatically — no user confirmation.
+
+**Tool Dispatcher**
+Receives parsed tool-call requests from the LLM response, routes them to the correct Tool implementation, enforces the semi-restricted bash policy, and returns results.
+
+**Semi-Restricted Bash Policy**
+Non-destructive shell commands execute immediately. Destructive commands (those matching a configured danger pattern: `rm`, `sudo`, `dd`, `mkfs`, `chmod -R`, etc.) require explicit user confirmation before execution.
+
+## MCP (Model Context Protocol)
+
+**MCP Server**
+An external tool provider the user configures under `mcp_servers` in Config — either a local subprocess (stdio transport) or a remote endpoint (HTTP transport). Trust is established once, at configuration time, not per call: unlike the Semi-Restricted Bash Policy, invoking an MCP Server's tools requires no per-call confirmation. Palapa is only ever an MCP *client* — it does not expose its own Tools to other MCP clients.
+_Avoid_: "MCP client" as a synonym — Palapa's MCP client is the mechanism; "MCP Server" is the thing being connected to.
+
+**MCP Tool**
+A Tool whose implementation is delegated to an MCP Server rather than Palapa's own code, discovered automatically when Palapa starts and registered into the Tool Dispatcher under the name `mcp_{server}_{tool}`. Functionally a Tool like any other — the Agent Loop cannot tell the difference.
+
+## Agent Delegation
+
+**Agent Preset**
+A named specialist configuration declared in `config.yaml` under `delegation.agents`. Each preset specifies: which Tools the child may use (`tools`), an optional override model (`model`), an optional per-task timeout in seconds (`timeout`, default 120), and whether those tools are hidden from the main agent (`exclusive`). Trust is established at config time, not at call time.
+
+**`delegate_task` (singular)**
+Existing tool (Fase 12). Spawns one child Agent Loop synchronously with a named preset, returns the child's final message as a string. Use for a single bounded sub-task.
+
+**`delegate_tasks` (plural)**
+New tool (Fase 16). Takes a list of labeled sub-tasks `[{label, goal, context, agent}, ...]`, spawns all children in parallel (up to `delegation.max_parallel` at a time, default 2), and returns a dict keyed by label once all finish. Failed children return an `"ERROR: ..."` string for their label — other children are not cancelled. Use when multiple independent sub-tasks can run concurrently.
+_Avoid_: "parallel delegate_task" — the tool name is `delegate_tasks` (plural), a distinct tool from `delegate_task`.
+
+**Parallel Delegation**
+The pattern of using `delegate_tasks` to run multiple specialist children concurrently. Each child is an ephemeral Agent Loop with its preset's tool registry and a minimal system prompt. Children do not share state, cannot communicate with each other, and results are collected only after all children finish (or timeout).
+
+**`max_parallel`**
+A `DelegationConfig`-level integer (default 2) capping how many child threads `delegate_tasks` may spawn simultaneously. Exists as a resource safety valve for local Ollama deployments where each child competes for GPU VRAM.
+
+## Agent Skills
+
+**Agent Skills standard**
+Open format (agentskills.io) for portable skill definitions — a folder named after the skill containing a `SKILL.md` file. Palapa is fully compatible: `SkillsLibrary` reads, writes, and migrates skills in this format.
+
+**Skill folder format**
+A directory named `{slug}/SKILL.md`. The `slug` is the kebab-case name, max 64 characters. The frontmatter `name` field must match the directory name exactly. Other files in the folder (scripts, assets) are ignored by `SkillsLibrary` but preserved by `delete_skill`.
+
+**`SkillsLibrary`**
+Memory module that manages the Agent Skills store. Scans both a global directory (`config.memory.skills_dir`, default `~/.palapa/skills/`) and a project-level directory (`.palapa/skills/` in CWD, convention-based, no config). Project skills override global skills on name conflict. `write_skill` and `delete_skill` target the global dir by default; `delete_skill` targets the project dir first.
+
+**`auto_extracted` marker**
+YAML field `metadata.palapa.auto_extracted: true` injected by the Evaluator into every skill it writes. Skills without this marker are treated as user-created and are never overwritten by the Evaluator — not even when a duplicate is detected. Skills with the marker may be overwritten if the Evaluator's LLM decides the new session is an improvement.
+
+**`evaluator.model`**
+Optional config field on `EvaluatorConfig`. When set, the Evaluator uses a separate `OllamaProvider` with this model name (same `base_url` as the main model) instead of the main agent's provider. Purpose: avoid quality degradation when the main model is small-parameter.

palapa_agent-0.1.0/PKG-INFO

@@ -0,0 +1,244 @@
+Metadata-Version: 2.5
+Name: palapa-agent
+Version: 0.1.0
+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`.

palapa_agent-0.1.0/PRD.md

@@ -0,0 +1,131 @@
+# PRD: Palapa — Local Autonomous AI Agent
+
+## Problem Statement
+
+Existing autonomous AI agent frameworks (including Hermes Agent by NousResearch) either require cloud LLM APIs, lack full configurability, or cannot be modified without forking an upstream dependency. A developer who wants a self-improving, tool-using AI agent running entirely on local hardware — with full control over every component — has no off-the-shelf option that satisfies all three constraints simultaneously.
+
+## Solution
+
+Palapa is a locally-running autonomous AI agent built from scratch, inspired by Hermes Agent's architecture but independently owned. It runs against any Ollama model via the OpenAI-compatible endpoint, uses a three-layer memory system (episodic, semantic, procedural), dispatches a core set of tools (bash, file, web, browser), and automatically extracts reusable Skills after complex tasks. It is accessible via an interactive CLI and a REST API.
+
+## User Stories
+
+1. As a developer, I want to start an interactive chat session with the agent in the terminal, so that I can give it tasks and see its tool-use steps in real time.
+2. As a developer, I want to configure the Ollama model and base URL in a single `config.yaml`, so that I can switch between models without touching code.
+3. As a developer, I want the agent to execute bash commands on my behalf, so that it can automate shell tasks without me copy-pasting commands.
+4. As a developer, I want destructive shell commands (rm, sudo, dd, etc.) to require my explicit confirmation before execution, so that the agent cannot accidentally destroy files.
+5. As a developer, I want the agent to read, write, and list files on my filesystem, so that it can work with project files directly.
+6. As a developer, I want the agent to search the web using DuckDuckGo without requiring an API key, so that it can retrieve up-to-date information.
+7. As a developer, I want the agent to fetch and parse the content of a URL, so that it can read documentation, articles, or API responses.
+8. As a developer, I want the agent to control a headless browser via Playwright, so that it can interact with JavaScript-heavy websites that plain HTTP fetch cannot handle.
+9. As a developer, I want the agent to search my past sessions by keyword, so that it can recall relevant context from previous conversations.
+10. As a developer, I want the agent to maintain a `USER.md` file about my preferences and expertise, so that it personalizes responses across sessions.
+11. As a developer, I want the agent to automatically extract a reusable Skill after completing a complex task, so that it handles similar tasks better in future sessions.
+12. As a developer, I want the Skills library to deduplicate against existing skills before writing a new one, so that the skills directory doesn't accumulate redundant files.
+13. As a developer, I want to call the agent programmatically via a REST API, so that I can integrate it into scripts and other tools.
+14. As a developer, I want the REST API to return streamed responses, so that I can display partial output as the agent works.
+15. As a developer, I want to list, read, and delete skill files via CLI commands, so that I can manage the Skills library without editing the filesystem manually.
+16. As a developer, I want each session to be summarized and persisted to a SQLite FTS5 database on close, so that episodic memory accumulates automatically.
+17. As a developer, I want the agent to load relevant skills from the Skills library at session start, so that prior learned patterns are available without explicit invocation.
+18. As a developer, I want the danger pattern list for bash confirmation to be configurable in `config.yaml`, so that I can tighten or loosen the policy to my comfort level.
+19. As a developer, I want the agent loop to have a configurable max iteration count, so that I can prevent runaway loops on complex tasks.
+20. As a developer, I want clear tool-use output in the CLI showing which tool was called and what it returned, so that I can follow the agent's reasoning step by step.
+
+## Implementation Decisions
+
+- **Provider abstraction:** A `Provider` ABC wraps LLM calls. The default `OllamaProvider` uses the `openai` Python SDK with `base_url: http://10.45.185.253:11494/v1`. Swapping providers requires only a `config.yaml` change. See ADR-0001.
+
+- **Agent Loop:** Owns both a Session's lifecycle and the ReAct-style execution of each Turn within it — one class, mirroring Hermes Agent's `AIAgent` (ADR-0006; a prior design that split this into a separate "Orchestrator" was reconsidered in favor of matching the reference architecture first, splitting later only if a concrete need appears). Per session: assembles the system prompt once at session start (config + USER.md + relevant skills + episodic memory hits) and keeps it frozen for the whole session — skill/memory updates take effect starting the next session, not mid-session (keeps the prompt prefix stable so Ollama can reuse its KV-cache across turns). Accumulates conversation history across Turns, subject to Context Compaction (below). When the session closes, persists it (`SessionStore.save()`) and invokes the Evaluator — both run in the background, not blocking the user-facing response, since both can take 80-100+ seconds. Per turn: call LLM → parse tool calls from response → dispatch via Tool Dispatcher → feed results back → repeat until LLM returns a final message with no tool calls, or max iterations reached (subject to a Grace Call, below). See ADR-0004, ADR-0006.
+
+- **Context Compaction:** Two thresholds against `context_length`, mirroring Hermes Agent's `run_agent.py`. At >50% (preflight), and again more aggressively at >85% (safety net — Hermes runs this in a separate Gateway layer that Palapa has no equivalent of, so both thresholds live in the Agent Loop itself): older messages are compacted, the most recent N are always preserved intact, a tool-call/tool-result pair is never split apart, and anything compacted away is persisted via `SessionStore.save()` first. The exact value of N and the compression method (deterministic truncation vs. LLM summarization) are implementation details, not fixed here. See ADR-0007.
+
+- **Grace Call:** When a Turn's `max_iterations` budget is exhausted, the loop gets exactly one more LLM call instead of a hard stop — `tools=None` (no further tool calls allowed) plus an instruction to summarize progress. Mirrors Hermes's `while (iterations < max and budget > 0) or grace_call` loop condition; the exact mechanism for forcing a summary is Palapa's own interpretation, not a confirmed detail of Hermes's implementation. See ADR-0007.
+
+- **Tool Dispatcher:** Routes tool-call requests to registered Tool implementations. Enforces semi-restricted bash policy (ADR-0002) before executing bash tools. All tools expose a `schema()` method returning an OpenAI-compatible function definition JSON.
+
+- **Tools (v1):**
+  - `BashTool` — executes shell commands; applies danger-pattern check with fail-closed confirmation timeout, a non-configurable hardline blocklist for catastrophic commands, and strips credential-like env vars (`KEY`/`TOKEN`/`SECRET`/`PASSWORD`/`CREDENTIAL`) from the child process. See ADR-0002.
+  - `FileTool` — read, write, list, delete local files
+  - `WebSearchTool` — DuckDuckGo search via `duckduckgo-search` package, no API key
+  - `WebFetchTool` — HTTP GET via `httpx`, returns parsed text
+  - `BrowserTool` — Playwright headless Chromium for JS-heavy pages
+  - `MemoryTool` — search episodic SQLite, read/update USER.md and MEMORY.md
+
+- **Memory system:**
+  - Episodic: SQLite database with FTS5 virtual table. Schema: `(id, timestamp, summary, full_text)`. Searched at session start using keywords extracted from the user's first message.
+  - Semantic: `USER.md` (user model) and `MEMORY.md` (general facts). Flat markdown files, updated by MemoryTool or by Evaluator post-session. Each has a configurable character limit (`memory.user_model_char_limit` / `memory.memory_char_limit`, default 1,375 / 2,200 — matching Hermes Agent's precedent). When a file exceeds 80% of its limit, the next write triggers an LLM consolidation pass that condenses existing entries before appending.
+  - Procedural: `skills/` directory. Each skill is a `.md` file with YAML frontmatter (`name`, `description`, `tags`) followed by four mandatory sections: `## When to Use`, `## Procedure`, `## Pitfalls`, `## Verification`. Loaded at session start by relevance match against current task. See ADR-0005.
+
+- **Evaluator:** Runs after each completed session. Triggers a skill write only if *both* hold: the session's tool-call count ≥ `evaluator.min_tool_calls` (default 5, a cheap structural gate checked first) *and* an LLM complexity score (1–5) ≥ `evaluator.complexity_threshold` (default 4). If triggered and no matching skill already exists (fuzzy match against existing skill descriptions), writes a new skill file. Runs fully automatically — no user confirmation. See ADR-0003, ADR-0005.
+
+- **Config (`config.yaml`):**
+  ```yaml
+  model:
+    name: qwen3.6:27b
+    base_url: http://10.45.185.253:11494/v1
+    context_length: 64000
+    max_iterations: 90
+  memory:
+    db_path: ~/.palapa/sessions.db
+    user_model: ~/.palapa/USER.md
+    memory_md: ~/.palapa/MEMORY.md
+    skills_dir: ~/.palapa/skills/
+    user_model_char_limit: 1375
+    memory_char_limit: 2200
+  evaluator:
+    complexity_threshold: 4
+    min_tool_calls: 5
+  tools:
+    bash:
+      enabled: true
+      danger_patterns: [rm, sudo, dd, mkfs, "chmod -R", truncate, shred, "kill -9", "curl | sh", "wget | sh"]
+      confirmation_timeout_seconds: 60
+    browser:
+      enabled: true
+      headless: true
+  api:
+    host: 127.0.0.1
+    port: 8000
+  ```
+
+- **CLI interface:** `palapa chat` starts an interactive session (one `AgentLoop` instance for the process's lifetime, accumulating history across turns) — ends on `Ctrl+D`/`Ctrl+C`, at which point the session is persisted and the Evaluator runs in the background before the process exits. `palapa skills list|show|delete` manages skills. `palapa sessions search <query>` queries episodic memory.
+
+- **REST API:** FastAPI app, stateless — no server-side session state between requests (see ADR-0006; Palapa doesn't need Hermes's ecosystem-compatibility reasons for a stateful tier). `POST /chat` accepts `{messages: [{role, content}, ...]}` (the full conversation so far) and returns a streaming response; the server treats the whole request as one Session for persistence/Evaluator purposes, run in the background via FastAPI `BackgroundTasks` after the response is sent. `GET /skills` lists skills. `GET /health` returns model + config status.
+
+- **Package manager:** `uv` for dependency management and virtual environment.
+
+## Testing Decisions
+
+- Good tests verify external behavior: given an input message, does the agent produce the expected tool calls and/or final response? Tests must not assert on internal loop state or intermediate LLM calls.
+- **OllamaProvider** is tested with a real Ollama instance running a small fast model (e.g., `llama3.2:3b`) — no mocking of LLM calls.
+- **Tool unit tests:** Each Tool is tested in isolation with real filesystem/network access where possible (BashTool, FileTool), or a local mock server for WebFetchTool. BrowserTool tests use a locally served static HTML file.
+- **Evaluator:** Tested by feeding it a known complex task transcript and asserting a skill file is written to a temp directory.
+- **Agent Loop integration test:** Single end-to-end test: send a task that requires one tool call, assert the correct tool was dispatched and a response was returned.
+
+## Out of Scope
+
+- Text-to-speech (TTS) — ElevenLabs, edge-tts, or any audio output
+- Messaging gateways — Telegram, Discord, Slack, WhatsApp, Signal connectors
+- Multi-user support — authentication, session isolation, user accounts
+- Vector database — chromadb, qdrant, or semantic embedding search
+- Image generation tools
+- Code execution sandbox (Python REPL) — deferred to v2
+- Subagent delegation — spawning isolated child agents for parallel/reasoning-heavy tasks (a Hermes Agent feature). No v1 user story needs it; the ReAct loop's conversation history already carries results forward within a single agent. Candidate for v2 if a real need for parallel independent workstreams emerges.
+
+## Post-v1 (Fase 8)
+
+- **MCP (Model Context Protocol) client support** — not part of v1. Designed 2026-07-06 (see ADR-0008): Palapa gains a native MCP client (stdio+HTTP transports, mirroring Hermes Agent) so external MCP Servers' tools auto-register alongside built-in Tools. Client only — Palapa does not expose itself as an MCP Server. Not yet implemented.
+
+## Post-v1 (Fase 10)
+
+- **Network device management** — not part of v1. Designed 2026-07-07 (see ADR-0009): a native `NetworkTool` (Netmiko-backed) lets Palapa inspect campus and IDREN network devices for a network engineer. Mikrotik only for now (Ruckus/Juniper/Cisco/Huawei deferred); read-only (config-changing commands deferred to v2). Commands are gated by a hard-coded-in-config allowlist, not an LLM-authored blocklist. Not yet implemented.
+
+## Further Notes
+
+- Palapa's name derives from the Sumpah Palapa (Palapa Oath) of Gajah Mada, Mahapatih of Majapahit — a vow to complete a mission before rest. Fitting for an autonomous task-completion agent.
+- The architecture deliberately mirrors Hermes Agent (NousResearch) as a reference, but all code is written independently. No Hermes source is copied.
+- Ollama does not need to run on the same machine as the Palapa process — `base_url` just needs to point at wherever the server is reachable on the user's network (e.g. `http://10.45.185.253:11494/v1`, a non-default port). `OLLAMA_KEEP_ALIVE` and `OLLAMA_CONTEXT_LENGTH` are set on the Ollama server itself, not on the Palapa side.
+- Ollama must be running with `OLLAMA_KEEP_ALIVE=24h` to avoid cold-start latency between agent turns.
+- `context_length` in `config.yaml` is used by Palapa for its own prompt-budgeting/accounting — it does not, by itself, change the model's actual context window in Ollama. The Ollama server's context window must be raised separately via the `OLLAMA_CONTEXT_LENGTH` environment variable or a Modelfile `PARAMETER num_ctx` line; without this, the model may silently truncate context even if `config.yaml` says otherwise.
+- Recommended minimum context is 64,000 tokens for reliable agent + tool-use behavior (tool schemas, skills, and memory hits all consume prompt budget before the actual task starts).
+- The chosen model must support tool/function calling. Recommended: `qwen3.6:27b` (verified working against the project's dev Ollama server in Fase 2/3) or `qwen3.6:35b`. Models without tool-call support will fall back to chat-only mode with a warning.