{"_id":"@alextis59/athena","_rev":"7-91136b6d5ed598e1a64e59bf04265e65","name":"@alextis59/athena","dist-tags":{"latest":"1.5.0"},"versions":{"1.0.0":{"name":"@alextis59/athena","version":"1.0.0","keywords":["rag","documentation","search","sqlite","mcp","pdf"],"author":{"name":"Athena contributors"},"license":"ISC","_id":"@alextis59/athena@1.0.0","maintainers":[{"name":"alextis59","email":"alex.tis59@gmail.com"}],"homepage":"https://github.com/alextis59/athena#readme","bugs":{"url":"https://github.com/alextis59/athena/issues"},"bin":{"athena":"dist/cli/main.js"},"dist":{"shasum":"bfbc8a01d7a5e764d17824eb9605bed394cb3ae4","tarball":"https://registry.npmjs.org/@alextis59/athena/-/athena-1.0.0.tgz","fileCount":201,"integrity":"sha512-GFL81zbeIizN0poQzaoWE4r9RZ9Vh/ESh5bvIZfpsOGApDwla9WdqxHDXyBbwB4/tlcsVOMG2NH8ynsI34SGMA==","signatures":[{"sig":"MEUCIGb1WFt8fXO1sku0u/4YAMlJ6ltmyGekat51P0LIOjNWAiEAnyKU3lUPc3blYaQdKrPmuj2Agwm3V0073WJWKTBSrTY=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":636505},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=22.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"2409b855b40f8da699caede5a0a57ded9ec63db1","private":false,"scripts":{"eval":"tsx scripts/eval.ts validate --offline","lint":"eslint .","test":"node --import tsx --test \"test/**/*.test.ts\"","build":"tsc -p tsconfig.json","check":"npm run format:check && npm run lint && npm run typecheck && npm test","prepack":"npm run build","typecheck":"tsc -p tsconfig.test.json --noEmit","format:check":"prettier --check .","check:publish":"npm run check && npm run eval && npm run build","corpus:health":"tsx scripts/corpus.ts health --offline","prepublishOnly":"npm run check:publish","corpus:retrieve":"tsx scripts/corpus.ts retrieve"},"_npmUser":{"name":"alextis59","email":"alex.tis59@gmail.com"},"repository":{"url":"git+https://github.com/alextis59/athena.git","type":"git"},"_npmVersion":"11.5.2","description":"Local-first agentic documentation RAG command.","directories":{},"_nodeVersion":"22.19.0","dependencies":{"jiti":"^2.7.0","fast-glob":"^3.3.3","pdf-2-llm":"^1.1.0","better-sqlite3":"^12.11.1","@huggingface/transformers":"^4.2.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.23.0","eslint":"^10.6.0","prettier":"^3.9.4","@eslint/js":"^10.0.1","typescript":"^6.0.3","@types/node":"^26.1.0","typescript-eslint":"^8.62.1","@types/better-sqlite3":"^7.6.13"},"_npmOperationalInternal":{"tmp":"tmp/athena_1.0.0_1783243387655_0.5111081530690671","host":"s3://npm-registry-packages-npm-production"}},"1.1.0":{"name":"@alextis59/athena","version":"1.1.0","keywords":["rag","documentation","search","sqlite","mcp","pdf"],"author":{"name":"Athena contributors"},"license":"ISC","_id":"@alextis59/athena@1.1.0","maintainers":[{"name":"alextis59","email":"alex.tis59@gmail.com"}],"homepage":"https://github.com/alextis59/athena#readme","bugs":{"url":"https://github.com/alextis59/athena/issues"},"bin":{"athena":"dist/cli/main.js"},"dist":{"shasum":"16dc043302583586029b6fb0654898bbdc9f7971","tarball":"https://registry.npmjs.org/@alextis59/athena/-/athena-1.1.0.tgz","fileCount":206,"integrity":"sha512-sQ9BYPRNPmlPJf+1iKuXVkkKcCg+ZURtsWG8B7uaEGmeigAHoroEN+dJ0dUuPo1J7nL5Ug8oF4zyOjXZa1NDoQ==","signatures":[{"sig":"MEUCIQDC+ausHUa//liyENrxwIKsp3fYa3oJjtXFF95VCHFwNgIgO5uyMVUQTmwEJHagtHqQvAS8cfYhA6It9YzyvBcyGZw=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":663339},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=22.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"e510c11d913ddbc8a7960bc7c5021edbae1b3f18","private":false,"scripts":{"eval":"tsx scripts/eval.ts validate --offline","lint":"eslint .","test":"node --import tsx --test \"test/**/*.test.ts\"","build":"tsc -p tsconfig.json","check":"npm run format:check && npm run lint && npm run typecheck && npm test","prepack":"npm run build","typecheck":"tsc -p tsconfig.test.json --noEmit","format:check":"prettier --check .","check:publish":"npm run check && npm run eval && npm run build","corpus:health":"tsx scripts/corpus.ts health --offline","prepublishOnly":"npm run check:publish","corpus:retrieve":"tsx scripts/corpus.ts retrieve"},"_npmUser":{"name":"alextis59","email":"alex.tis59@gmail.com"},"repository":{"url":"git+https://github.com/alextis59/athena.git","type":"git"},"_npmVersion":"11.5.2","description":"Local-first agentic documentation RAG command.","directories":{},"_nodeVersion":"22.19.0","dependencies":{"jiti":"^2.7.0","fast-glob":"^3.3.3","pdf-2-llm":"^1.1.0","better-sqlite3":"^12.11.1","@huggingface/transformers":"^4.2.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.23.0","eslint":"^10.6.0","prettier":"^3.9.4","@eslint/js":"^10.0.1","typescript":"^6.0.3","@types/node":"^26.1.0","typescript-eslint":"^8.62.1","@types/better-sqlite3":"^7.6.13"},"_npmOperationalInternal":{"tmp":"tmp/athena_1.1.0_1783272435069_0.41820456361770364","host":"s3://npm-registry-packages-npm-production"}},"1.2.0":{"name":"@alextis59/athena","version":"1.2.0","keywords":["rag","documentation","search","sqlite","mcp","pdf"],"author":{"name":"Athena contributors"},"license":"ISC","_id":"@alextis59/athena@1.2.0","maintainers":[{"name":"alextis59","email":"alex.tis59@gmail.com"}],"homepage":"https://github.com/alextis59/athena#readme","bugs":{"url":"https://github.com/alextis59/athena/issues"},"bin":{"athena":"dist/cli/main.js"},"dist":{"shasum":"0a7c57ee4790baef02ea4280dd3c7595b62b4fcc","tarball":"https://registry.npmjs.org/@alextis59/athena/-/athena-1.2.0.tgz","fileCount":206,"integrity":"sha512-iHF2yggHPvWsbx+rIEYmabBzGI6s46PxlOWb7yn6caCwzLnKWA7tdGY/YI8QV0tfCCQmDIwrLYR2d0eHL8gApg==","signatures":[{"sig":"MEYCIQCDtFXMfOThdFOR9w2M5KYZSr1LSa+2m6rdDJ713/R4rgIhAOiW6EK2nhenLjW2owqPt2fcFNZsuYtOqNE4F1g1Ei+5","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":684990},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=22.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"e510c11d913ddbc8a7960bc7c5021edbae1b3f18","private":false,"scripts":{"eval":"tsx scripts/eval.ts validate --offline","lint":"eslint .","test":"node --import tsx --test \"test/**/*.test.ts\"","build":"tsc -p tsconfig.json","check":"npm run format:check && npm run lint && npm run typecheck && npm test","prepack":"npm run build","typecheck":"tsc -p tsconfig.test.json --noEmit","format:check":"prettier --check .","check:publish":"npm run check && npm run eval && npm run build","corpus:health":"tsx scripts/corpus.ts health --offline","prepublishOnly":"npm run check:publish","corpus:retrieve":"tsx scripts/corpus.ts retrieve"},"_npmUser":{"name":"alextis59","email":"alex.tis59@gmail.com"},"repository":{"url":"git+https://github.com/alextis59/athena.git","type":"git"},"_npmVersion":"11.5.2","description":"Local-first agentic documentation RAG command.","directories":{},"_nodeVersion":"22.19.0","dependencies":{"jiti":"^2.7.0","fast-glob":"^3.3.3","pdf-2-llm":"^1.1.0","better-sqlite3":"^12.11.1","@huggingface/transformers":"^4.2.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.23.0","eslint":"^10.6.0","prettier":"^3.9.4","@eslint/js":"^10.0.1","typescript":"^6.0.3","@types/node":"^26.1.0","typescript-eslint":"^8.62.1","@types/better-sqlite3":"^7.6.13"},"_npmOperationalInternal":{"tmp":"tmp/athena_1.2.0_1783448892785_0.8442492936000525","host":"s3://npm-registry-packages-npm-production"}},"1.3.0":{"name":"@alextis59/athena","version":"1.3.0","keywords":["rag","documentation","search","sqlite","mcp","pdf"],"author":{"name":"Athena contributors"},"license":"ISC","_id":"@alextis59/athena@1.3.0","maintainers":[{"name":"alextis59","email":"alex.tis59@gmail.com"}],"homepage":"https://github.com/alextis59/athena#readme","bugs":{"url":"https://github.com/alextis59/athena/issues"},"bin":{"athena":"dist/cli/main.js"},"dist":{"shasum":"13911f6dfaf3770279dd2fb8a2cec6046b94225c","tarball":"https://registry.npmjs.org/@alextis59/athena/-/athena-1.3.0.tgz","fileCount":195,"integrity":"sha512-x5aL5lz58Xut/upol2guCRd02G8dg75nu6Jym2+C6HQwIcL8+kszEHAKr7nXQU5tDelEsomBVzrtAfXwMY1K3w==","signatures":[{"sig":"MEQCIEC3GJ+o23+QSqoYS8VaF0lq0DNx3Ld5V/JiEBaKEyQ1AiAdsGCks4Pa2zjHZyQ5Fv4+u7N2p4f7gagiTrt5oC31mg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":546455},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=22.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"4051fcd37c6d8e01d9a2e883141c2e1fc4c14cd9","private":false,"scripts":{"eval":"tsx scripts/eval.ts validate --offline","lint":"eslint .","test":"node --import tsx --test \"test/**/*.test.ts\"","build":"tsc -p tsconfig.json","check":"npm run format:check && npm run lint && npm run typecheck && npm test","prepack":"npm run build","typecheck":"tsc -p tsconfig.test.json --noEmit","format:check":"prettier --check .","benchmark:pdf":"tsx scripts/pdf-benchmark.ts run","check:publish":"npm run check && npm run eval && npm run build","corpus:health":"tsx scripts/corpus.ts health --offline","prepublishOnly":"npm run check:publish","corpus:retrieve":"tsx scripts/corpus.ts retrieve","benchmark:pdf:plan":"tsx scripts/pdf-benchmark.ts plan"},"_npmUser":{"name":"alextis59","email":"alex.tis59@gmail.com"},"repository":{"url":"git+https://github.com/alextis59/athena.git","type":"git"},"_npmVersion":"11.5.2","description":"Local-first agentic documentation RAG command.","directories":{},"_nodeVersion":"22.19.0","dependencies":{"jiti":"^2.7.0","fast-glob":"^3.3.3","pdf-2-llm":"^1.2.0","better-sqlite3":"^12.11.1","@huggingface/transformers":"^4.2.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.23.0","eslint":"^10.6.0","prettier":"^3.9.4","@eslint/js":"^10.0.1","typescript":"^6.0.3","@types/node":"^26.1.0","typescript-eslint":"^8.62.1","@types/better-sqlite3":"^7.6.13"},"_npmOperationalInternal":{"tmp":"tmp/athena_1.3.0_1783575886914_0.6055732264312577","host":"s3://npm-registry-packages-npm-production"}},"1.3.1":{"name":"@alextis59/athena","version":"1.3.1","keywords":["rag","documentation","search","sqlite","mcp","pdf"],"author":{"name":"Athena contributors"},"license":"ISC","_id":"@alextis59/athena@1.3.1","maintainers":[{"name":"alextis59","email":"alex.tis59@gmail.com"}],"homepage":"https://github.com/alextis59/athena#readme","bugs":{"url":"https://github.com/alextis59/athena/issues"},"bin":{"athena":"dist/cli/main.js"},"dist":{"shasum":"edad0b0580e7f07a8dae557f268792d5f08f7ce2","tarball":"https://registry.npmjs.org/@alextis59/athena/-/athena-1.3.1.tgz","fileCount":195,"integrity":"sha512-lJIcW9whfPRTdckGy1RtHg8PXC9BQvtjpD/DGXo/2O3VBjEwEzM8fZYG4+LZzZeD+xPss+7qfQraCJAZu4dfCA==","signatures":[{"sig":"MEUCIHvBtFnxRD/uZB5yIILiSmp5iUS5iJYaDKX0pmXkE8reAiEAg3sIswgppIhb7ZGXrMKARk9vATc2XDVCXY9AuoJo4Ow=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":546455},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=22.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"4051fcd37c6d8e01d9a2e883141c2e1fc4c14cd9","private":false,"scripts":{"eval":"tsx scripts/eval.ts validate --offline","lint":"eslint .","test":"node --import tsx --test \"test/**/*.test.ts\"","build":"tsc -p tsconfig.json","check":"npm run format:check && npm run lint && npm run typecheck && npm test","prepack":"npm run build","typecheck":"tsc -p tsconfig.test.json --noEmit","format:check":"prettier --check .","benchmark:pdf":"tsx scripts/pdf-benchmark.ts run","check:publish":"npm run check && npm run eval && npm run build","corpus:health":"tsx scripts/corpus.ts health --offline","prepublishOnly":"npm run check:publish","corpus:retrieve":"tsx scripts/corpus.ts retrieve","benchmark:pdf:plan":"tsx scripts/pdf-benchmark.ts plan"},"_npmUser":{"name":"alextis59","email":"alex.tis59@gmail.com"},"repository":{"url":"git+https://github.com/alextis59/athena.git","type":"git"},"_npmVersion":"11.5.2","description":"Local-first agentic documentation RAG command.","directories":{},"_nodeVersion":"22.19.0","dependencies":{"jiti":"^2.7.0","fast-glob":"^3.3.3","pdf-2-llm":"^1.3.0","better-sqlite3":"^12.11.1","@huggingface/transformers":"^4.2.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.23.0","eslint":"^10.6.0","prettier":"^3.9.4","@eslint/js":"^10.0.1","typescript":"^6.0.3","@types/node":"^26.1.0","typescript-eslint":"^8.62.1","@types/better-sqlite3":"^7.6.13"},"_npmOperationalInternal":{"tmp":"tmp/athena_1.3.1_1783662079518_0.5175466415434367","host":"s3://npm-registry-packages-npm-production"}},"1.4.0":{"name":"@alextis59/athena","version":"1.4.0","keywords":["rag","documentation","search","sqlite","mcp","pdf"],"author":{"name":"Athena contributors"},"license":"ISC","_id":"@alextis59/athena@1.4.0","maintainers":[{"name":"alextis59","email":"alex.tis59@gmail.com"}],"homepage":"https://github.com/alextis59/athena#readme","bugs":{"url":"https://github.com/alextis59/athena/issues"},"bin":{"athena":"dist/cli/main.js"},"dist":{"shasum":"64d3670b2e0c3d4ec66ef89b95499fdc188b2561","tarball":"https://registry.npmjs.org/@alextis59/athena/-/athena-1.4.0.tgz","fileCount":211,"integrity":"sha512-IsLE6n8LKy+rJYxoEwRhrFgBTcfD2OmPWG/VofAbAwrt3L5GfeeLCC/ETjv429c9rI7rqN5Gu8Uy298Xt65yHw==","signatures":[{"sig":"MEUCIGJ8gSGTxeSN+Bo9K+hwgdcyAjtu3QhUUQNC3np9OEg0AiEA7m2Vx4TZEq6EmL6rWdmUIIJuy+uiyjmrdXCOe7eAH4w=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":690006},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=22.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"0954e62f2b8d2eadcfea01c17fdd468f077f336c","private":false,"scripts":{"eval":"tsx scripts/eval.ts validate --offline","lint":"eslint .","test":"node --import tsx --test \"test/**/*.test.ts\"","build":"tsc -p tsconfig.json","check":"npm run format:check && npm run lint && npm run typecheck && npm test","prepack":"npm run build","eval:plan":"tsx scripts/eval.ts plan --offline","typecheck":"tsc -p tsconfig.test.json --noEmit","format:check":"prettier --check .","benchmark:pdf":"tsx scripts/pdf-benchmark.ts run","check:publish":"npm run check && npm run eval && npm run build","corpus:health":"tsx scripts/corpus.ts health --offline","prepublishOnly":"npm run check:publish","corpus:retrieve":"tsx scripts/corpus.ts retrieve","benchmark:pdf:plan":"tsx scripts/pdf-benchmark.ts plan"},"_npmUser":{"name":"alextis59","email":"alex.tis59@gmail.com"},"repository":{"url":"git+https://github.com/alextis59/athena.git","type":"git"},"_npmVersion":"11.5.2","description":"Local-first agentic documentation RAG command.","directories":{},"_nodeVersion":"22.19.0","dependencies":{"jiti":"^2.7.0","fast-glob":"^3.3.3","pdf-2-llm":"1.3.0","better-sqlite3":"^12.11.1","@huggingface/transformers":"4.2.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.23.0","eslint":"^10.6.0","prettier":"^3.9.4","happy-dom":"^20.10.6","@eslint/js":"^10.0.1","typescript":"^6.0.3","@types/node":"^26.1.0","typescript-eslint":"^8.62.1","@types/better-sqlite3":"^7.6.13"},"_npmOperationalInternal":{"tmp":"tmp/athena_1.4.0_1783766581780_0.1878238589365011","host":"s3://npm-registry-packages-npm-production"}},"1.5.0":{"name":"@alextis59/athena","version":"1.5.0","description":"Local-first agentic documentation RAG command.","type":"module","private":false,"bin":{"athena":"dist/cli/main.js"},"keywords":["rag","documentation","search","sqlite","mcp","pdf"],"homepage":"https://github.com/alextis59/athena#readme","bugs":{"url":"https://github.com/alextis59/athena/issues"},"repository":{"type":"git","url":"git+https://github.com/alextis59/athena.git"},"license":"ISC","author":{"name":"Athena contributors"},"engines":{"node":">=22.0.0"},"publishConfig":{"access":"public"},"main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"scripts":{"build":"tsc -p tsconfig.json","check":"npm run format:check && npm run lint && npm run typecheck && npm test","check:publish":"npm run check && npm run eval && npm run build","benchmark:pdf":"tsx scripts/pdf-benchmark.ts run","benchmark:pdf:plan":"tsx scripts/pdf-benchmark.ts plan","corpus:health":"tsx scripts/corpus.ts health --offline","corpus:retrieve":"tsx scripts/corpus.ts retrieve","eval":"tsx scripts/eval.ts validate --offline","eval:plan":"tsx scripts/eval.ts plan --offline","format:check":"prettier --check .","lint":"eslint .","prepack":"npm run build","prepublishOnly":"npm run check:publish","test":"node --import tsx --test \"test/**/*.test.ts\"","typecheck":"tsc -p tsconfig.test.json --noEmit"},"devDependencies":{"@eslint/js":"^10.0.1","@types/better-sqlite3":"^7.6.13","@types/node":"^26.1.0","eslint":"^10.6.0","happy-dom":"^20.10.6","prettier":"^3.9.4","tsx":"^4.23.0","typescript":"^6.0.3","typescript-eslint":"^8.62.1"},"dependencies":{"@huggingface/transformers":"4.2.0","better-sqlite3":"^12.11.1","fast-glob":"^3.3.3","jiti":"^2.7.0","pdf-2-llm":"1.3.0"},"_id":"@alextis59/athena@1.5.0","gitHead":"ffde984556332f08547bf8ce3e0a64d419264699","_nodeVersion":"22.19.0","_npmVersion":"11.5.2","dist":{"integrity":"sha512-lqXT0aJBRQzcu4klVNeJjiwVTNlDag1pucaSV+BXsq5NZTSVeFKaHg2Un83oXa7h2/NRU8VKEAuTFngmRgrSdg==","shasum":"d33ff337f243d7a1dbb0428ce6accf4b41fd570b","tarball":"https://registry.npmjs.org/@alextis59/athena/-/athena-1.5.0.tgz","fileCount":219,"unpackedSize":760786,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIHbAQtyhREGd9tWQu2WoW6gfSJyN8g9lkw0WZrACOd5hAiACup4Wz1PP9mNIcgvzN0jmcwobcYDXfjTP5QdDWqXR7Q=="}]},"_npmUser":{"name":"alextis59","email":"alex.tis59@gmail.com"},"directories":{},"maintainers":[{"name":"alextis59","email":"alex.tis59@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/athena_1.5.0_1783772921033_0.32575019647397374"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-05T09:23:07.489Z","modified":"2026-07-11T12:28:41.296Z","1.0.0":"2026-07-05T09:23:07.807Z","1.1.0":"2026-07-05T17:27:15.226Z","1.2.0":"2026-07-07T18:28:12.987Z","1.3.0":"2026-07-09T05:44:47.039Z","1.3.1":"2026-07-10T05:41:19.670Z","1.4.0":"2026-07-11T10:43:01.941Z","1.5.0":"2026-07-11T12:28:41.177Z"},"bugs":{"url":"https://github.com/alextis59/athena/issues"},"author":{"name":"Athena contributors"},"license":"ISC","homepage":"https://github.com/alextis59/athena#readme","keywords":["rag","documentation","search","sqlite","mcp","pdf"],"repository":{"type":"git","url":"git+https://github.com/alextis59/athena.git"},"description":"Local-first agentic documentation RAG command.","maintainers":[{"name":"alextis59","email":"alex.tis59@gmail.com"}],"readme":"# Athena\n\nAthena is a local-first documentation RAG command for project folders. It\nindexes Markdown, MDX, text, RST, AsciiDoc, HTML, extensionless documentation,\nand PDFs into a local `.athena/index.sqlite` cache, then exposes search, source\nreading, cited terminal answers, a local web UI, and an optional read-only MCP\nbridge. Terminal and UI questions run through a fresh non-interactive OpenCode\nor Codex CLI process instead of calling a chat API directly.\n\nThe installed command is `athena`. The npm package is published as\n`@alextis59/athena` because the unscoped `athena` package name is already taken\non npm.\n\n## Install\n\n```bash\nnpm install -g @alextis59/athena\n```\n\nFor ad hoc use inside a documentation folder:\n\n```bash\nnpx @alextis59/athena\n```\n\nFor development from this checkout:\n\n```bash\nnpm install\nnpm run build\nnpm link\nathena --help\n```\n\n## Commands\n\n```bash\nathena                 # build or update the local index, then start the UI\nathena index           # build or update .athena/index.sqlite only\nathena serve           # serve an existing index\nathena serve --build   # build first, then serve\nathena ask \"...\"       # one-shot terminal answer with citations\nathena doctor          # inspect config, index, agent, parser, embedding, and port state\nathena mcp             # stdio MCP server for external coding agents\n```\n\nUnknown command names fail as usage errors before any command runs. `ask` is\nthe only command that accepts positional arguments and requires a non-empty\nquestion; every other command rejects unexpected positionals.\n\nWhen multiple project roots share one `--db`, `athena doctor` reports source,\ndocument, chunk, and parser-warning counts only for the selected `--root`.\n`athena serve` also verifies that the database has Athena's current schema and\nthat the latest index run for the selected root succeeded. If either check\nfails, rebuild with `athena index` or `athena serve --build`. The local UI's\n`/api/status` counts, latest run, and index indicator use that same selected-root\nscope rather than aggregating other roots in a shared database.\n\nCommon options:\n\n```bash\n--root <path>      Project root to inspect\n--config <path>    Explicit athena.config.ts, .mjs, or .json file\n--db <path>        SQLite index path\n--host <host>      Server bind host\n--port <port>      Server port, decimal digits 0-65535\n--session <id>     Conversation session for athena ask (default: cli)\n--agent-provider <opencode|codex>\n                   Non-interactive agent for answers and MCP\n--debug            Enable debug logs and write index traces to /tmp/athena-traces\n--json             Emit machine-readable output where supported\n```\n\n## Local-First Defaults\n\nAthena keeps private documentation local by default.\n\n- The runtime cache lives in `.athena/`.\n- Local Transformers.js model files are read from `.athena/models/`, the same\n  cache path reported by `athena doctor`.\n- The default embedding provider is local Transformers.js with\n  `mixedbread-ai/mxbai-embed-xsmall-v1`.\n- PDF ingestion uses the published `pdf-2-llm` package.\n- OpenCode is the default answer agent, but direct agent execution is blocked\n  until `agent.allowRemoteDocumentText` is explicitly enabled.\n- Athena launches agents read-only, injects only its retrieval MCP server,\n  carries conversation memory, and validates citations before releasing an\n  answer.\n- Remote embeddings and external agents require explicit configuration before\n  document text can leave the machine.\n\n## Configuration\n\nAthena discovers `athena.config.ts`, `athena.config.mjs`, or\n`athena.config.json` from the project root.\n\n```ts\nimport { defineConfig } from \"@alextis59/athena\";\n\nexport default defineConfig({\n  index: {\n    include: [\"**/*.md\", \"**/*.mdx\", \"**/*.pdf\", \"**/*.html\"],\n    exclude: [\"node_modules/**\", \"dist/**\", \".git/**\"]\n  },\n  embeddings: {\n    provider: \"transformers-js\",\n    model: \"mixedbread-ai/mxbai-embed-xsmall-v1\",\n    dimensions: 384,\n    pooling: \"mean\",\n    normalize: true,\n    timeoutMs: 30_000,\n    allowRemoteDocumentText: false\n  },\n  agent: {\n    provider: \"opencode\",\n    model: null,\n    timeoutMs: 300_000,\n    allowRemoteDocumentText: true\n  }\n});\n```\n\n`agent.allowRemoteDocumentText` defaults to `false`. Set it to `true` only when\nthe selected OpenCode or Codex configuration is allowed to receive indexed\ndocument text. Athena requires the opt-in for both agent CLIs because it cannot\nreliably determine whether an OpenCode model is local or remote. `agent.model`\nuses the selected CLI's model syntax and `null` preserves that CLI's default.\n\nInstall and authenticate at least one supported agent before asking questions:\n\n```bash\nopencode --version\ncodex --version\nathena doctor\n```\n\nThe historical `chat` configuration and model-provider exports remain for\nprogrammatic compatibility. The installed `athena ask` command and browser UI\ndo not use chat API adapters.\n\nConfiguration is strict: unknown top-level keys and section fields are rejected\nwith their exact field paths, so misspellings such as `server.prot` cannot\nsilently fall back to defaults.\n\nOptional embedding providers are `ollama`, `openai`, `voyage`, `cohere`, and\n`gemini`. Cloud providers require `allowRemoteDocumentText: true` and their API\nkey environment variable:\n\nSet `embeddings.provider` to `none` to disable vector retrieval. The next index\nrun removes persisted embeddings for that project root while retaining its\nlexical index and any other roots stored in a shared database.\n\n- `OPENAI_API_KEY`\n- `VOYAGE_API_KEY`\n- `COHERE_API_KEY`\n- `GEMINI_API_KEY`\n\nOllama uses the local `/api/embed` endpoint and honors `OLLAMA_HOST` when set.\nOllama and cloud embedding requests share the positive\n`embeddings.timeoutMs` deadline, which defaults to 30 seconds.\n\n## Answers And Web UI\n\n`athena ask` and the local UI launch one fresh `opencode run --format json` or\n`codex exec --json --ephemeral` process for each question. Athena injects a\ntemporary `athena_internal` MCP server into that invocation, restricts OpenCode\nto the injected read-only tools, and runs Codex in its read-only sandbox. No\nmanual MCP setup is required for this path.\n\nThe server loads the newest 20 accepted turns for the exact project root and\nsession. It gives each new agent process the prior questions and full answers in\nchronological order, without replaying intermediate tool traces. Other roots\nand sessions are never included. Schema version 4 stores the full accepted\nanswer beside its compact summary; existing summaries are backfilled during\nthe next `athena index` migration.\n\nSelect Codex for one terminal question or for the served UI with:\n\n```bash\nathena --agent-provider codex ask \"What are the benchmark results?\"\nathena serve --agent-provider codex\n```\n\nWhole-source text previews read at most 256 KiB and visibly report truncation.\nPDFs use the page- and region-aware `/api/pdf` preview contract; the generic\n`/api/source` endpoint rejects PDF bytes instead of decoding them as text.\n\nExternal turns use `agent.timeoutMs`, defaulting to five minutes. Cancelling a\nbrowser request or reaching the deadline terminates the subprocess group.\nAgent stdout is bounded, failure diagnostics retain only bounded tails, and\ncredential-bearing headers or environment assignments are redacted.\n\nThe `POST /api/agent/turn` stream uses newline-delimited JSON. Requests include a\nvalidated `sessionId`; the browser keeps its generated ID in `sessionStorage` so\nreloads in the same tab retain context without resending the transcript. Agent\ntext is buffered until final citation validation succeeds, so a rejected answer\nis never delivered as chat content.\n\n## Citations\n\nAnswers are required to cite retrieved source material. Athena validates\nMarkdown line ranges, PDF page and region metadata, source visibility during the\nturn, and out-of-range citations before accepting an answer.\n\n`athena ask` buffers model text and writes it to the terminal only after final\ncitation validation succeeds; rejected answers are not emitted on stdout. Calls\nuse the `cli` conversation by default. Pass `--session <id>` to keep independent\nterminal conversations in one project.\n\nPDF citations include page, region, confidence, and warning metadata when\navailable. Low-confidence PDF regions are surfaced as uncertain in the UI.\nPDF retrieval ranking uses the `pdf.minConfidenceForAutoCitation` value stored\nwith each indexed locator rather than a separate fixed threshold. Search and\nPDF APIs return that policy with the locator, and the UI displays and applies\nthe same threshold, falling back to the configured default only for legacy\nlocators. The configured threshold must be a finite number from `0` through `1`;\nexecutable configs using `NaN` or an infinity are rejected.\nPDF sidecar links are authorized by root-owned parser metadata: UTF-8 assets\nopen as text previews, while base64 binary assets are served as their decoded\nbytes with the recorded media type.\n\n## MCP Integration\n\nEvery direct answer gets an automatically injected MCP process. `athena mcp`\nalso remains available as a standalone read-only retrieval server for users who\nwant to configure Athena in another agent session manually:\n\n- `searchDocs`\n- `readSourceRange`\n- `readPdfSource`\n- `grepDocs`\n- `listDocs`\n- `relatedChunks`\n\n`readSourceRange` streams exact line ranges without loading the complete source.\nEach request is limited to 200 lines and 262,144 UTF-8 bytes; a larger range is\nrejected rather than silently truncated so returned locators remain exact.\n\nStdio requests use newline-delimited UTF-8 and are limited to 1,048,576 bytes\nper JSON-RPC message. An oversized line receives a parse error and is discarded\nthrough its next newline so later requests can continue.\n\nEach successful tool response includes only that call's retrieval trace, so\nlong-lived and batched MCP sessions do not resend earlier trace history.\n\nAgent, local-server, and MCP retrieval calls use the same schema-backed input\nvalidator and dispatcher. Missing or misspelled fields, unsupported extra\nproperties, invalid types, and out-of-range values fail before tool execution.\n\n`grepDocs` searches text-like source files only and keeps its 128-character\npattern cap. Regex mode additionally rejects unsafe constructs, caps input\nsizes, and runs matching in a worker with a one-second cumulative execution\ndeadline; exact-string mode is unchanged. Use `searchDocs` followed by\n`readPdfSource` for citation-backed PDF Markdown and page-region evidence.\n\nSee the\n[MCP integration guide](https://github.com/alextis59/athena/blob/main/docs/mcp-integration.md)\nfor standalone OpenCode, Codex, and generic MCP setup examples. OpenCode is the\ndefault answer agent; pass `--agent-provider codex` or set\n`agent.provider: \"codex\"` to select Codex.\n\n## Development\n\n```bash\nnpm run format:check\nnpm run lint\nnpm run typecheck\nnpm test\nnpm run build\nnpm run eval:plan\nnpm run eval\n```\n\n`npm run eval:plan` validates and prints manifest and ground-truth metadata only;\nit does not inspect materialized corpus files, create temporary indexes, or run\nevaluation suites. Add `-- --json` for the structured plan.\n\nThe offline evaluation validates the committed corpus manifest, ground-truth\nquestions, supported document types, hybrid retrieval behavior, PDF handling,\nand answer citation policy. Its corpus-wide suite executes every ground-truth\nquestion, checks expected fact evidence, opens and validates citation targets,\nand exercises negative unsupported behavior. It exits nonzero and prints\nper-suite diagnostics if any evaluated case, suite invariant, or recorded issue\nfails. Corpus health must pass before heavyweight work starts; the suites reuse\nthree compatible indexes with at most two evaluation workspaces active at once.\nCorpus manifest directories must remain relative to the repository, and\nentry paths must remain relative to their selected cache or synthetic directory;\nabsolute or parent-traversing values are rejected before any retrieval work.\nEach corpus download has one 60-second connection/body deadline, streams with\nthe manifest size as a hard ceiling, and replaces the cache entry only by\nrenaming a size- and checksum-verified sibling temp file. Evaluation preflights\nevery corpus source and temporary destination through the same containment\nresolver before copying any entry.\n\nThe development PDF benchmark likewise accepts only safe portable paper paths\nunder `papers/` and slug question IDs, then containment-checks generated\nworkspace, prompt, and answer destinations beneath its selected runtime root.\nPaper retrieval shares the corpus downloader's 60-second deadline, streamed\nmanifest-size ceiling, incremental SHA-256, and atomic verified-file install.\nCodex runs retain at most the latest 32 KiB from each output stream for\ndiagnostics, with the timeout or exit reason preserved at the start of errors.\nReference scoring reopens each cited path and page through Athena, accepts only\nquotes present in that page-bounded Markdown, and matches evidence terms only\ninside those source-backed quotes. Every expected paper needs an allowed-page\nreference, and `allReferencesSupportChoice` must be `true`.\n","readmeFilename":"README.md"}