Voice
AgentKthx
By ⚛️ AgentKthx - minimal, modular, python stdlib, agentic framework for tool calling AI agents. Runs locally with Ollama, BitNet, TurboQuant, in the cloud with OpenRouter, ZAI, HuggingFace, and Google Gemini. Extensible via a manifest-based plugin system for additional backends and features.
Install
pip install git+https://github.com/VTSTech/AgentKthx.gitREADME
# ⚛️ AgentKthx R07.34
**Status: Alpha**
A minimal, modular, python stdlib, agentic framework for tool calling AI agents. Runs **locally** with [BitNet](https://github.com/microsoft/BitNet), [Ollama](https://ollama.com), [TurboQuant](https://github.com/TheTom/llama-cpp-turboquant), and [stable-diffusion.cpp](https://github.com/leejet/stable-diffusion.cpp) (image generation), **in the cloud** with [Cloudflare](https://developers.cloudflare.com/workers-ai/), [Google](https://ai.google.dev/gemini-api/docs), [HuggingFace](https://huggingface.co/), [Mistral](https://mistral.ai), [NVIDIA](https://build.nvidia.com), [OpenAI](https://openai.com), [OpenRouter](https://openrouter.ai), [OrcaRouter](https://www.orcarouter.ai), [Pollinations](https://enter.pollinations.ai), [SiliconFlow](https://www.siliconflow.com), [TokenHarbor](https://tokenharbor.ai/) and [ZAI](https://api.z.ai). Extensible via a manifest-based **plugin system** for additional backends and features.
Inspired by the architecture of OpenClaw, rebuilt from scratch for local-first operation.
**Written by [VTSTech](https://www.vts-tech.org)** · [GitHub](https://github.com/VTSTech/AgentKthx) [Discord](https://discord.gg/vSK3Ba2aQ)
[](https://colab.research.google.com/github/VTSTech/AgentKthx/blob/main/AgentKthx.ipynb)
[](https://GitHub.com/VTSTech/AgentKthx/commit/) [](https://GitHub.com/VTSTech/AgentKthx/commit/) [](https://github.com/VTSTech/AgentKthx/actions/workflows/ci.yml) 
[](https://pypi.org/project/agentkthx/) [](https://pypi.org/project/agentkthx/) [](https://pypi.org/project/agentkthx/) [](https://pypi.org/project/agentkthx/)
[](#license) [](https://python.org)
## Installation
```bash
# Latest Development Release
pip install git+https://github.com/VTSTech/AgentKthx.git --force-reinstall
# Last Stable (as stable as Alpha can be) Release
pip install agentkthx
```
<img width="1648" height="996" alt="image" src="https://github.com/user-attachments/assets/42a7dfd6-ffb4-4e1a-844d-7984b4c8b59c" />
<img width="1295" height="1002" alt="image" src="https://github.com/user-attachments/assets/4264616b-1af7-44ad-bc74-24f78737f8e3" />
<img width="1498" height="721" alt="image" src="https://github.com/user-attachments/assets/f1f1e13b-c489-4fc3-b05c-9f6084818e7b" />
<img width="1117" height="882" alt="image" src="https://github.com/user-attachments/assets/d3e1a716-f3df-4383-ade2-c34882dbddb8" />
<img width="1247" height="622" alt="image" src="https://github.com/user-attachments/assets/f71e2221-57ac-4c15-850b-206039a95063" />
<img width="848" height="316" alt="image" src="https://github.com/user-attachments/assets/86724683-b217-4788-9277-1e16b65d74c2" />
<img width="1067" height="342" alt="image" src="https://github.com/user-attachments/assets/8b7870ca-5393-46b4-8d7a-0ea165cb2d41" />
<img width="1042" height="650" alt="image" src="https://github.com/user-attachments/assets/7743850a-634b-4fe6-96ea-977a96c26572" />
<img width="672" height="617" alt="image" src="https://github.com/user-attachments/assets/59b4a074-fd8a-4970-8289-5ec671324a94" />
<img width="1553" height="648" alt="image" src="https://github.com/user-attachments/assets/aeeb37b8-8f80-429b-b0e3-a31f8b3a482d" />
<img width="1311" height="668" alt="image" src="https://github.com/user-attachments/assets/b813736c-4944-4b11-96c1-27aeda70b9e8" />
## 📚 Documentation
| Document | Description |
|----------|-------------|
| [ARCH.md](https://github.com/VTSTech/AgentKthx/blob/main/docs/ARCH.md) | Technical documentation for developers (directory structure, core design, orchestrator modes) |
| [CHANGELOG.md](https://github.com/VTSTech/AgentKthx/blob/main/docs/CHANGELOG.md) | Version history and release notes (includes LocalClaw history) |
| [CREDITS.md](https://github.com/VTSTech/AgentKthx/blob/main/docs/CREDITS.md) | Acknowledges every project, inspiration, API, model creator, and specification that makes AgentKthx possible |
| [DISCORD.md](https://github.com/VTSTech/AgentKthx/blob/main/docs/DISCORD.md) | **Discord bot guide** — portal setup + invite URL, `agentkthx discord setup` wizard, env var reference, per-channel `discord.json` overrides, slash commands (`/ask` `/think` `/model` `/soul` `/reset` `/status`), run cookbook, troubleshooting matrix (4014/4004/silent bot) |
| [docs/api/](https://github.com/VTSTech/AgentKthx/blob/main/docs/api/) | **API Technical References** — one deep-dive per provider, all in one folder: NVIDIA NIM, ZAI, OpenRouter, Gemini, Hugging Face Router, OpenAI, Mistral, Pollinations, OrcaRouter (auth & endpoints, request/response schemas, model catalogs, function calling, streaming, error codes & recovery, rate limits, free-tier behavior, AgentKthx `Backend` + `plugin.json` blueprints, troubleshooting matrices) |
| [JEV_API_MODE.md](https://github.com/VTSTech/AgentKthx/blob/main/docs/JEV_API_MODE.md) | JEV API mode — System-One decisions via any free LLM (Jev-compatible shape) |
| [mcp/ROADMAP.md](https://github.com/VTSTech/AgentKthx/blob/main/docs/mcp/ROADMAP.md) | **MCP support** — Phase 1 (client mode, stdio) status + Phase 2 (`kthx-audit` MCP server) + Phase 3 (generic `mcp serve`) plan |
| [PLUGIN_SPEC_v0.2.md](https://github.com/VTSTech/AgentKthx/blob/main/docs/PLUGIN_SPEC_v0.2.md) | Plugin spec v0.2 — lifecycle hooks, plugin tools API, external plugin roots, dual-form manifests, migration guide from v0.1 |
| [STABLE_DIFFUSION_BACKEND_PLAN.md](https://github.com/VTSTech/AgentKthx/blob/main/docs/STABLE_DIFFUSION_BACKEND_PLAN.md) | Stable Diffusion backend design (D1–D5) — sd.cpp wire facts pinned at source commit 228c707, capabilities discovery, image-artifact pipeline, test plan |
| [SUPPORT.md](https://github.com/VTSTech/AgentKthx/blob/main/docs/SUPPORT.md) | Backend support tiers — Fully Supported vs Limited Support per-backend policy (R07.25) |
| [USAGE.md](https://github.com/VTSTech/AgentKthx/blob/main/docs/USAGE.md) | **Usage guide** — CLI commands, backend configurations (OpenRouter/Gemini/HuggingFace/ZAI/TurboQuant), Python API, persistent memory, security modes, environment variables, MCP client setup, full CLI options table |
| [TESTS.md](https://github.com/VTSTech/AgentKthx/blob/main/docs/TESTS.md) | Example scripts, test categories, benchmark results, and per-test deep-dive results |
## Features
- **Zero dependencies** — Uses Python stdlib only (urllib for HTTP)
- **Plugin system** — Manifest-based plugin discovery, lazy loading, dependency resolution (R05.0), plugin spec v0.2 lifecycle hooks (`on_init`/`on_run_start`/`on_run_end`/`on_error`/`on_shutdown`), plugin-provided tools, external plugin roots (`~/.agentkthx/plugins/`, `$AGENTKTHX_PLUGIN_PATH`), optional `sha256` content pinning (R07.05 SEC-06), `plugins --load/--unload/--reload/--json/--verbose` management
- **Native + plugin backends** — Ollama + TurboQuant built-in; Cloudflare, NVIDIA, OpenRouter, BitNet, ZAI, ACP, Gemini, OrcaRouter, Mistral, HuggingFace, OpenAI, Pollinations, SiliconFlow, and Stable Diffusion (image generation) as plugins. (The TurboQuant backend uses llama.cpp's `llama-server` binary under the hood — `--backend turboquant` is the primary name; `--backend llama-server` remains as a backward-compat alias. Stable Diffusion follows the same pattern: `--backend stable-diffusion` is the primary name, `--backend sd` the alias.)
- **Image generation** (R07.31) — `--backend sd` turns each chat turn into ONE image via an external [stable-diffusion.cpp](https://github.com/leejet/stable-diffusion.cpp) server (`sd-server -m <model> --listen-port 1234` — Ollama pattern: AgentKthx never manages the process). The flattened conversation becomes the prompt (harness system prompt suppressed, DDG-style), and the returned PNG is written to the artifacts dir (`AGENTKTHX_ARTIFACTS_DIR`, default `./generated/`) — the reply carries `[image saved: <path>]`. R07.32: `--max-steps N --backend sd` remaps to diffusion **sample steps** (validated 1–100, applied per request via the server's `sd_cpp_extra_args` — no restart) and the session header shows **Sample Steps** instead of Max Steps.
- **Backend support tiers** (R07.25) — ZAI, OpenRouter, HuggingFace, Gemini, Mistral, NVIDIA NIM, Cloudflare Workers AI, and the R07.31 TokenHarbor scaffold are Fully Supported (maintainer-tested before every release — Cloudflare promoted R07.27 and TokenHarbor promoted R07.34, each after a 5/5 end-to-end smoke test; TokenHarbor runs $0 on its `:free` tier); Pollinations, OrcaRouter, OpenAI, and the R07.29 SiliconFlow scaffold are Limited Support (code-quality identical, but the maintainer's API key access has been unavailable for an extended period — SiliconFlow passed its live catalog probe (79 models, R07.29) and its 2026-10-09 smoke attempt verified auth, the catalog, and one `--think` generation before the account balance drained; both tool-call steps returned 402 insufficient-balance, so it awaits a topped-up 5/5 run). See [docs/SUPPORT.md](docs/SUPPORT.md) for the full policy + what "Limited Support" means in practice. Local backends (TurboQuant, Ollama, BitNet, Stable Diffusion) are always Fully Supported (no external API
... (truncated)
voice
Comments
Sign in to leave a comment