{"_id":"@aittalam/pi-llamafile","name":"@aittalam/pi-llamafile","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@aittalam/pi-llamafile","version":"1.0.0","description":"Pi extension that supervises local llamafile-served model processes — start, stop, adopt, with progress visible on quit","license":"MIT","author":{"name":"Davide Eynard","email":"davide@mozilla.ai"},"type":"module","main":"index.ts","homepage":"https://github.com/aittalam/pi-llamafile#readme","repository":{"type":"git","url":"git+https://github.com/aittalam/pi-llamafile.git"},"bugs":{"url":"https://github.com/aittalam/pi-llamafile/issues"},"keywords":["pi-package","pi-extension","llamafile","llm","local-llm","openai-compatible"],"pi":{"extensions":["./index.ts"]},"scripts":{"dev":"pi -e .","test":"vitest run","test:unit":"vitest run tests/unit","test:integration":"vitest run tests/integration","test:watch":"vitest"},"peerDependencies":{"@earendil-works/pi-coding-agent":"*"},"devDependencies":{"@earendil-works/pi-coding-agent":">=0.75.0","@types/node":"^20.0.0","tsx":"^4.22.3","typescript":"^5.4.0","vitest":"^1.6.1"},"gitHead":"f0d3ecf4e8c3dd79caa6b07ee0623d391412b1bd","_id":"@aittalam/pi-llamafile@1.0.0","_nodeVersion":"26.0.0","_npmVersion":"11.12.1","dist":{"integrity":"sha512-SYvs1JB0Vg8jcLEoaVGlyYKizScGAp/AHn7mwT1pdfkx7RSAYyQegLDhoDzAawpoq0Vyh2KxYCuzX39X73QkWg==","shasum":"324d9d74eddfeb80334241e72ef31d06acce5946","tarball":"https://registry.npmjs.org/@aittalam/pi-llamafile/-/pi-llamafile-1.0.0.tgz","fileCount":12,"unpackedSize":77970,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIH6ZayxscGGby9aQWwSluiMl+uClgL8EhwjhD4JZreB9AiAFclZc6nk9T/oqGInZ3aeaux9JGyxy610B0IQZaR/kLQ=="}]},"_npmUser":{"name":"aittalam","email":"davide.eynard@gmail.com"},"directories":{},"maintainers":[{"name":"aittalam","email":"davide.eynard@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/pi-llamafile_1.0.0_1779383337551_0.8357194359769229"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-21T17:08:57.418Z","1.0.0":"2026-05-21T17:08:57.724Z","modified":"2026-05-21T17:08:57.889Z"},"maintainers":[{"name":"aittalam","email":"davide.eynard@gmail.com"}],"description":"Pi extension that supervises local llamafile-served model processes — start, stop, adopt, with progress visible on quit","homepage":"https://github.com/aittalam/pi-llamafile#readme","keywords":["pi-package","pi-extension","llamafile","llm","local-llm","openai-compatible"],"repository":{"type":"git","url":"git+https://github.com/aittalam/pi-llamafile.git"},"author":{"name":"Davide Eynard","email":"davide@mozilla.ai"},"bugs":{"url":"https://github.com/aittalam/pi-llamafile/issues"},"license":"MIT","readme":"# Llamafiles provider extension for pi\n\nA pi extension that supervises locally-run llamafile-style model servers\n(or any OpenAI-compatible server you can launch from a binary). It\nregisters a `llamafiles` provider with pi, starts the configured binary\nwhen you pick one of its models, and stops it when you switch away or\nquit.\n\n## Status\n\nImplementation complete; covered by 55 automated tests (42 unit + 13\nintegration via the SDK driver). `npm test` runs in ~15s and exits 0.\n\nSee [`SPECS.md`](SPECS.md) for the behavioral contract, [`PLAN.md`](PLAN.md)\nfor the implementation plan, and [`NOTES.md`](NOTES.md) for the pi API\nfindings that informed the design.\n\n## Features\n\n- **Process supervision** — starts the configured binary on `/model`,\n  waits for `/v1/models` to respond, then reports ready. One process per\n  pi session.\n- **Per-model port** — each model declares its own `port`; pi sends\n  requests there. Default `8080`.\n- **`{{port}}` substitution in `args`** — `port` is the single source of\n  truth; reference it in your binary's arg list as `{{port}}`.\n- **Adoption** — if a compatible server is already running on the port,\n  pi adopts it instead of spawning a duplicate.\n- **Foreign-port safety** — if a different server holds the port, pi\n  surfaces the conflict and tells you to free it manually. It never kills\n  processes it did not start.\n- **Visible quit progress** — when you exit pi while it owns a running\n  process, the extension prints \"Stopping llamafile ...\" and\n  \"Stopped llamafile ...\" to stderr so the user can see the wait.\n- **Transparent reload** — `/reload` does **not** prompt; the process\n  keeps running and the freshly loaded extension instance re-adopts it.\n- **Cleanup-by-design** — adopted processes are never stopped without\n  your consent.\n\n## Installation\n\nThree options, in order of recommendation:\n\n**From npm** (most convenient, gets gallery indexing):\n\n```bash\npi install npm:@aittalam/pi-llamafile\n```\n\n**From git** (pins to a tag, no npm account needed by you or by pi):\n\n```bash\npi install git:github.com/aittalam/pi-llamafile@v1.0.0\n```\n\n**From source** (for hacking on the extension):\n\n```bash\ngit clone https://github.com/aittalam/pi-llamafile ~/.pi/agent/extensions/pi-llamafile\ncd ~/.pi/agent/extensions/pi-llamafile\nnpm install\n```\n\nIn all cases, use `/reload` from a running pi session, or restart pi, to pick\nup changes.\n\n## Configuration\n\nDefine your llamafile models in `~/.pi/agent/models.json` under the\n`llamafiles` provider:\n\n```jsonc\n{\n  \"providers\": {\n    \"llamafiles\": {\n      \"models\": [\n        {\n          \"id\": \"qwen3-9b\",\n          \"name\": \"Qwen3 9B\",\n          \"command\": \"sh\",\n          \"args\": [\n            \"/path/to/qwen3-9b.llamafile\",\n            \"--server\",\n            \"--port\",\n            \"{{port}}\",\n            \"--jinja\"\n          ],\n          \"port\": 8080,\n          \"reasoning\": false,\n          \"input\": [\"text\"],\n          \"contextWindow\": 32768,\n          \"maxTokens\": 4096\n        }\n      ]\n    }\n  }\n}\n```\n\nOptional per-model fields beyond pi's standard set:\n\n| Field     | Description                                          |\n|-----------|------------------------------------------------------|\n| `command` | Executable to spawn. Required.                        |\n| `args`    | Argument list. `{{port}}` is substituted at spawn.    |\n| `port`    | TCP port the server listens on. Default `8080`.       |\n| `env`     | Extra environment variables for the spawned process.  |\n| `cwd`     | Working directory for the spawned process.            |\n\nSee [`SPECS.md` §3.2](SPECS.md) for the complete schema and defaults.\n\n## Usage\n\n1. `pi --list-models` should show your llamafile models under\n   the `llamafiles` provider.\n2. Use `/model` to pick one. The extension spawns the binary, waits\n   for readiness, and reports `<name> is ready`.\n3. Switch with `/model` again. The current process is stopped and the\n   new one started.\n4. Switch to any non-llamafile model: the running llamafile is stopped.\n5. `/quit` (or `Ctrl+D`): the running llamafile is stopped. Two lines\n   appear on the terminal (stderr): `Stopping llamafile \"<name>\" ...`\n   then `Stopped llamafile \"<name>\".` Adopted servers (started outside\n   pi) are left running silently.\n6. `/llamafiles`: prints the current state.\n\n## Development\n\n```bash\nnpm install        # install dev deps\nnpm test           # 56 tests, unit + integration\nnpm run test:unit  # 45 unit tests, sub-second\nnpm run dev        # pi -e . — smoke-load against your real HOME\n```\n\nLogs from spawned binaries are appended to `~/.pi/llamafile_logs/<modelId>.log`.\n\n## Layout\n\n```\nSPECS.md          # behavioral contract (single source of truth)\nPLAN.md           # implementation plan\nNOTES.md          # pi API findings\nindex.ts          # thin wiring: events, commands\nsrc/\n  config.ts       # models.json loader\n  template.ts     # {{port}} substitution\n  process.ts      # LlamafileSupervisor\n  log.ts          # file log streams\n  notify.ts       # notification text\n  types.ts        # shared types\ntests/\n  unit/           # 3 files, 42 tests\n  integration/    # 13 files, all SDK-driven\n  helpers/        # fake-server, harness, port allocator\n  MANUAL.md       # checklist for things automation cannot reach\n```\n\n## License\n\nMIT.\n","readmeFilename":"README.md","_rev":"1-83cbaccbd860cd89613657c992cc8f75"}