offlineaid-pack-builder

Build offline .oapack.zip knowledge packs from any source — PDFs, scraped public-data sites, local files, MCP servers, or piped JSON. Packs are portable SQLite FTS5 databases that on-device AI agents can query without internet.

Zero runtime dependencies. The core packager.py uses only the Python standard library (sqlite3, json, csv, struct, zipfile, hashlib). Optional extras (agent, ocr, scrape, upload) are installed only when the relevant pipeline stages run.

License: Apache-2.0.

Two ways to use it

1. As a CLI tool — run make pack INPUTS=<dir> or invoke packager.py subcommands directly. Works from any shell, including automation scripts and CI.
2. As an agent skill — SKILL.md is a portable skill manifest. Any agent runtime that supports skills (Claude Code, OpenClaw, MCP-capable hosts) can discover and invoke the pack-builder by shelling out to the CLI.

The CLI is the contract; the skill manifest is a thin wrapper over it.

Install as a skill

This package ships an Anthropic-format skill manifest (SKILL.md at the repo root) and a plugin manifest (.claude-plugin/plugin.json), so it is discoverable by any skills.sh-compatible agent runtime:

npx skills add helenkwok/offlineaid-pack-builder

Compatible with Claude Code, Cursor, Codex CLI, GitHub Copilot, Windsurf, Gemini CLI, Cline, OpenClaw, and the broader vercel-labs/skills ecosystem.

Quick start (human)

# 1. Install (zero runtime deps for the core; extras pulled per pipeline stage)
uv sync

# 2. Build a pack from the bundled ACCC Scamwatch example
make pack INPUTS=./examples/accc-scams

# 3. Verify the archive contract
uv run python packager.py verify out/scam-resilience-au.oapack.zip

Output: out/scam-resilience-au.oapack.zip — a portable, FTS5-searchable SQLite pack containing the compiled knowledge plus a SHA-256 sidecar.

Prerequisite for the demo pipeline

The OCR + agent-compile path uses local LLMs via Ollama. Configure as needed:

# OCR model (26B, vision-capable)
ollama create gemma4-26b-ocr -f /path/to/Modelfile.gemma4-26b-ocr

# Compiler model (E4B fine-tune, or any tool-capable model)
ollama list | grep offlineaid-compiler

Customize via Makefile variables: INPUTS, OCR_MODEL, COMPILER_MODEL, OLLAMA_BASE_URL, PACK_NAME. See Makefile for all knobs.

Quick start (agent)

Any agent that can shell out to a CLI can drive the pack-builder:

python3 packager.py init      --output pack.db --name "scam-resilience-au"
python3 packager.py add-layer --pack pack.db   --name scams --tier static_reference --file chunks.json
python3 packager.py build-index --pack pack.db
python3 packager.py archive   --pack pack.db   --output pack.oapack.zip

See SKILL.md for the full skill manifest, end-to-end agent workflow walkthrough, and pack-spec contract.

Testing

# Core library tests (zero deps)
uv run pytest -q tests/test_packager.py

# Full agent / OCR / scrape pipeline tests (requires extras)
uv run --extra agent --extra ocr --extra scrape pytest -q tests/

CI runs the core suite on Python 3.11, 3.12, and 3.13 — see .github/workflows/ci.yml.

What's in a pack

A .oapack.zip archive contains:

• One .db — SQLite database satisfying the pack contract (pack_metadata, chunks, fts_chunks; optional layers, geo_points, chunk_vectors).
• One manifest.json — versioned descriptor with archive format version, artifact type, builder version, and the canonical SHA-256 of the .db.
• One <db>.sha256 — sidecar for byte-level integrity verification.

The archive contract is enforced at build time by _validate_archive_contract in packager.py. See SKILL.md for the full pack spec.

Project layout

Path	What it is
packager.py	Single-file pure-stdlib pack builder + CLI (the contract)
SKILL.md	Skill manifest for agent runtime discovery
Makefile	End-to-end build pipeline (extract → compile → verify)
extract.py	Source-to-markdown extraction (OCR for PDFs via Gemma 4)
agent.py	Gemma 4 compile-loop (PydanticAI + Deep Agents)
scrape.py	Scrapy-based extractor for public-data sites
notebooks/	Kaggle T4 fine-tune notebooks (E2B + E4B)
eval/	Tier A holdout eval harness + Maestro device tests + perf data
examples/accc-scams/	Bundled ACCC Scamwatch PDFs for the demo pipeline
tests/	Pytest suite (core stdlib + optional pipeline tests)

Related artifacts

• OfflineAid (the consumer app) — Expo + LiteRT-LM Android client that loads .oapack.zip packs and queries them on-device with Gemma 4.
• expo-litert-lm — MIT-licensed Expo bridge module for LiteRT-LM.
• Datasets & models — published under helenk/gemma-4-* on Hugging Face and kaggle.com/datasets/helenkwok/offlineaid on Kaggle.

---

Built for the Kaggle Gemma 4 Good Hackathon, submitted May 2026 by Helen Kwok. Released under Apache 2.0.