{"_id":"@aspct/distill-agent","_rev":"2-53cd15f572553e7145e5ef3c97c74cc1","name":"@aspct/distill-agent","dist-tags":{"latest":"0.2.7"},"versions":{"0.2.6":{"name":"@aspct/distill-agent","version":"0.2.6","keywords":["distill","agent","ai","autonomous-agents","llm","react-agent","mcp","skill-distillation","installer","cli"],"license":"MIT","_id":"@aspct/distill-agent@0.2.6","maintainers":[{"name":"aspct","email":"Karim.ouda@hotmail.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":"7f550d3d7521366cfb1f452f2b46c0e730f102a9","tarball":"https://registry.npmjs.org/@aspct/distill-agent/-/distill-agent-0.2.6.tgz","fileCount":4,"integrity":"sha512-PHUoCswyD914s07iyhSknHt9EMCQidjmxvGehZ1Mm8chh+G4wwgZ2D0v9UjRpiee43G2UdvGu461kQpmSw9njw==","signatures":[{"sig":"MEUCIQCrrn2qMkXLok3e233leTJBfsWU1ZQzcFWmHLZVni6FEwIgBvAFaaOlJx7m7CQA15vtoznGKfzmDPmb66yFCUy8f2k=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":87190},"engines":{"node":">=18"},"gitHead":"ed29076c7bfdc131f68de83506f7fceb99981830","scripts":{"test":"node tests/installer-cli.test.js","pack:dry-run":"npm pack --dry-run"},"_npmUser":{"name":"aspct","email":"Karim.ouda@hotmail.com"},"repository":{"url":"git+https://github.com/Aspct3434/agent-ai.git","type":"git"},"_npmVersion":"11.13.0","description":"Distill — interactive installer and lifecycle CLI for the Distill autonomous agent framework.","directories":{},"_nodeVersion":"26.2.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/distill-agent_0.2.6_1780313349611_0.8388755707233697","host":"s3://npm-registry-packages-npm-production"}},"0.2.7":{"name":"@aspct/distill-agent","version":"0.2.7","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/Distill-Agent.git"},"engines":{"node":">=18"},"license":"MIT","publishConfig":{"access":"public"},"gitHead":"b92e83e247c546b4acfab168a240deff278d9193","_id":"@aspct/distill-agent@0.2.7","bugs":{"url":"https://github.com/Aspct3434/Distill-Agent/issues"},"homepage":"https://github.com/Aspct3434/Distill-Agent#readme","_nodeVersion":"26.2.0","_npmVersion":"11.13.0","dist":{"integrity":"sha512-wG7QYubBZ2HWFDNVvz/aZfXksIM8iG2HFf2+C5I4OeWRUJ5RXKz79UymTwNmo7SXJ0CBrYAK0RmUNGPgxUKxDg==","shasum":"3847706d4e0d07386650d31cbf2c4a7d556a61ab","tarball":"https://registry.npmjs.org/@aspct/distill-agent/-/distill-agent-0.2.7.tgz","fileCount":5,"unpackedSize":96442,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIEk5Pkla4aaGKKNC5/iUbFZNlkcR9bICWD6Vx5P+XC/4AiEA+TpIHzO7yxGG2cXf30FMHOb5CZBRasq5Ws2bqUzTyec="}]},"_npmUser":{"name":"aspct","email":"Karim.ouda@hotmail.com"},"directories":{},"maintainers":[{"name":"aspct","email":"Karim.ouda@hotmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/distill-agent_0.2.7_1781193481120_0.32680047317413563"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-01T11:29:09.336Z","modified":"2026-06-11T15:58:01.377Z","0.2.6":"2026-06-01T11:29:09.731Z","0.2.7":"2026-06-11T15:58:01.269Z"},"bugs":{"url":"https://github.com/Aspct3434/Distill-Agent/issues"},"license":"MIT","homepage":"https://github.com/Aspct3434/Distill-Agent#readme","keywords":["distill","agent","ai","autonomous-agents","llm","react-agent","mcp","skill-distillation","installer","cli"],"repository":{"type":"git","url":"git+https://github.com/Aspct3434/Distill-Agent.git"},"description":"Distill — interactive installer and lifecycle CLI for the Distill autonomous agent framework.","maintainers":[{"name":"aspct","email":"Karim.ouda@hotmail.com"}],"readme":"\r\n

\r\n \"Colored\r\n

\r\n\r\n

\r\n \"MIT\r\n

\r\n\r\n**The self-hosted AI agent that can't say \"done\" without proof.**\r\n\r\nEvery Distill run is governed by a **task contract**: before finishing, the agent must produce physical evidence — a file written, a test passing, a service answering on its port. No evidence, no \"done\".\r\n\r\nDistill also learns your projects across sessions, distills its own reusable skills from experience (each one versioned and rolled back automatically if a newer version measurably regresses), keeps persistent **hybrid memory**, and reaches you over Telegram, Discord, Slack, email, a real-time streaming control panel, or the terminal.\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\nThe reasoning behind these decisions — and the alternatives that were\r\nrejected — is documented in [docs/DESIGN.md](docs/DESIGN.md).\r\n\r\n## 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 remotely through a single HTTP exec shim that can front any serverless sandbox (Daytona, E2B, Modal, …).\r\n* **Shareable Skills**: Export and import distilled skills via the open `SKILL.md` format.\r\n\r\n## Production Readiness\r\n\r\nDistill is a research framework with a stable core and a set of more\r\nexperimental capabilities around it. This matrix shows where each subsystem\r\nstands — treat anything marked *Experimental* as subject to change.\r\n\r\n| Subsystem | Maturity | Notes |\r\n|---|---|---|\r\n| FastAPI gateway (auth, rate-limit, session FIFO lanes) | **Stable** | Token-gated; returns 503 until `AGENT_API_TOKEN` is set. |\r\n| Contract / evidence-gated ReAct loop | **Stable** | Core differentiator; final answer gated on physical evidence. |\r\n| SQLite checkpointer + session store | **Stable** | Durable per-session state and history. |\r\n| Local & Docker sandbox | **Stable** | Default execution paths. |\r\n| Serverless sandbox (HTTP exec shim) | **Experimental** | Opt-in via `AGENT_SANDBOX=http`; one endpoint contract fronts any provider (Daytona, E2B, Modal, …). |\r\n| ChromaDB semantic + Neo4j graph memory | **Optional** | Degrade gracefully when the backends are absent. |\r\n| Skill distillation & evolution | **Experimental** | Auto-synthesised skills are versioned and auto-rolled-back on regression. |\r\n| Sub-agent delegation (`delegate_task`) | **Experimental** | Bounded delegated execution — see [ARCHITECTURE.md](ARCHITECTURE.md). |\r\n| Messaging adapters (Telegram / Discord / Slack / Email) | **Adapter-tested** | Off by default; activate per token. Local-only without public ingress. |\r\n\r\n## Quick Start\r\n\r\n### Deploy in one click\r\n\r\nSpin up the agent gateway in the cloud, add your LLM API key (and optionally a\r\nTelegram bot token), and text your agent. Runs lean — SQLite-backed memory, no\r\ndatabase to provision.\r\n\r\n[![Deploy to Render](https://render.com/images/deploy-to-render-button.svg)](https://render.com/deploy?repo=https://github.com/Aspct3434/Distill-Agent)\r\n \r\n[![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/new)\r\n\r\n* **Render** reads [`render.yaml`](render.yaml), generates a gateway token for\r\n you, and prompts for your provider key + models.\r\n* **Railway** uses [`railway.json`](railway.json): create a project from this\r\n repo, then set `AGENT_API_TOKEN`, `AGENT_MODEL`, and your provider key.\r\n* **Fly.io**: `fly launch --copy-config` against [`fly.toml`](fly.toml), then\r\n `fly secrets set …` (commands are in the file header).\r\n\r\n### Run locally — one command\r\n\r\n```bash\r\n./scripts/quickstart.sh\r\n```\r\n\r\nGenerates strong secrets, creates your env file, and brings the full stack up\r\nwith Docker Compose. Add your LLM API key to `an-api.env` and re-run.\r\n\r\n
\r\nManual 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. Set a Neo4j password for the bundled graph-memory database (required;\r\n# there is no insecure default). Compose reads it from .env:\r\necho \"NEO4J_PASSWORD=$(openssl rand -hex 24)\" >> .env\r\n\r\n# 4. Start the application\r\ndocker compose up -d --build\r\n```\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/Distill-Agent/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/Distill-Agent/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 @aspct/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/Distill-Agent install\r\n```\r\n\r\nAfter installation, use the CLI to manage the agent:\r\n```bash\r\nnpm i -g @aspct/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 @aspct/distill-agent start # Start the backend and control panel\r\nnpx @aspct/distill-agent logs # View running logs\r\nnpx @aspct/distill-agent update # Pull the latest changes\r\nnpx @aspct/distill-agent doctor # Diagnose the install and environment\r\n```\r\n\r\n## Configuration\r\n\r\nDistill is configured via environment variables. Key settings in `an-api.env`:\r\n\r\n### LLM providers\r\n\r\n`AGENT_MODEL` accepts any LiteLLM provider string. The installers can\r\npreconfigure Kimi/Moonshot, Ollama, OpenRouter, OpenAI, Anthropic, Gemini,\r\nDeepSeek, Groq, xAI Grok, Mistral, or any OpenAI-compatible endpoint (vLLM) —\r\nset the matching `*_API_KEY` in `an-api.env`.\r\n\r\nFor OpenAI you can also **sign in with your ChatGPT account (Codex OAuth)**\r\ninstead of pasting a key: choose it in the installer, or run\r\n`PYTHONPATH=src python -m auth login` (also available in the control panel\r\nunder Settings → Authentication). The token is stored locally, injected as\r\n`OPENAI_API_KEY`, and refreshed automatically before LLM calls.\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\nAdapters 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\nThe test suite covers 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\r\nTo measure the contract system's effect directly, the eval harness can run its\r\nlive suite with evidence gating on and off and report the false-completion\r\nrate (confident final answers whose deterministic check failed) per arm:\r\n\r\n```bash\r\npython src/eval_harness.py --benchmark-gating --out gating.json # needs an API key\r\n```\r\n\r\n## License\r\n\r\nDistill is released under the [MIT License](LICENSE).\r\n","readmeFilename":"README.md"}