hubzoid 0.2.2__tar.gz

hubzoid-0.2.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 HubZoid contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hubzoid-0.2.2/PKG-INFO

@@ -0,0 +1,352 @@
+Metadata-Version: 2.4
+Name: hubzoid
+Version: 0.2.2
+Summary: Drop a folder of markdown files, get a chat agent with a polished web UI.
+Author-email: HubZoid <hello@hubzoid.com>
+Maintainer-email: HubZoid <hello@hubzoid.com>
+License: MIT
+Project-URL: Homepage, https://github.com/hubzoid/hubzoid
+Project-URL: Repository, https://github.com/hubzoid/hubzoid
+Project-URL: Issues, https://github.com/hubzoid/hubzoid/issues
+Project-URL: Changelog, https://github.com/hubzoid/hubzoid/releases
+Keywords: agents,ai,llm,openai,anthropic,claude,openrouter,open-webui,markdown,agents.md,mcp
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: openai-agents[litellm]>=0.14.7
+Requires-Dist: claude-agent-sdk>=0.1.0
+Requires-Dist: open-webui>=0.6
+Requires-Dist: fastapi>=0.115
+Requires-Dist: uvicorn[standard]>=0.30
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.0
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: typer>=0.12
+Requires-Dist: rich>=13
+Requires-Dist: jinja2>=3.1
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+Dynamic: license-file
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="assets/mark-dark.svg">
+    <img alt="/hubzoid" src="assets/mark-light.svg" width="220">
+  </picture>
+</p>
+
+<p align="center">
+  <strong>Drop a folder of markdown files. Get a chat agent with a polished web UI.</strong>
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/hubzoid/"><img src="https://img.shields.io/pypi/v/hubzoid.svg?color=E5572A&label=pypi" alt="PyPI"></a>
+  <a href="https://pypi.org/project/hubzoid/"><img src="https://img.shields.io/pypi/pyversions/hubzoid.svg?color=0B0B0C" alt="Python"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-0B0B0C.svg" alt="MIT License"></a>
+  <a href="https://hubzoid.com"><img src="https://img.shields.io/badge/website-hubzoid.com-E5572A.svg" alt="hubzoid.com"></a>
+</p>
+
+---
+
+hubzoid reads `AGENTS.md`, `agents/`, `skills/`, and `knowledge/` from a folder
+and turns it into a running AI agent. Backed by the [OpenAI Agents
+SDK](https://openai.github.io/openai-agents-python/) or the [Claude Agent
+SDK](https://code.claude.com/docs/en/agent-sdk/overview), served over an
+OpenAI-compatible HTTP API, and chattable through a bundled
+[Open WebUI](https://openwebui.com) front end.
+
+You write the markdown. hubzoid handles the runtime, the API, the UI, the
+streaming, and the sub-agent routing. Provider-agnostic via
+[LiteLLM](https://docs.litellm.ai): OpenRouter, OpenAI, Anthropic, and local
+Claude work out of the box.
+
+## Quickstart
+
+**3 steps if you have `claude` CLI installed and logged in, 4 otherwise.**
+
+```bash
+pip install hubzoid
+hubzoid init demo-hub                  # scaffolds a starter hub + agents-repo wrapper
+*  edit demo-hub/.env                  # ← optional. skip if using claude-local.
+hubzoid run demo-hub
+```
+
+Open <http://localhost:3080>. The scaffolded `demo-hub` is a working **Hubzoid
+Guide** agent.
+
+**\* Step 3 (the optional one).** Default `MODEL=claude-local` uses your
+installed `claude` CLI subscription. If you already ran `claude login`,
+skip this step and go straight to `hubzoid run`. Otherwise, open
+`demo-hub/.env`, comment out the `MODEL=claude-local` line, and uncomment
+one of the provider stanzas (OpenRouter, OpenAI, Anthropic) with your key
+pasted in.
+
+The two files you edit later as you customize:
+
+1. `demo-hub/.env`: keys, model selection, UI knobs.
+2. `demo-hub/AGENTS.md`: the system prompt body. YAML frontmatter sets
+   `name`, `description`, and optional `model`.
+
+## How it works
+
+```
+┌─────────────────────────────┐
+│  Open WebUI                 │  http://localhost:3080
+│  (web chat, white-label)    │
+└──────────────┬──────────────┘
+               │ OpenAI-compatible HTTP
+┌──────────────┴──────────────┐
+│  FastAPI bridge             │  /v1/chat/completions  /v1/models
+└──────────────┬──────────────┘
+               │ in-process
+┌──────────────┴──────────────┐
+│  Agent runtime              │  OpenAI Agents SDK  |  Claude Agent SDK
+└──────────────┬──────────────┘
+               │ LiteLLM (or claude CLI subprocess)
+┌──────────────┴──────────────┐
+│  Your model                 │  OpenRouter · OpenAI · Anthropic · claude-local
+└─────────────────────────────┘
+```
+
+One install command. Open WebUI, the Claude Agent SDK, the OpenAI Agents
+SDK, LiteLLM, and FastAPI are all bundled as required dependencies. No
+optional extras for the runtime.
+
+## A minimal AGENTS.md
+
+```markdown
+---
+name: code-reviewer
+description: Reviews a code diff. Ranks the top three issues by severity.
+model: openrouter/anthropic/claude-haiku-4.5
+---
+
+You review code. When the user pastes a diff or a file, identify the top
+three issues ranked by severity: correctness first, then security, then
+readability.
+
+For each issue, cite the line number and explain the fix in one sentence.
+Skip style nits unless the user asks for them. If the code looks clean,
+say so in one line and stop.
+```
+
+That is the whole hub. One file. No sub-agents, no skills, no knowledge
+needed. Drop it in a folder, run `hubzoid run .`, and you have a code
+reviewer at <http://localhost:3080>.
+
+## Editing your hub
+
+Your hub is one folder. Six things to know.
+
+1. **Pick your model.** Default `.env` uses `MODEL=claude-local` (no key
+   needed if `claude login` is done). To switch to OpenRouter / OpenAI /
+   Anthropic, uncomment a stanza in `.env` and paste a key.
+2. **Write the main agent.** Open `AGENTS.md`. The body is the system
+   prompt. YAML frontmatter sets `name`, `description`, and optional
+   `model`.
+3. **Sub-agents.** One folder per sub-agent under `agents/`. Each has its
+   own `AGENTS.md`. Frontmatter `tools: [...]` whitelists which tools the
+   sub-agent may call.
+4. **Skills.** One folder per playbook under `skills/`, each with a
+   `SKILL.md`. The main agent loads them on demand via `load_skill(name)`.
+5. **Knowledge.** One markdown file per topic under `knowledge/`. Reached
+   via `read_knowledge(name)`.
+6. **Tools and connectors.** Drop Python files with `@function_tool` in
+   `tools_local/`. Edit `connectors/.mcp.json` to plug in
+   [MCP](https://modelcontextprotocol.io) servers.
+
+Folder names are case- and plural-flexible. `skills/`, `Skills/`, and
+`skill/` all work. Same for `agents/`, `knowledge/`, `tools_local/`,
+`connectors/`. Restart with the same command. Changes are picked up on
+the next start.
+
+## Multi-hub agents repo
+
+Run `hubzoid init` more than once in the same directory and you get a
+Samarth-style multi-hub layout with one parent `requirements.txt`:
+
+```bash
+mkdir my-agents && cd my-agents
+hubzoid init devops-agent       # creates ./devops-agent + ./requirements.txt + ./.gitignore + ./README.md
+hubzoid init support-agent      # creates ./support-agent only; parent files left alone
+hubzoid init research-agent     # creates ./research-agent only
+```
+
+Each hub is independent: its own `.env`, its own port, its own user
+database. The parent files are written **only** on the first init in a
+fresh directory (empty or containing only dotfiles / README /
+requirements.txt / LICENSE). Idempotent and non-destructive afterward.
+
+## Providers
+
+Pick one stanza in `.env`. See [docs/providers.md](docs/providers.md) for
+more detail.
+
+```bash
+# OpenRouter (one key, many models)
+OPENROUTER_API_KEY=sk-or-v1-...
+MODEL=openrouter/anthropic/claude-haiku-4.5
+
+# OR OpenAI
+OPENAI_API_KEY=sk-...
+MODEL=openai/gpt-4o-mini
+
+# OR Anthropic
+ANTHROPIC_API_KEY=sk-ant-...
+MODEL=anthropic/claude-haiku-4-5
+
+# OR Claude local (uses your installed `claude` CLI + Pro/Max subscription)
+# Requires `claude login` first. No API key needed.
+MODEL=claude-local
+# MODEL=claude-local/sonnet       # pin Sonnet
+# MODEL=claude-local/opus         # pin Opus
+# MODEL=claude-local/haiku        # pin Haiku
+```
+
+The `MODEL` string tells LiteLLM which provider to call, and the matching
+key must be set. The exception is `MODEL=claude-local`: instead of
+LiteLLM, hubzoid drives the Claude Agent SDK against your locally
+installed `claude` CLI, so auth and billing flow through your existing
+Pro/Max subscription. Same hub folder, same tools, same skills. Only the
+LLM and auth path differ.
+
+## Pre-shipped tools
+
+Every hub gets these tools for free.
+
+| Tool | What it does |
+|---|---|
+| `read_file(path)` | Read a file under the hub directory. |
+| `list_files(glob)` | List files matching a glob. |
+| `write_artifact(filename, content)` | Write a file under `output/<session>/`. |
+| `list_skills()` | Menu of skills in the hub. |
+| `load_skill(name)` | Read a skill's full body on demand. |
+| `list_knowledge()` | Menu of knowledge documents. |
+| `read_knowledge(name)` | Read a knowledge document's full body. |
+| `remember(fact, scope)` | Save a fact to durable memory. |
+| `recall(query, scope)` | Look up saved facts. |
+| `forget(id, scope)` | Delete a saved fact. |
+| `render_jinja(template, context_json)` | Render a Jinja2 template. |
+| `http_get(url)` | Fetch a URL (honors `HTTP_ALLOWLIST`). |
+| `web_search(query)` | DuckDuckGo search. No API key. |
+
+Custom tools dropped into `tools_local/*.py` are auto-discovered.
+
+## MCP connectors
+
+MCP connectors are **per-hub**. Each hub has its own
+`<hub>/connectors/.mcp.json` alongside its `AGENTS.md`. Two hubs in the
+same agents-repo connect to completely different MCP servers because each
+loads its own config independently. There is no parent-level shared MCP
+file by design: agents are independent products with their own scope.
+
+Edit `demo-hub/connectors/.mcp.json` (or whatever your hub is named):
+
+```json
+{
+  "mcpServers": {
+    "filesystem": {
+      "command": "npx",
+      "args": ["@modelcontextprotocol/server-filesystem", "./workspace"]
+    },
+    "github": {
+      "command": "npx",
+      "args": ["@modelcontextprotocol/server-github"],
+      "env": {"GITHUB_PERSONAL_ACCESS_TOKEN": "${GH_TOKEN}"}
+    }
+  }
+}
+```
+
+`${VAR}` references in any string field resolve against the environment at
+boot. The same `.mcp.json` is honored by both the OpenAI Agents and
+Claude Agent runtimes.
+
+## CLI
+
+```
+hubzoid init [NAME]              Scaffold a new hub folder under the current directory.
+                                   NAME defaults to "demo-hub".
+                                   Also drops requirements.txt / .gitignore / README.md
+                                   at the parent on first run if the directory looks fresh.
+hubzoid run [PATH]               Start the FastAPI bridge plus Open WebUI for a hub.
+  --port INT                       Open WebUI port (default 3080).
+  --bridge-port INT                FastAPI bridge port (default 8000).
+  --no-ui                          Bridge only, no Open WebUI.
+hubzoid doctor [PATH]            Validate hub config and report issues.
+hubzoid test [PATH]              Send one prompt to the agent and print the response.
+hubzoid version
+hubzoid --help
+```
+
+PATH defaults to `.` for run / doctor / test. `python -m hubzoid ...` also
+works as an alternative invocation.
+
+## Run from source
+
+For contributors or anyone who wants to read or extend the framework code.
+
+```bash
+git clone https://github.com/hubzoid/hubzoid.git
+cd hubzoid
+python -m venv .venv && source .venv/bin/activate
+pip install -e '.[dev]'
+hubzoid run demo-hub
+```
+
+The repo ships with `demo-hub/` at the root as a working starter. Its
+`.env` is git-ignored but the template includes sensible defaults
+(`MODEL=claude-local`).
+
+## Open standards
+
+| Spec | Used at |
+|---|---|
+| [AGENTS.md](https://agents.md) | `<hub>/AGENTS.md`, `<hub>/agents/<n>/AGENTS.md` |
+| SKILL.md | `<hub>/skills/<n>/SKILL.md` |
+| [MCP](https://modelcontextprotocol.io) | `<hub>/connectors/.mcp.json` |
+
+Hubs are portable across any tool that adopts these specs (Claude Code,
+Cursor, Codex, Copilot, Gemini CLI, VS Code).
+
+## Roadmap
+
+* **v0.2** Current. PyPI release with bundled Open WebUI + Claude Agent
+  SDK; OpenAI Agents and Claude Agent runtimes; AGENTS.md, SKILL.md, MCP
+  loaders; OpenRouter, OpenAI, Anthropic, claude-local providers.
+* **v0.3** Per-hub branding, auth-on path, native-venv production
+  deployment docs, Playwright UI test tier.
+* **v0.4** Background and scheduled workflows via WaveAssist Cloud
+  (separate product, opt-in).
+* **Later** Slack and Telegram chat surfaces. Mem0 / Zep memory backends.
+
+Non-goals: voice and realtime, visual agent builder.
+
+## Hubzoid as a service
+
+This is the open-source framework. [hubzoid.com](https://hubzoid.com) is
+the consulting practice that deploys role-scoped hubs for mid-enterprise
+organizations in six weeks, fixed scope, fixed price. The framework is
+the substrate; the practice ships the deployment.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Issues and PRs welcome.
+
+## License
+
+MIT.

hubzoid-0.2.2/README.md

@@ -0,0 +1,308 @@
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="assets/mark-dark.svg">
+    <img alt="/hubzoid" src="assets/mark-light.svg" width="220">
+  </picture>
+</p>
+
+<p align="center">
+  <strong>Drop a folder of markdown files. Get a chat agent with a polished web UI.</strong>
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/hubzoid/"><img src="https://img.shields.io/pypi/v/hubzoid.svg?color=E5572A&label=pypi" alt="PyPI"></a>
+  <a href="https://pypi.org/project/hubzoid/"><img src="https://img.shields.io/pypi/pyversions/hubzoid.svg?color=0B0B0C" alt="Python"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-0B0B0C.svg" alt="MIT License"></a>
+  <a href="https://hubzoid.com"><img src="https://img.shields.io/badge/website-hubzoid.com-E5572A.svg" alt="hubzoid.com"></a>
+</p>
+
+---
+
+hubzoid reads `AGENTS.md`, `agents/`, `skills/`, and `knowledge/` from a folder
+and turns it into a running AI agent. Backed by the [OpenAI Agents
+SDK](https://openai.github.io/openai-agents-python/) or the [Claude Agent
+SDK](https://code.claude.com/docs/en/agent-sdk/overview), served over an
+OpenAI-compatible HTTP API, and chattable through a bundled
+[Open WebUI](https://openwebui.com) front end.
+
+You write the markdown. hubzoid handles the runtime, the API, the UI, the
+streaming, and the sub-agent routing. Provider-agnostic via
+[LiteLLM](https://docs.litellm.ai): OpenRouter, OpenAI, Anthropic, and local
+Claude work out of the box.
+
+## Quickstart
+
+**3 steps if you have `claude` CLI installed and logged in, 4 otherwise.**
+
+```bash
+pip install hubzoid
+hubzoid init demo-hub                  # scaffolds a starter hub + agents-repo wrapper
+*  edit demo-hub/.env                  # ← optional. skip if using claude-local.
+hubzoid run demo-hub
+```
+
+Open <http://localhost:3080>. The scaffolded `demo-hub` is a working **Hubzoid
+Guide** agent.
+
+**\* Step 3 (the optional one).** Default `MODEL=claude-local` uses your
+installed `claude` CLI subscription. If you already ran `claude login`,
+skip this step and go straight to `hubzoid run`. Otherwise, open
+`demo-hub/.env`, comment out the `MODEL=claude-local` line, and uncomment
+one of the provider stanzas (OpenRouter, OpenAI, Anthropic) with your key
+pasted in.
+
+The two files you edit later as you customize:
+
+1. `demo-hub/.env`: keys, model selection, UI knobs.
+2. `demo-hub/AGENTS.md`: the system prompt body. YAML frontmatter sets
+   `name`, `description`, and optional `model`.
+
+## How it works
+
+```
+┌─────────────────────────────┐
+│  Open WebUI                 │  http://localhost:3080
+│  (web chat, white-label)    │
+└──────────────┬──────────────┘
+               │ OpenAI-compatible HTTP
+┌──────────────┴──────────────┐
+│  FastAPI bridge             │  /v1/chat/completions  /v1/models
+└──────────────┬──────────────┘
+               │ in-process
+┌──────────────┴──────────────┐
+│  Agent runtime              │  OpenAI Agents SDK  |  Claude Agent SDK
+└──────────────┬──────────────┘
+               │ LiteLLM (or claude CLI subprocess)
+┌──────────────┴──────────────┐
+│  Your model                 │  OpenRouter · OpenAI · Anthropic · claude-local
+└─────────────────────────────┘
+```
+
+One install command. Open WebUI, the Claude Agent SDK, the OpenAI Agents
+SDK, LiteLLM, and FastAPI are all bundled as required dependencies. No
+optional extras for the runtime.
+
+## A minimal AGENTS.md
+
+```markdown
+---
+name: code-reviewer
+description: Reviews a code diff. Ranks the top three issues by severity.
+model: openrouter/anthropic/claude-haiku-4.5
+---
+
+You review code. When the user pastes a diff or a file, identify the top
+three issues ranked by severity: correctness first, then security, then
+readability.
+
+For each issue, cite the line number and explain the fix in one sentence.
+Skip style nits unless the user asks for them. If the code looks clean,
+say so in one line and stop.
+```
+
+That is the whole hub. One file. No sub-agents, no skills, no knowledge
+needed. Drop it in a folder, run `hubzoid run .`, and you have a code
+reviewer at <http://localhost:3080>.
+
+## Editing your hub
+
+Your hub is one folder. Six things to know.
+
+1. **Pick your model.** Default `.env` uses `MODEL=claude-local` (no key
+   needed if `claude login` is done). To switch to OpenRouter / OpenAI /
+   Anthropic, uncomment a stanza in `.env` and paste a key.
+2. **Write the main agent.** Open `AGENTS.md`. The body is the system
+   prompt. YAML frontmatter sets `name`, `description`, and optional
+   `model`.
+3. **Sub-agents.** One folder per sub-agent under `agents/`. Each has its
+   own `AGENTS.md`. Frontmatter `tools: [...]` whitelists which tools the
+   sub-agent may call.
+4. **Skills.** One folder per playbook under `skills/`, each with a
+   `SKILL.md`. The main agent loads them on demand via `load_skill(name)`.
+5. **Knowledge.** One markdown file per topic under `knowledge/`. Reached
+   via `read_knowledge(name)`.
+6. **Tools and connectors.** Drop Python files with `@function_tool` in
+   `tools_local/`. Edit `connectors/.mcp.json` to plug in
+   [MCP](https://modelcontextprotocol.io) servers.
+
+Folder names are case- and plural-flexible. `skills/`, `Skills/`, and
+`skill/` all work. Same for `agents/`, `knowledge/`, `tools_local/`,
+`connectors/`. Restart with the same command. Changes are picked up on
+the next start.
+
+## Multi-hub agents repo
+
+Run `hubzoid init` more than once in the same directory and you get a
+Samarth-style multi-hub layout with one parent `requirements.txt`:
+
+```bash
+mkdir my-agents && cd my-agents
+hubzoid init devops-agent       # creates ./devops-agent + ./requirements.txt + ./.gitignore + ./README.md
+hubzoid init support-agent      # creates ./support-agent only; parent files left alone
+hubzoid init research-agent     # creates ./research-agent only
+```
+
+Each hub is independent: its own `.env`, its own port, its own user
+database. The parent files are written **only** on the first init in a
+fresh directory (empty or containing only dotfiles / README /
+requirements.txt / LICENSE). Idempotent and non-destructive afterward.
+
+## Providers
+
+Pick one stanza in `.env`. See [docs/providers.md](docs/providers.md) for
+more detail.
+
+```bash
+# OpenRouter (one key, many models)
+OPENROUTER_API_KEY=sk-or-v1-...
+MODEL=openrouter/anthropic/claude-haiku-4.5
+
+# OR OpenAI
+OPENAI_API_KEY=sk-...
+MODEL=openai/gpt-4o-mini
+
+# OR Anthropic
+ANTHROPIC_API_KEY=sk-ant-...
+MODEL=anthropic/claude-haiku-4-5
+
+# OR Claude local (uses your installed `claude` CLI + Pro/Max subscription)
+# Requires `claude login` first. No API key needed.
+MODEL=claude-local
+# MODEL=claude-local/sonnet       # pin Sonnet
+# MODEL=claude-local/opus         # pin Opus
+# MODEL=claude-local/haiku        # pin Haiku
+```
+
+The `MODEL` string tells LiteLLM which provider to call, and the matching
+key must be set. The exception is `MODEL=claude-local`: instead of
+LiteLLM, hubzoid drives the Claude Agent SDK against your locally
+installed `claude` CLI, so auth and billing flow through your existing
+Pro/Max subscription. Same hub folder, same tools, same skills. Only the
+LLM and auth path differ.
+
+## Pre-shipped tools
+
+Every hub gets these tools for free.
+
+| Tool | What it does |
+|---|---|
+| `read_file(path)` | Read a file under the hub directory. |
+| `list_files(glob)` | List files matching a glob. |
+| `write_artifact(filename, content)` | Write a file under `output/<session>/`. |
+| `list_skills()` | Menu of skills in the hub. |
+| `load_skill(name)` | Read a skill's full body on demand. |
+| `list_knowledge()` | Menu of knowledge documents. |
+| `read_knowledge(name)` | Read a knowledge document's full body. |
+| `remember(fact, scope)` | Save a fact to durable memory. |
+| `recall(query, scope)` | Look up saved facts. |
+| `forget(id, scope)` | Delete a saved fact. |
+| `render_jinja(template, context_json)` | Render a Jinja2 template. |
+| `http_get(url)` | Fetch a URL (honors `HTTP_ALLOWLIST`). |
+| `web_search(query)` | DuckDuckGo search. No API key. |
+
+Custom tools dropped into `tools_local/*.py` are auto-discovered.
+
+## MCP connectors
+
+MCP connectors are **per-hub**. Each hub has its own
+`<hub>/connectors/.mcp.json` alongside its `AGENTS.md`. Two hubs in the
+same agents-repo connect to completely different MCP servers because each
+loads its own config independently. There is no parent-level shared MCP
+file by design: agents are independent products with their own scope.
+
+Edit `demo-hub/connectors/.mcp.json` (or whatever your hub is named):
+
+```json
+{
+  "mcpServers": {
+    "filesystem": {
+      "command": "npx",
+      "args": ["@modelcontextprotocol/server-filesystem", "./workspace"]
+    },
+    "github": {
+      "command": "npx",
+      "args": ["@modelcontextprotocol/server-github"],
+      "env": {"GITHUB_PERSONAL_ACCESS_TOKEN": "${GH_TOKEN}"}
+    }
+  }
+}
+```
+
+`${VAR}` references in any string field resolve against the environment at
+boot. The same `.mcp.json` is honored by both the OpenAI Agents and
+Claude Agent runtimes.
+
+## CLI
+
+```
+hubzoid init [NAME]              Scaffold a new hub folder under the current directory.
+                                   NAME defaults to "demo-hub".
+                                   Also drops requirements.txt / .gitignore / README.md
+                                   at the parent on first run if the directory looks fresh.
+hubzoid run [PATH]               Start the FastAPI bridge plus Open WebUI for a hub.
+  --port INT                       Open WebUI port (default 3080).
+  --bridge-port INT                FastAPI bridge port (default 8000).
+  --no-ui                          Bridge only, no Open WebUI.
+hubzoid doctor [PATH]            Validate hub config and report issues.
+hubzoid test [PATH]              Send one prompt to the agent and print the response.
+hubzoid version
+hubzoid --help
+```
+
+PATH defaults to `.` for run / doctor / test. `python -m hubzoid ...` also
+works as an alternative invocation.
+
+## Run from source
+
+For contributors or anyone who wants to read or extend the framework code.
+
+```bash
+git clone https://github.com/hubzoid/hubzoid.git
+cd hubzoid
+python -m venv .venv && source .venv/bin/activate
+pip install -e '.[dev]'
+hubzoid run demo-hub
+```
+
+The repo ships with `demo-hub/` at the root as a working starter. Its
+`.env` is git-ignored but the template includes sensible defaults
+(`MODEL=claude-local`).
+
+## Open standards
+
+| Spec | Used at |
+|---|---|
+| [AGENTS.md](https://agents.md) | `<hub>/AGENTS.md`, `<hub>/agents/<n>/AGENTS.md` |
+| SKILL.md | `<hub>/skills/<n>/SKILL.md` |
+| [MCP](https://modelcontextprotocol.io) | `<hub>/connectors/.mcp.json` |
+
+Hubs are portable across any tool that adopts these specs (Claude Code,
+Cursor, Codex, Copilot, Gemini CLI, VS Code).
+
+## Roadmap
+
+* **v0.2** Current. PyPI release with bundled Open WebUI + Claude Agent
+  SDK; OpenAI Agents and Claude Agent runtimes; AGENTS.md, SKILL.md, MCP
+  loaders; OpenRouter, OpenAI, Anthropic, claude-local providers.
+* **v0.3** Per-hub branding, auth-on path, native-venv production
+  deployment docs, Playwright UI test tier.
+* **v0.4** Background and scheduled workflows via WaveAssist Cloud
+  (separate product, opt-in).
+* **Later** Slack and Telegram chat surfaces. Mem0 / Zep memory backends.
+
+Non-goals: voice and realtime, visual agent builder.
+
+## Hubzoid as a service
+
+This is the open-source framework. [hubzoid.com](https://hubzoid.com) is
+the consulting practice that deploys role-scoped hubs for mid-enterprise
+organizations in six weeks, fixed scope, fixed price. The framework is
+the substrate; the practice ships the deployment.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Issues and PRs welcome.
+
+## License
+
+MIT.

hubzoid-0.2.2/hubzoid/__init__.py

@@ -0,0 +1,10 @@
+"""HubZoid — markdown-driven AI agent platform.
+
+Drop AGENTS.md + skills/ + knowledge/ into a folder, get a working chat agent
+with a polished web UI. See README.md.
+"""
+from __future__ import annotations
+
+__version__ = "0.2.2"
+
+from .factory import build_agent  # noqa: E402,F401  (public re-export)