lhumina_code/hero_aibroker
23
0
Fork 0
Code Issues 3 Pull requests Projects Releases 1 Packages Wiki Activity Actions

implement std practices #44

New issue
Open
opened 2026-04-04 19:51:30 +00:00 by despiegk · 5 comments
despiegk commented 2026-04-04 19:51:30 +00:00
Owner
Copy link

use skills

/hero_crates_best_practices_check
/hero_proc_service_selfstart
/hero_ui_dashboard

large refactor needed

make sure all functionality is in hero_aibroker_server
or if needed hero_aibroker_lib and make modular there

the the hero_aibroker_server has only openrpc interface

hero_aibroker_sdk is openrpc macro towards the openrpc interface

the hero_aibroker crate is the cmdline and uses hero_aibroker_sdk

make sure the openrpc interface is complete and all is there

use skills /hero_crates_best_practices_check /hero_proc_service_selfstart /hero_ui_dashboard large refactor needed make sure all functionality is in hero_aibroker_server or if needed hero_aibroker_lib and make modular there the the hero_aibroker_server has only openrpc interface hero_aibroker_sdk is openrpc macro towards the openrpc interface the hero_aibroker crate is the cmdline and uses hero_aibroker_sdk make sure the openrpc interface is complete and all is there
despiegk commented 2026-04-04 20:12:13 +00:00
Author
Owner
Copy link

Implementation Spec — Issue #44: Implement Std Practices

Summary

Large refactor to align with Hero standard practices:

  1. Rename hero_aibroker library → hero_aibroker_lib (frees the name for CLI)
  2. hero_aibroker_server = pure OpenRPC only — remove all /v1/* HTTP REST routes
  3. Add ai.* RPC methods — chat, TTS, STT, embeddings accessible via JSON-RPC
  4. Update openrpc.json — complete spec with all methods
  5. hero_aibroker_ui translates HTTP→RPC — OpenAI-compatible HTTP translation layer using SDK
  6. hero_aibroker CLI uses SDK — replace raw HTTP with typed SDK calls
  7. Rename hero_aibroker_daemon/ → hero_aibroker/ — package name matches binary name

Architecture After Refactor

hero_aibroker_lib      (library — all business logic)
       │
hero_aibroker_server   (pure OpenRPC JSON-RPC 2.0 — NO HTTP REST)
       │
hero_aibroker_sdk      (openrpc_client! macro → typed async client)
   ▲         ▲
   │         └── hero_aibroker  (CLI, --start/--stop + interactive)
hero_aibroker_ui       (HTML dashboard + /v1/* HTTP→RPC translation)

New OpenRPC Methods

Method Description
ai.chat Non-streaming chat completion
ai.models List models (OpenAI format)
ai.tts Text-to-speech (returns base64 audio)
ai.transcribe Speech-to-text (accepts base64 audio)
ai.embed Create embeddings

Plus missing admin methods: providers.list/add_key/remove_key, mcp.add_server/remove_server

Implementation Steps

  1. Rename lib crate hero_aibroker → hero_aibroker_lib, update all references
  2. Add ai.* RPC handlers to server + update openrpc.json
  3. Remove HTTP REST routes from server (delete src/api/chat.rs, tts.rs, stt.rs, embedding.rs, models.rs)
  4. Add SDK + OpenAI translation to UI (src/openai.rs)
  5. Refactor hero_aibroker CLI to use SDK instead of raw HTTP
  6. Rename hero_aibroker_daemon/ → hero_aibroker/
  7. Update examples with new AI methods

Key Design Decisions

  • Non-streaming RPC for chat: JSON-RPC is request/response only. ai.chat returns complete response. SSE streaming stays in the UI translation layer.
  • TTS base64 over RPC: Binary audio base64-encoded in JSON. UI decodes before returning HTTP response.
  • STT multipart stays in UI: Multipart form upload is HTTP-only. UI base64-encodes bytes before calling RPC.
  • Keep info.title in openrpc.json unchanged to avoid struct name churn.

Generated by Claude Code — awaiting approval before implementation

## Implementation Spec — Issue #44: Implement Std Practices ### Summary Large refactor to align with Hero standard practices: 1. **Rename `hero_aibroker` library → `hero_aibroker_lib`** (frees the name for CLI) 2. **`hero_aibroker_server` = pure OpenRPC only** — remove all `/v1/*` HTTP REST routes 3. **Add `ai.*` RPC methods** — chat, TTS, STT, embeddings accessible via JSON-RPC 4. **Update `openrpc.json`** — complete spec with all methods 5. **`hero_aibroker_ui` translates HTTP→RPC** — OpenAI-compatible HTTP translation layer using SDK 6. **`hero_aibroker` CLI uses SDK** — replace raw HTTP with typed SDK calls 7. **Rename `hero_aibroker_daemon/` → `hero_aibroker/`** — package name matches binary name --- ### Architecture After Refactor ``` hero_aibroker_lib (library — all business logic) │ hero_aibroker_server (pure OpenRPC JSON-RPC 2.0 — NO HTTP REST) │ hero_aibroker_sdk (openrpc_client! macro → typed async client) ▲ ▲ │ └── hero_aibroker (CLI, --start/--stop + interactive) hero_aibroker_ui (HTML dashboard + /v1/* HTTP→RPC translation) ``` --- ### New OpenRPC Methods | Method | Description | |--------|-------------| | `ai.chat` | Non-streaming chat completion | | `ai.models` | List models (OpenAI format) | | `ai.tts` | Text-to-speech (returns base64 audio) | | `ai.transcribe` | Speech-to-text (accepts base64 audio) | | `ai.embed` | Create embeddings | Plus missing admin methods: `providers.list/add_key/remove_key`, `mcp.add_server/remove_server` --- ### Implementation Steps 1. Rename lib crate `hero_aibroker` → `hero_aibroker_lib`, update all references 2. Add `ai.*` RPC handlers to server + update `openrpc.json` 3. Remove HTTP REST routes from server (delete `src/api/chat.rs`, `tts.rs`, `stt.rs`, `embedding.rs`, `models.rs`) 4. Add SDK + OpenAI translation to UI (`src/openai.rs`) 5. Refactor `hero_aibroker` CLI to use SDK instead of raw HTTP 6. Rename `hero_aibroker_daemon/` → `hero_aibroker/` 7. Update examples with new AI methods --- ### Key Design Decisions - **Non-streaming RPC for chat**: JSON-RPC is request/response only. `ai.chat` returns complete response. SSE streaming stays in the UI translation layer. - **TTS base64 over RPC**: Binary audio base64-encoded in JSON. UI decodes before returning HTTP response. - **STT multipart stays in UI**: Multipart form upload is HTTP-only. UI base64-encodes bytes before calling RPC. - **Keep `info.title`** in openrpc.json unchanged to avoid struct name churn. --- *Generated by Claude Code — awaiting approval before implementation*
despiegk commented 2026-04-04 20:15:56 +00:00
Author
Owner
Copy link

Spec Correction — Dual-Socket Server

The previous spec was wrong on one point: do NOT remove the REST routes.

The server keeps all REST compatibility (OpenAI, MCP, Anthropic) but binds two separate Unix sockets:

Two Sockets from One Server Binary

Socket Protocol Purpose
~/hero/var/sockets/hero_aibroker_server.sock Pure OpenRPC JSON-RPC Admin + AI methods via RPC
~/hero/var/sockets/hero_aibroker_server_rest.sock HTTP REST OpenAI-compatible + MCP + Anthropic REST

Both sockets share the same in-process AppState (same providers, registry, services, metrics, etc.).

Updated Architecture

hero_aibroker_lib      (business logic library)
       │
hero_aibroker_server   (single binary — two listeners)
  ├── hero_aibroker_server.sock      (OpenRPC JSON-RPC only)
  └── hero_aibroker_server_rest.sock (OpenAI/MCP/Anthropic REST)
       │
hero_aibroker_sdk      (openrpc_client! → connects to .sock)
hero_aibroker_ui       (HTML dashboard + proxies /v1/* to _rest.sock, /rpc to .sock)
hero_aibroker          (CLI, uses SDK over .sock)

What Changes

  • Server main.rs spawns two UnixListener tasks sharing the same AppState
  • No REST routes are removed
  • UI proxy routes: /rpc → server.sock, /v1/* → server_rest.sock
  • hero_aibroker_daemon registers both sockets in hero_proc health checks

Proceeding with implementation based on this corrected design.

## Spec Correction — Dual-Socket Server The previous spec was wrong on one point: **do NOT remove the REST routes**. The server keeps all REST compatibility (OpenAI, MCP, Anthropic) but binds **two separate Unix sockets**: ### Two Sockets from One Server Binary | Socket | Protocol | Purpose | |--------|----------|---------| | `~/hero/var/sockets/hero_aibroker_server.sock` | Pure OpenRPC JSON-RPC | Admin + AI methods via RPC | | `~/hero/var/sockets/hero_aibroker_server_rest.sock` | HTTP REST | OpenAI-compatible + MCP + Anthropic REST | Both sockets share the **same in-process AppState** (same providers, registry, services, metrics, etc.). ### Updated Architecture ``` hero_aibroker_lib (business logic library) │ hero_aibroker_server (single binary — two listeners) ├── hero_aibroker_server.sock (OpenRPC JSON-RPC only) └── hero_aibroker_server_rest.sock (OpenAI/MCP/Anthropic REST) │ hero_aibroker_sdk (openrpc_client! → connects to .sock) hero_aibroker_ui (HTML dashboard + proxies /v1/* to _rest.sock, /rpc to .sock) hero_aibroker (CLI, uses SDK over .sock) ``` ### What Changes - Server `main.rs` spawns **two** `UnixListener` tasks sharing the same `AppState` - No REST routes are removed - UI proxy routes: `/rpc` → `server.sock`, `/v1/*` → `server_rest.sock` - `hero_aibroker_daemon` registers both sockets in hero_proc health checks *Proceeding with implementation based on this corrected design.*
despiegk commented 2026-04-04 20:34:35 +00:00
Author
Owner
Copy link

Test Results

Check Status
cargo check --workspace PASS (0 errors, 1 harmless dead_code warning)
cargo test --workspace PASS (all tests passed, including SDK doctest)
## Test Results | Check | Status | |-------|--------| | `cargo check --workspace` | PASS (0 errors, 1 harmless `dead_code` warning) | | `cargo test --workspace` | PASS (all tests passed, including SDK doctest) |
despiegk commented 2026-04-04 20:34:49 +00:00
Author
Owner
Copy link

Final Implementation Summary

Architecture: Dual Unix Socket Design

The server now binds two Unix sockets sharing the same AppState:

Socket Path Purpose
RPC ~/hero/var/sockets/hero_aibroker_server.sock Pure OpenRPC JSON-RPC
REST ~/hero/var/sockets/hero_aibroker_server_rest.sock REST / OpenAI-compat

Files Changed

1. crates/hero_aibroker_server/src/main.rs

Binds both sockets sharing the same AppState.

2. crates/hero_aibroker_server/src/api/mod.rs

  • create_rpc_router() returns (Router, AppState) — serves /rpc, /health, /openrpc.json, /.well-known/heroservice.json
  • create_rest_router(state) — serves /v1/chat/completions, /v1/models, /v1/audio/speech, /v1/audio/transcriptions, /v1/embeddings, /metrics, /health
  • Added RPC handlers: ai.chat, ai.models, ai.tts, ai.transcribe, ai.embed

3. crates/hero_aibroker_server/openrpc.json

Added methods: ai.chat, ai.models, ai.tts, ai.transcribe, ai.embed, providers.list, mcp.add_server, mcp.remove_server.
Added schemas: Message, ChatResponse.

4. crates/hero_aibroker_ui/src/api/mod.rs

UI now proxies to two sockets:

  • /rpc, /openrpc.json → hero_aibroker_server.sock
  • /v1/*, /metrics, /health → hero_aibroker_server_rest.sock

5. crates/hero_aibroker_ui/src/main.rs

Passes both socket paths to the router.

6. crates/hero_aibroker/ (was hero_aibroker_daemon/)

Renamed package to hero_aibroker. CLI commands use AIBrokerAdminAPIClient SDK.

7. crates/hero_aibroker_lib/ (was crates/hero_aibroker/)

Library renamed to hero_aibroker_lib, freeing the hero_aibroker name for the CLI binary.

## Final Implementation Summary ### Architecture: Dual Unix Socket Design The server now binds **two Unix sockets** sharing the same `AppState`: | Socket | Path | Purpose | |--------|------|---------| | RPC | `~/hero/var/sockets/hero_aibroker_server.sock` | Pure OpenRPC JSON-RPC | | REST | `~/hero/var/sockets/hero_aibroker_server_rest.sock` | REST / OpenAI-compat | --- ### Files Changed #### 1. `crates/hero_aibroker_server/src/main.rs` Binds both sockets sharing the same `AppState`. #### 2. `crates/hero_aibroker_server/src/api/mod.rs` - `create_rpc_router()` returns `(Router, AppState)` — serves `/rpc`, `/health`, `/openrpc.json`, `/.well-known/heroservice.json` - `create_rest_router(state)` — serves `/v1/chat/completions`, `/v1/models`, `/v1/audio/speech`, `/v1/audio/transcriptions`, `/v1/embeddings`, `/metrics`, `/health` - Added RPC handlers: `ai.chat`, `ai.models`, `ai.tts`, `ai.transcribe`, `ai.embed` #### 3. `crates/hero_aibroker_server/openrpc.json` Added methods: `ai.chat`, `ai.models`, `ai.tts`, `ai.transcribe`, `ai.embed`, `providers.list`, `mcp.add_server`, `mcp.remove_server`. Added schemas: `Message`, `ChatResponse`. #### 4. `crates/hero_aibroker_ui/src/api/mod.rs` UI now proxies to **two sockets**: - `/rpc`, `/openrpc.json` → `hero_aibroker_server.sock` - `/v1/*`, `/metrics`, `/health` → `hero_aibroker_server_rest.sock` #### 5. `crates/hero_aibroker_ui/src/main.rs` Passes both socket paths to the router. #### 6. `crates/hero_aibroker/` (was `hero_aibroker_daemon/`) Renamed package to `hero_aibroker`. CLI commands use `AIBrokerAdminAPIClient` SDK. #### 7. `crates/hero_aibroker_lib/` (was `crates/hero_aibroker/`) Library renamed to `hero_aibroker_lib`, freeing the `hero_aibroker` name for the CLI binary.
despiegk commented 2026-04-04 20:41:56 +00:00
Author
Owner
Copy link

Implementation committed:

  • 70a4792 — feat: implement standard three-crate architecture
  • b6bd05b — feat: implement working CLI chat via ai.chat RPC

Browse: b6bd05b

Implementation committed: - `70a4792` — feat: implement standard three-crate architecture - `b6bd05b` — feat: implement working CLI chat via ai.chat RPC Browse: https://forge.ourworld.tf/lhumina_code/hero_aibroker/commit/b6bd05b
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
development
development_mik2
main
v0.1.0
Labels
Clear labels   
prio_critical

   
prio_low

   
type_bug

   
type_contact

   
type_issue

   
type_lead

   
type_question

   
type_story

   
type_task
No labels
prio_critical
prio_low
type_bug
type_contact
type_issue
type_lead
type_question
type_story
type_task
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
lhumina_code/hero_aibroker#44
No description provided.