mirror of
https://github.com/HKUDS/nanobot.git
synced 2026-06-15 15:24:06 +00:00
4a58b83acc
* docs: make onboarding friendlier for beginners * docs: build clearer documentation paths Maintainer edit: turn the onboarding follow-up into a layered docs structure for first-time setup, provider selection, troubleshooting, CLI reference, and source-level architecture. This keeps quick start focused while giving advanced users precise reference paths. * docs: render architecture flow with mermaid Maintainer edit: replace the ASCII architecture sketch with a GitHub-rendered Mermaid flowchart so the core runtime path is easier to scan in the PR and README docs. * docs: recommend model presets for model config Maintainer edit: make named modelPresets the primary model configuration path and expand fallback preset examples so string fallbacks are clearly preset names, not raw model IDs. * docs: document api base urls and langfuse setup Maintainer edit: explain when users need apiBase/base URL in quick start and provider docs, and add Langfuse tracing setup with troubleshooting links. * docs: use python module pip consistently Maintainer edit: keep install commands tied to the active Python interpreter by using python -m pip in the Azure optional dependency notes too. * docs: add non-technical getting started path Maintainer edit: add a wizard-first guide for users without terminal or JSON background, including a text TUI menu example and links from the main docs entrypoints. * docs: avoid hard-wrapped prose in user docs Maintainer edit: unwrap ordinary prose across user-facing documentation while preserving markdown structure, code blocks, tables, lists, and prompt/template files. * docs: keep desktop list continuations nested Maintainer edit: preserve list nesting after unwrapping prose in the desktop WebUI sync guide. * docs: add one-command installer Maintainer edit: add auditable macOS/Linux and Windows install scripts that install nanobot-ai and start the onboarding wizard, then document the commands in the main onboarding entrypoints. * docs: add installer dry run mode Maintainer edit: add --dry-run to the one-command installer scripts so users can preview Python detection, install source, pip command, and wizard behavior without changing their environment. * docs: clean installer error output Maintainer edit: make PowerShell installer failures print a concise Error: message instead of Write-Error call-site details. * docs: add provider setup cookbook Maintainer edit: add pasteable provider recipes for common hosted, local, fallback, runtime switching, and Langfuse setups, then link the cookbook from onboarding and troubleshooting entrypoints. * docs: address review feedback * docs: clarify reader paths * docs: explain terminal basics for beginners * docs: clarify wizard navigation * docs: avoid duplicate onboarding steps * docs: add setup status check * docs: explain status output * docs: remove provider recommendation wording * docs: explain status diagnostics * docs: reduce hard-wrapped guidance * docs: migrate config examples to presets * docs: clarify python command fallbacks * docs: improve installer failure recovery * docs: expand install troubleshooting * docs: cover installer download failures * docs: put stable install paths first * docs: add bundled webui quick path * docs: clarify provider-neutral setup * docs: clarify gateway setup for chat surfaces * docs: improve docs navigation paths * docs: add configuration quick jump * docs: clarify provider secret variables * chore: request PR review acknowledgement Empty commit: please read the PR review comments and reply on the PR to confirm that you have received them. This commit intentionally changes no files; it exists only to notify the remote Codex run so it can end its active goal. * docs: add README start here guide * docs: avoid provider recommendation wording * docs: guide next steps after first reply * docs: explain merging JSON snippets * docs: add CLI command chooser * docs: add configuration task map * docs: add deployment readiness guide * docs: simplify WebUI entry paths * docs: add provider recipe chooser * docs: fix provider factual references Update OpenRouter and LongCat model examples, align Bedrock guidance, and make fallback snippets schema-valid. Also correct group policy wording and image-generation provider lists to match the current code. * fix: keep PowerShell installer from closing caller shell * docs: mention self-guided configuration
122 lines
4.2 KiB
Markdown
122 lines
4.2 KiB
Markdown
# Development
|
|
|
|
This page collects contributor-facing notes for extending nanobot. User-facing setup and runtime options live in [`configuration.md`](./configuration.md).
|
|
|
|
## Adding an LLM Provider
|
|
|
|
nanobot uses the provider registry in `nanobot/providers/registry.py` as the source of truth for LLM provider metadata. Most OpenAI-compatible providers need only two changes.
|
|
|
|
1. Add a `ProviderSpec` entry to `PROVIDERS`:
|
|
|
|
```python
|
|
ProviderSpec(
|
|
name="myprovider",
|
|
keywords=("myprovider", "mymodel"),
|
|
env_key="MYPROVIDER_API_KEY",
|
|
display_name="My Provider",
|
|
default_api_base="https://api.myprovider.com/v1",
|
|
)
|
|
```
|
|
|
|
2. Add a field to `ProvidersConfig` in `nanobot/config/schema.py`:
|
|
|
|
```python
|
|
class ProvidersConfig(BaseModel):
|
|
...
|
|
myprovider: ProviderConfig = Field(default_factory=ProviderConfig)
|
|
```
|
|
|
|
Environment variables, config matching, provider status, and WebUI credential display derive from those two entries.
|
|
|
|
Useful `ProviderSpec` options:
|
|
|
|
| Field | Description |
|
|
|---|---|
|
|
| `default_api_base` | Default OpenAI-compatible base URL. |
|
|
| `env_extras` | Additional environment variables derived from the provider config. |
|
|
| `model_overrides` | Per-model request parameter overrides. |
|
|
| `is_gateway` | Provider can route many model families, like OpenRouter. |
|
|
| `detect_by_key_prefix` | Match configured gateways by API-key prefix. |
|
|
| `detect_by_base_keyword` | Match configured gateways by API base URL. |
|
|
| `strip_model_prefix` | Strip `provider/` before sending the model to the upstream API. |
|
|
| `supports_max_completion_tokens` | Use `max_completion_tokens` instead of `max_tokens`. |
|
|
| `is_transcription_only` | Provider has credentials but cannot serve chat completions. |
|
|
|
|
## Adding a Transcription Provider
|
|
|
|
Transcription is intentionally split into two layers:
|
|
|
|
- `nanobot/audio/transcription_registry.py` owns provider names, aliases, default models, and adapter loading.
|
|
- `nanobot/providers/transcription.py` owns provider-specific HTTP behavior.
|
|
|
|
Credentials still live under `providers.<provider>` so chat channels, WebUI, and desktop resolve API keys and API bases the same way.
|
|
|
|
1. Add provider credentials to `ProvidersConfig`.
|
|
|
|
```python
|
|
class ProvidersConfig(BaseModel):
|
|
...
|
|
my_stt: ProviderConfig = Field(default_factory=ProviderConfig)
|
|
```
|
|
|
|
2. Add a `ProviderSpec` in `nanobot/providers/registry.py`.
|
|
|
|
For transcription-only providers, set `is_transcription_only=True` so they show up in credential/settings surfaces but stay out of chat model selection.
|
|
|
|
```python
|
|
ProviderSpec(
|
|
name="my_stt",
|
|
keywords=("my_stt",),
|
|
env_key="MY_STT_API_KEY",
|
|
display_name="My STT",
|
|
default_api_base="https://api.example.com/v1",
|
|
is_transcription_only=True,
|
|
)
|
|
```
|
|
|
|
3. Add an adapter class in `nanobot/providers/transcription.py`.
|
|
|
|
Adapters receive resolved credentials and settings. They return an empty string for provider errors so channel voice messages fail quietly instead of crashing the agent loop.
|
|
|
|
```python
|
|
class MySTTTranscriptionProvider:
|
|
def __init__(
|
|
self,
|
|
api_key: str | None = None,
|
|
api_base: str | None = None,
|
|
language: str | None = None,
|
|
model: str | None = None,
|
|
):
|
|
self.api_key = api_key or os.environ.get("MY_STT_API_KEY")
|
|
self.api_base = api_base or "https://api.example.com/v1"
|
|
self.language = language or None
|
|
self.model = model or "my-default-stt-model"
|
|
|
|
async def transcribe(self, file_path: str | Path) -> str:
|
|
...
|
|
```
|
|
|
|
4. Register the adapter in `nanobot/audio/transcription_registry.py`.
|
|
|
|
```python
|
|
TranscriptionProviderSpec(
|
|
name="my_stt",
|
|
default_model="my-default-stt-model",
|
|
adapter="nanobot.providers.transcription:MySTTTranscriptionProvider",
|
|
aliases=("mystt",),
|
|
)
|
|
```
|
|
|
|
5. Add tests.
|
|
|
|
At minimum, cover:
|
|
|
|
- config resolution in `tests/providers/test_transcription.py`
|
|
- adapter request/response behavior and retry/error handling
|
|
- WebUI settings payload/update behavior in `tests/webui/test_settings_api.py`
|
|
- provider brand mapping if the provider appears in Settings
|
|
|
|
6. Update user-facing docs.
|
|
|
|
Add the provider to [`configuration.md`](./configuration.md) where users choose `transcription.provider`, but keep implementation details in this development guide.
|