sam/central_ai_llm_master
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Freeze Hub inbound API v1; choose Go for the service

Browse Source 
- docs/hub-api.md: language decision (Go 1.25) with reason and the
  frozen v1 routes POST /ask, POST /approve, GET /health, including
  request/response schemas, bearer-token auth, timeouts, error shapes,
  logging, versioning, and a safety confirmation that no route is a
  high-consequence control.
- Update README, hub_brief.md open items, and the outline docs so they
  no longer say the API is undecided or the language is open.

Co-Authored-By: Paperclip <noreply@paperclip.ing>
This commit is contained in:
Sam Rolfe
2026-10-10 17:06:43 +11:00
parent 6a395d46a9
commit 449fdd02c5
6 changed files with 528 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
docs/outline/00-index.md
View File

@@ -14,6 +14,7 @@ Read this index to inject the exact file you need. Do not search all files.
| **Code Structure Map** | `docs/outline/03-code-map.md` | Shows the planned folder layout and entry points. |
| **AI Agent Runbook** | `docs/outline/04-agent-runbook.md` | Gives steps to build, test, and restart Hub work. |
| **Ask Contract** | `docs/ask-contract.md` | The interface between the Hub and every data project. |
| **Hub Inbound API** | `docs/hub-api.md` | The frozen v1 API from every way in to the Hub. |
| **Design Brief** | `hub_brief.md` | The agreed design. This file is the source of truth. |
| **Project Rules** | `AGENTS.md` | Mission, rules, build order, and project relations. |
@@ -29,7 +30,7 @@ hold a personality or a memory. The Hub does not do the destination work.
- **Env File**: `~/.config/environment.d/10-secrets.conf`
- **Config Directory**: `docs/`
- **Active Ports**: Hub port not allocated yet.
- **Active Ports**: Hub 8787 (`HUB_PORT`, proposed default — confirm before deploy).
## Agent Restart Steps

7
docs/outline/02-config-and-env.md
View File

@@ -17,6 +17,11 @@ Relevant keys:
| `OL_API_KEY` | Outline docs. |
| `VIKUNJA_TOKEN` | Vikunja tasks. |
| `GITEA_TOKEN` | Gitea repository. |
| `HUB_TOKEN_PHONE` | Hub token for the phone app. |
| `HUB_TOKEN_ESP32` | Hub token for the house voice. |
| `HUB_TOKEN_DSH` | Hub token for dsh chat. |
| `HUB_TOKEN_CONSOLE` | Hub token for the console portal. |
| `HUB_TOKEN_ADMIN` | Hub token for the admin app. The only trusted door. |
## Services and Ports
@@ -28,7 +33,7 @@ Relevant keys:
| Home Assistant | 192.168.20.30 | 8123 | Devices and timers. |
| MQTT | 192.168.20.13 | 1883 | Voice topics. |
| Apprise | 192.168.20.35 | 8210 | Notifications. |
| Hub | not allocated | — | This service. |
| Hub | 192.168.20.13 | 8787 | This service. Proposed default (`HUB_PORT`). |
## Config Paths

8
docs/outline/03-code-map.md
View File

@@ -16,9 +16,11 @@ central_ai_llm_master/
diagrams/ rendered images
archify/ Archify JSON input
outline/ AI context documents
ask-contract.md Hub to project interface
hub-api.md frozen inbound API (v1)
vikunja-tasks.json human task list
src/ Hub service code (to build)
main.* HTTP entry point
main.go HTTP entry point
hear/ takes voice or text
understand/ LLM intent routing
check/ authorization and approval
@@ -36,11 +38,11 @@ central_ai_llm_master/
| `POST /approve` | Admin app confirms a restricted action. |
| `GET /health` | Liveness check. |
The API contract is not final. See `hub_brief.md`.
The inbound API is frozen. See `docs/hub-api.md`.
## Primary Dependencies
- HTTP server (Go or Python — decide before build).
- HTTP server (Go 1.25, standard library `net/http`).
- HTTP client for OmniRoute, Home Assistant, Paperclip.
- MQTT client for voice topics.
- Tavily API client for web search.