{"_id":"@aspct3434/distill-agent","_rev":"6-9de71ad5225700e599a119579cfa3a38","name":"@aspct3434/distill-agent","dist-tags":{"latest":"0.2.5"},"versions":{"0.2.0":{"name":"@aspct3434/distill-agent","version":"0.2.0","keywords":["distill","agent","ai","autonomous-agents","llm","react-agent","mcp","skill-distillation","installer","cli"],"license":"MIT","_id":"@aspct3434/distill-agent@0.2.0","maintainers":[{"name":"aspct3434","email":"Kareem.i.souda@gmail.com"}],"homepage":"https://github.com/Aspct3434/agent-ai#readme","bugs":{"url":"https://github.com/Aspct3434/agent-ai/issues"},"bin":{"distill":"bin/distill.js"},"dist":{"shasum":"8f3c79a4afd84c33a53d146621b589e08046d3d1","tarball":"https://registry.npmjs.org/@aspct3434/distill-agent/-/distill-agent-0.2.0.tgz","fileCount":4,"integrity":"sha512-dFClvGBYNxtiE7+lqjvOrlXbuBtCkwZvW6GFZxnlxxd3aN9SpsA4Lslw9cNB4sL4DU1fF7EC3j4iwQOLG29kag==","signatures":[{"sig":"MEYCIQD+6HWxjpm4M0Mb6HDhRTWZ5xF3VLYmH9Lb4sgn2WX5dQIhAN7cbS2DUUSlQcVmu4+HYm6zUOqFzyjMXlXvHOxz4quT","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":69696},"engines":{"node":">=18"},"gitHead":"80e7eca679678ce760c9ae8a237a305f99b50394","scripts":{"test":"node tests/installer-cli.test.js","pack:dry-run":"npm pack --dry-run"},"_npmUser":{"name":"aspct3434","email":"Kareem.i.souda@gmail.com"},"repository":{"url":"git+https://github.com/Aspct3434/agent-ai.git","type":"git"},"_npmVersion":"10.9.2","description":"Distill — interactive installer and lifecycle CLI for the Distill autonomous agent framework.","directories":{},"_nodeVersion":"22.17.1","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/distill-agent_0.2.0_1779887226605_0.20693051975383936","host":"s3://npm-registry-packages-npm-production"}},"0.2.1":{"name":"@aspct3434/distill-agent","version":"0.2.1","keywords":["distill","agent","ai","autonomous-agents","llm","react-agent","mcp","skill-distillation","installer","cli"],"license":"MIT","_id":"@aspct3434/distill-agent@0.2.1","maintainers":[{"name":"aspct3434","email":"Kareem.i.souda@gmail.com"}],"homepage":"https://github.com/Aspct3434/agent-ai#readme","bugs":{"url":"https://github.com/Aspct3434/agent-ai/issues"},"bin":{"distill":"bin/distill.js"},"dist":{"shasum":"12ed9eefe9e8391e1eb3b0b202328bb81cf41629","tarball":"https://registry.npmjs.org/@aspct3434/distill-agent/-/distill-agent-0.2.1.tgz","fileCount":4,"integrity":"sha512-Pu/UkgG6VvP+SnThOqrZRX90BtwxyzH9iF7873B6VZaTvk/dx9a/4M78aCmAz/IL09jzNrm6TZ/V8wUhNYa0Vg==","signatures":[{"sig":"MEUCIQDy6uhEtg1YGYoarItFFqee1iG8eLRTuv7KtK7j1SVyowIgQ5YozYgZbSKvlwCHBx/8fvcrqyiuFK1HTrjoZeElFRg=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":72812},"engines":{"node":">=18"},"gitHead":"4da01fc43db09ec68907d3c333faa5f23cec126e","scripts":{"test":"node tests/installer-cli.test.js","pack:dry-run":"npm pack --dry-run"},"_npmUser":{"name":"aspct3434","email":"Kareem.i.souda@gmail.com"},"repository":{"url":"git+https://github.com/Aspct3434/agent-ai.git","type":"git"},"_npmVersion":"10.9.2","description":"Distill — interactive installer and lifecycle CLI for the Distill autonomous agent framework.","directories":{},"_nodeVersion":"22.17.1","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/distill-agent_0.2.1_1779892158076_0.370765082920949","host":"s3://npm-registry-packages-npm-production"}},"0.2.2":{"name":"@aspct3434/distill-agent","version":"0.2.2","keywords":["distill","agent","ai","autonomous-agents","llm","react-agent","mcp","skill-distillation","installer","cli"],"license":"MIT","_id":"@aspct3434/distill-agent@0.2.2","maintainers":[{"name":"aspct3434","email":"Kareem.i.souda@gmail.com"}],"homepage":"https://github.com/Aspct3434/agent-ai#readme","bugs":{"url":"https://github.com/Aspct3434/agent-ai/issues"},"bin":{"distill":"bin/distill.js"},"dist":{"shasum":"ba3fb2bebccdff80962cc05d600c7cb56ee7db3e","tarball":"https://registry.npmjs.org/@aspct3434/distill-agent/-/distill-agent-0.2.2.tgz","fileCount":4,"integrity":"sha512-yquANlWFfdie5KcENItmC7rRqzHDvf5Cf8rRjbE47ott3MH9H8MGPxlwzHVGzgrjtj0asROyGbgchrGU+3vhJQ==","signatures":[{"sig":"MEUCICzLLZlHWDrK0J/KRqq5oLhtmih8eK6krchHF/wVUlWRAiEAjXK8S+llcxjGBCTO+S5ZVMeUdnB/CL2hTN3beoi1g3Q=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":77989},"engines":{"node":">=18"},"gitHead":"9e28feb43ccfb2338e37bef8150e96465e2fd4d2","scripts":{"test":"node tests/installer-cli.test.js","pack:dry-run":"npm pack --dry-run"},"_npmUser":{"name":"aspct3434","email":"Kareem.i.souda@gmail.com"},"repository":{"url":"git+https://github.com/Aspct3434/agent-ai.git","type":"git"},"_npmVersion":"10.9.2","description":"Distill — interactive installer and lifecycle CLI for the Distill autonomous agent framework.","directories":{},"_nodeVersion":"22.17.1","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/distill-agent_0.2.2_1780065195899_0.8093159923173137","host":"s3://npm-registry-packages-npm-production"}},"0.2.3":{"name":"@aspct3434/distill-agent","version":"0.2.3","keywords":["distill","agent","ai","autonomous-agents","llm","react-agent","mcp","skill-distillation","installer","cli"],"license":"MIT","_id":"@aspct3434/distill-agent@0.2.3","maintainers":[{"name":"aspct3434","email":"Kareem.i.souda@gmail.com"}],"homepage":"https://github.com/Aspct3434/agent-ai#readme","bugs":{"url":"https://github.com/Aspct3434/agent-ai/issues"},"bin":{"distill":"bin/distill.js"},"dist":{"shasum":"76c98d2a540ad936b9d9a86be0885ccce3ddab27","tarball":"https://registry.npmjs.org/@aspct3434/distill-agent/-/distill-agent-0.2.3.tgz","fileCount":4,"integrity":"sha512-viF9sjUPs+E3OsET/8HyWyhfUukZH2TPUVA1+otjuvXDb+/9HQ9C8VdjlD3n/AW4y9JaxWi2VUQ0mVcwv0vBOw==","signatures":[{"sig":"MEUCIET4WLaCsLiDap2PB+1+KSVrHt2uC+7FzX6CZVD64aO7AiEAmLblAn2vV/AIFjOjovilNkSXTiWaEhps8psLgXvpt+8=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":80890},"engines":{"node":">=18"},"gitHead":"a1d43ae0e8c88bb24e44f20632668eb372839c6a","scripts":{"test":"node tests/installer-cli.test.js","pack:dry-run":"npm pack --dry-run"},"_npmUser":{"name":"aspct3434","email":"Kareem.i.souda@gmail.com"},"repository":{"url":"git+https://github.com/Aspct3434/agent-ai.git","type":"git"},"_npmVersion":"10.9.2","description":"Distill — interactive installer and lifecycle CLI for the Distill autonomous agent framework.","directories":{},"_nodeVersion":"22.17.1","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/distill-agent_0.2.3_1780068127994_0.5449633423774289","host":"s3://npm-registry-packages-npm-production"}},"0.2.4":{"name":"@aspct3434/distill-agent","version":"0.2.4","keywords":["distill","agent","ai","autonomous-agents","llm","react-agent","mcp","skill-distillation","installer","cli"],"license":"MIT","_id":"@aspct3434/distill-agent@0.2.4","maintainers":[{"name":"aspct3434","email":"Kareem.i.souda@gmail.com"}],"homepage":"https://github.com/Aspct3434/agent-ai#readme","bugs":{"url":"https://github.com/Aspct3434/agent-ai/issues"},"bin":{"distill":"bin/distill.js"},"dist":{"shasum":"a69ae4bacea06418c88231cbb86d31b99521b80d","tarball":"https://registry.npmjs.org/@aspct3434/distill-agent/-/distill-agent-0.2.4.tgz","fileCount":4,"integrity":"sha512-5ajZ+53ADX3Y63GUN/AdaaqsI/nxt2FGNAv0uErwV551M5JGmaCKilmlsrPHxf6bzf4hH3lil7G9oBDotWr01A==","signatures":[{"sig":"MEYCIQCmJ02sKGtrIp7Ehle8ae069msWFNbXeH7UeMX4D80UYgIhAKiTBWlSWCsbIjk+J8IyuCwFhdPywqlrbXpVw81XT38H","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":84710},"engines":{"node":">=18"},"gitHead":"aba6e701ca706c1688083fc3ae52ced8b4a643ad","scripts":{"test":"node tests/installer-cli.test.js","pack:dry-run":"npm pack --dry-run"},"_npmUser":{"name":"aspct3434","email":"Kareem.i.souda@gmail.com"},"repository":{"url":"git+https://github.com/Aspct3434/agent-ai.git","type":"git"},"_npmVersion":"10.9.2","description":"Distill — interactive installer and lifecycle CLI for the Distill autonomous agent framework.","directories":{},"_nodeVersion":"22.17.1","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/distill-agent_0.2.4_1780087288983_0.37345127210439144","host":"s3://npm-registry-packages-npm-production"}},"0.2.5":{"name":"@aspct3434/distill-agent","version":"0.2.5","description":"Distill — interactive installer and lifecycle CLI for the Distill autonomous agent framework.","bin":{"distill":"bin/distill.js"},"scripts":{"test":"node tests/installer-cli.test.js","pack:dry-run":"npm pack --dry-run"},"keywords":["distill","agent","ai","autonomous-agents","llm","react-agent","mcp","skill-distillation","installer","cli"],"repository":{"type":"git","url":"git+https://github.com/Aspct3434/agent-ai.git"},"engines":{"node":">=18"},"license":"MIT","publishConfig":{"access":"public"},"_id":"@aspct3434/distill-agent@0.2.5","gitHead":"fdeb0c0d52639ecd3dfdfcdad1be0962e31daa06","bugs":{"url":"https://github.com/Aspct3434/agent-ai/issues"},"homepage":"https://github.com/Aspct3434/agent-ai#readme","_nodeVersion":"22.17.1","_npmVersion":"10.9.2","dist":{"integrity":"sha512-o5l24XT2UgjS3NvN21PFIgPCOF2KmJqUe339YM4h0U5txgOlRVqsn/8KNJQHiqpU4UUkK5pg/P/llvGNvvdb9g==","shasum":"247845a38811e887e7be9688d82ec05a8b295a03","tarball":"https://registry.npmjs.org/@aspct3434/distill-agent/-/distill-agent-0.2.5.tgz","fileCount":4,"unpackedSize":85602,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCZibdALCR/7JBTDl5RdNZysc18zCjibgIZXqVs5Rln8wIgTEX2REoMgE+a3Eq5G4f2otRu0i3knHGTIM1bkeIQEEE="}]},"_npmUser":{"name":"aspct3434","email":"Kareem.i.souda@gmail.com"},"directories":{},"maintainers":[{"name":"aspct3434","email":"Kareem.i.souda@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/distill-agent_0.2.5_1780163561573_0.1259382874510342"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-27T13:07:06.445Z","modified":"2026-05-30T17:52:41.839Z","0.2.0":"2026-05-27T13:07:06.752Z","0.2.1":"2026-05-27T14:29:18.268Z","0.2.2":"2026-05-29T14:33:16.041Z","0.2.3":"2026-05-29T15:22:08.186Z","0.2.4":"2026-05-29T20:41:29.117Z","0.2.5":"2026-05-30T17:52:41.746Z"},"bugs":{"url":"https://github.com/Aspct3434/agent-ai/issues"},"license":"MIT","homepage":"https://github.com/Aspct3434/agent-ai#readme","keywords":["distill","agent","ai","autonomous-agents","llm","react-agent","mcp","skill-distillation","installer","cli"],"repository":{"type":"git","url":"git+https://github.com/Aspct3434/agent-ai.git"},"description":"Distill — interactive installer and lifecycle CLI for the Distill autonomous agent framework.","maintainers":[{"name":"aspct3434","email":"Kareem.i.souda@gmail.com"}],"readme":"

\r\n \"Colored\r\n

\r\n\r\nA production-grade ReAct agent built for reliability. Features **task-contract execution** to prevent hallucination, **skill distillation** to evolve its own tools, **hybrid memory**, and a real-time streaming control panel.\r\n\r\n### Distill TUI\r\n\r\nLaunch the interactive terminal interface with:\r\n\r\n```bash\r\ndistill\r\n# or\r\ndistill tui\r\n```\r\n\r\n![Distill TUI command demo](docs/assets/distill-tui.gif)\r\n\r\n## Architecture\r\n\r\n```mermaid\r\ngraph TD\r\n %% External Interfaces\r\n UI[Control Panel UI
React + Tailwind]\r\n Adapters[Messaging Adapters
Telegram, Discord, Slack, Email]\r\n TUI[Terminal UI]\r\n\r\n %% Gateway & Concurrency\r\n subgraph Gateway Layer\r\n API[FastAPI Gateway]\r\n WS[WebSocket Stream]\r\n Queue[Session FIFO Queue]\r\n \r\n API --- WS\r\n WS --> Queue\r\n end\r\n\r\n UI --> API\r\n Adapters --> API\r\n TUI --> WS\r\n\r\n %% Core Agent Engine\r\n subgraph Core Agent Engine\r\n Agent[Agent Engine
ReAct Loop]\r\n Contract[Task Contract System
Evidence Gating]\r\n Plan[Plan Management
Action Ledger]\r\n Eval[Skill Distiller
Evaluator]\r\n \r\n Agent <--> Contract\r\n Agent <--> Plan\r\n Agent --> Eval\r\n end\r\n\r\n Queue --> Agent\r\n\r\n %% State & Memory\r\n subgraph State & Memory\r\n Checkpoint[(SQLite Checkpointer
State & History)]\r\n Chroma[(ChromaDB
Semantic Memory)]\r\n Neo4j[(Neo4j
Graph Memory)]\r\n \r\n Agent <--> Checkpoint\r\n Agent <--> Chroma\r\n Agent <--> Neo4j\r\n end\r\n\r\n %% External Services\r\n LLM((LLM Provider
LiteLLM))\r\n Agent <--> LLM\r\n\r\n %% Tooling & Execution\r\n subgraph Tooling & Execution Sandbox\r\n Tools[Tool Manager]\r\n MCP[MCP Servers]\r\n Sandbox[Terminal Sandbox
Docker / Host / Serverless]\r\n Skills[Evolved Skills
Auto-Maker]\r\n \r\n Agent --> Tools\r\n Tools --> MCP\r\n Tools --> Sandbox\r\n Tools --> Skills\r\n Eval -.->|Synthesizes & Validates| Skills\r\n end\r\n```\r\n\r\n### Directory Structure\r\n\r\n```text\r\nsrc/\r\n agent.py -- ReAct loop, session management, checkpointing\r\n contract.py -- Task-contract system (evidence tracking)\r\n evaluator.py -- Skill distiller: trajectory -> reusable MCP skill\r\n memory.py -- HybridMemory: ChromaDB (semantic) + Neo4j (graph)\r\n gateway.py -- FastAPI app, WebSocket stream, session-per-FIFO-lane\r\n tools.py -- MCP servers, terminal, file, process, port tools\r\ncontrol-panel/ -- React + Tailwind chat UI with live token streaming\r\n```\r\n\r\n## 🌟 Key Features\r\n\r\n* **Task-Contract Execution**: The agent must declare the required execution evidence (files created, services running) before starting a task. The final response is gated on this physical evidence, eliminating \"I'll do it now\" hallucinations.\r\n* **Skill Distillation**: After a successful complex task, an LLM evaluates the trajectory and synthesizes a parameterized Python tool. New skills are versioned, validated, and automatically rolled back if their success rate drops.\r\n* **Session-per-FIFO-Lane Concurrency**: Every user session gets a dedicated queue and worker task, allowing high concurrency with strict message ordering.\r\n* **Hybrid Memory**: Combines SQLite full-text search, ChromaDB semantic embeddings, and Neo4j graph relationships to recall cross-session context.\r\n* **Universal Sandboxing**: Run shell operations locally, in Docker, or via serverless platforms (Daytona, E2B, Modal).\r\n* **Shareable Skills**: Export and import distilled skills via the open `SKILL.md` format.\r\n\r\n## 🚀 Quick Start\r\n\r\nThe fastest way to run Distill locally is using Docker Compose:\r\n\r\n```bash\r\n# 1. Copy the environment template\r\ncp an-api.env.example an-api.env\r\n\r\n# 2. Add your LLM API Key to an-api.env (e.g., MOONSHOT_API_KEY or OPENAI_API_KEY)\r\n# By default, Distill uses LiteLLM and supports OpenAI, Anthropic, Gemini, Ollama, etc.\r\n\r\n# 3. Start the application\r\ndocker compose up -d --build\r\n```\r\n\r\n* **Control Panel (UI)**: `http://localhost:5173`\r\n* **API / Docs**: `http://localhost:8000/docs`\r\n\r\n### CLI Installation\r\n\r\n#### Empty machine (no Node, no Python)?\r\n\r\nThe bootstrap scripts install the prerequisites for you, then hand off to the\r\ninteractive installer. They are the recommended path on a fresh PC.\r\n\r\n**Windows (PowerShell):**\r\n```powershell\r\nirm https://raw.githubusercontent.com/Aspct3434/agent-ai/master/scripts/bootstrap.ps1 | iex\r\n```\r\n\r\n**macOS / Linux (bash):**\r\n```bash\r\ncurl -fsSL https://raw.githubusercontent.com/Aspct3434/agent-ai/master/scripts/bootstrap.sh | bash\r\n```\r\n\r\nYou can also clone the repo first and run `scripts/bootstrap.ps1` (Windows) or\r\n`scripts/bootstrap.sh` (macOS/Linux) directly.\r\n\r\n#### Already have Node?\r\n\r\nRun the interactive installer with `npx` (no global install required):\r\n\r\n```powershell\r\nnpx @aspct3434/distill-agent install\r\n```\r\n\r\nPrefer pinning to the exact GitHub revision? Use the repo form:\r\n\r\n```bash\r\nnpx --yes github:Aspct3434/agent-ai install\r\n```\r\n\r\nAfter installation, use the CLI to manage the agent:\r\n```bash\r\nnpm i -g @aspct3434/distill-agent\r\ndistill # Open the interactive terminal UI\r\ndistill start # Start the backend and control panel\r\ndistill logs # View running logs\r\ndistill update # Pull the latest changes\r\ndistill doctor # Diagnose the install and environment\r\n\r\n# npx works too if you prefer not to install globally:\r\nnpx @aspct3434/distill-agent start # Start the backend and control panel\r\nnpx @aspct3434/distill-agent logs # View running logs\r\nnpx @aspct3434/distill-agent update # Pull the latest changes\r\nnpx @aspct3434/distill-agent doctor # Diagnose the install and environment\r\n```\r\n\r\n## ⚙️ Configuration\r\n\r\nDistill is highly configurable via environment variables. Key settings in `an-api.env`:\r\n\r\n| Variable | Default | Description |\r\n|---|---|---|\r\n| `AGENT_MODEL` | `moonshot/kimi-k2.5` | The primary LLM to use (supports any LiteLLM provider string). |\r\n| `AGENT_SANDBOX` | (blank) | Leave blank for Docker Compose. Set to `docker` to run Docker-in-Docker, or `http` for serverless. |\r\n| `AGENT_REQUIRE_APPROVAL`| `off` | Set to `risky` or `all` to require human-in-the-loop approval before executing shell commands. |\r\n| `AGENT_API_TOKEN` | required | Bearer token for API/WebSocket access; agent endpoints return 503 until set. |\r\n| `AGENT_ALLOW_INSECURE_NO_AUTH` | `false` | Explicit local-only override for running without API auth. |\r\n| `GATEWAY_RATE_LIMIT_RPM` | `60` | Per-client request limit, keyed by API token or client IP. |\r\n| `AGENT_LOG_DB_PATH` | `./data/gateway_logs.db` | Persistent SQLite log store used by `/api/logs`. |\r\n\r\n## 🔌 Integrations & Adapters\r\n\r\nDistill can operate directly in your favorite platforms. Adapters are disabled by default and activate when you provide a bot token in `an-api.env`:\r\n* **Telegram**: Set `TELEGRAM_BOT_TOKEN`. Supports voice note transcriptions via Whisper.\r\n* **Discord**: Set `DISCORD_BOT_TOKEN`.\r\n* **Slack**: Set `SLACK_BOT_TOKEN` & `SLACK_APP_TOKEN` (Socket Mode).\r\n* **Email**: Set `EMAIL_ADDRESS`, `EMAIL_PASSWORD`, `EMAIL_IMAP_HOST`, `EMAIL_SMTP_HOST`.\r\n\r\nEach channel provides a live typing indicator, streams real-time tool execution logs, and isolates conversations.\r\n\r\n## 🧪 Testing\r\n\r\nDistill maintains a robust test suite covering contracts, planners, adapters, and the ReAct loop:\r\n\r\n```bash\r\npytest # Run the full suite\r\npytest tests/test_task_contract_loop.py -v # Test the anti-hallucination contract system\r\n```\r\n","readmeFilename":"README.md"}