GeneralBots/botbook
2
2
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
botbook/src/appendix-external-services/catalog.md

318 lines
9.4 KiB
Markdown
Raw Normal View History

- Split from botserver.
2025-12-03 19:56:35 -03:00
# Service Catalog
This catalog provides detailed information about every external service that General Bots integrates with.
## LLM Providers
### OpenAI
| Property | Value |
|----------|-------|
| **Service URL** | `https://api.openai.com/v1` |
| **Config Key** | `llm-provider=openai` |
docs: comprehensive keyword documentation update Completed stub files: - keyword-soap.md - SOAP web service integration - keyword-merge-pdf.md - PDF merging (MERGE PDF with spaces) - keyword-kb-statistics.md - KB statistics overview - keyword-kb-collection-stats.md - Per-collection stats - keyword-kb-documents-count.md - Document counting - keyword-kb-documents-added-since.md - Recent document tracking - keyword-kb-list-collections.md - Collection listing - keyword-kb-storage-size.md - Storage monitoring Updated documentation: - keyword-generate-pdf.md - Updated to GENERATE PDF (spaces) - keyword-delete.md - Rewritten for unified DELETE - keyword-delete-http.md - Redirects to unified DELETE - keyword-delete-file.md - Redirects to unified DELETE - All keyword docs updated to use spaces not underscores PROMPT.md updates: - Added keyword naming rules (NO underscores) - Added keyword mapping table - Added quick reference for all keywords - Added error handling examples TASKS.md created: - Comprehensive discrepancy report - Model name update tracking (17 files) - Config parameter documentation - Architecture notes Key clarifications: - GENERATE FROM TEMPLATE = FILL keyword - GENERATE WITH PROMPT = LLM keyword - ON ERROR RESUME NEXT now implemented - DELETE is unified (HTTP/DB/File auto-detect)
2025-12-05 09:55:38 -03:00
| **API Key Config** | `llm-api-key` (stored in Vault) |
- Split from botserver.
2025-12-03 19:56:35 -03:00
| **Documentation** | [platform.openai.com/docs](https://platform.openai.com/docs) |
| **BASIC Keywords** | `LLM` |
docs: comprehensive keyword documentation update Completed stub files: - keyword-soap.md - SOAP web service integration - keyword-merge-pdf.md - PDF merging (MERGE PDF with spaces) - keyword-kb-statistics.md - KB statistics overview - keyword-kb-collection-stats.md - Per-collection stats - keyword-kb-documents-count.md - Document counting - keyword-kb-documents-added-since.md - Recent document tracking - keyword-kb-list-collections.md - Collection listing - keyword-kb-storage-size.md - Storage monitoring Updated documentation: - keyword-generate-pdf.md - Updated to GENERATE PDF (spaces) - keyword-delete.md - Rewritten for unified DELETE - keyword-delete-http.md - Redirects to unified DELETE - keyword-delete-file.md - Redirects to unified DELETE - All keyword docs updated to use spaces not underscores PROMPT.md updates: - Added keyword naming rules (NO underscores) - Added keyword mapping table - Added quick reference for all keywords - Added error handling examples TASKS.md created: - Comprehensive discrepancy report - Model name update tracking (17 files) - Config parameter documentation - Architecture notes Key clarifications: - GENERATE FROM TEMPLATE = FILL keyword - GENERATE WITH PROMPT = LLM keyword - ON ERROR RESUME NEXT now implemented - DELETE is unified (HTTP/DB/File auto-detect)
2025-12-05 09:55:38 -03:00
| **Supported Models** | `gpt-5`, `gpt-oss-120b`, `gpt-oss-20b` |
- Split from botserver.
2025-12-03 19:56:35 -03:00
### Groq
| Property | Value |
|----------|-------|
| **Service URL** | `https://api.groq.com/openai/v1` |
| **Config Key** | `llm-provider=groq` |
docs: comprehensive keyword documentation update Completed stub files: - keyword-soap.md - SOAP web service integration - keyword-merge-pdf.md - PDF merging (MERGE PDF with spaces) - keyword-kb-statistics.md - KB statistics overview - keyword-kb-collection-stats.md - Per-collection stats - keyword-kb-documents-count.md - Document counting - keyword-kb-documents-added-since.md - Recent document tracking - keyword-kb-list-collections.md - Collection listing - keyword-kb-storage-size.md - Storage monitoring Updated documentation: - keyword-generate-pdf.md - Updated to GENERATE PDF (spaces) - keyword-delete.md - Rewritten for unified DELETE - keyword-delete-http.md - Redirects to unified DELETE - keyword-delete-file.md - Redirects to unified DELETE - All keyword docs updated to use spaces not underscores PROMPT.md updates: - Added keyword naming rules (NO underscores) - Added keyword mapping table - Added quick reference for all keywords - Added error handling examples TASKS.md created: - Comprehensive discrepancy report - Model name update tracking (17 files) - Config parameter documentation - Architecture notes Key clarifications: - GENERATE FROM TEMPLATE = FILL keyword - GENERATE WITH PROMPT = LLM keyword - ON ERROR RESUME NEXT now implemented - DELETE is unified (HTTP/DB/File auto-detect)
2025-12-05 09:55:38 -03:00
| **API Key Config** | `llm-api-key` (stored in Vault) |
- Split from botserver.
2025-12-03 19:56:35 -03:00
| **Documentation** | [console.groq.com/docs](https://console.groq.com/docs) |
| **BASIC Keywords** | `LLM` |
docs: comprehensive keyword documentation update Completed stub files: - keyword-soap.md - SOAP web service integration - keyword-merge-pdf.md - PDF merging (MERGE PDF with spaces) - keyword-kb-statistics.md - KB statistics overview - keyword-kb-collection-stats.md - Per-collection stats - keyword-kb-documents-count.md - Document counting - keyword-kb-documents-added-since.md - Recent document tracking - keyword-kb-list-collections.md - Collection listing - keyword-kb-storage-size.md - Storage monitoring Updated documentation: - keyword-generate-pdf.md - Updated to GENERATE PDF (spaces) - keyword-delete.md - Rewritten for unified DELETE - keyword-delete-http.md - Redirects to unified DELETE - keyword-delete-file.md - Redirects to unified DELETE - All keyword docs updated to use spaces not underscores PROMPT.md updates: - Added keyword naming rules (NO underscores) - Added keyword mapping table - Added quick reference for all keywords - Added error handling examples TASKS.md created: - Comprehensive discrepancy report - Model name update tracking (17 files) - Config parameter documentation - Architecture notes Key clarifications: - GENERATE FROM TEMPLATE = FILL keyword - GENERATE WITH PROMPT = LLM keyword - ON ERROR RESUME NEXT now implemented - DELETE is unified (HTTP/DB/File auto-detect)
2025-12-05 09:55:38 -03:00
| **Supported Models** | `llama-4-scout`, `llama-4-maverick`, `qwen3`, `mixtral-8x22b` |
- Split from botserver.
2025-12-03 19:56:35 -03:00
### Anthropic
| Property | Value |
|----------|-------|
| **Service URL** | `https://api.anthropic.com/v1` |
| **Config Key** | `llm-provider=anthropic` |
docs: comprehensive keyword documentation update Completed stub files: - keyword-soap.md - SOAP web service integration - keyword-merge-pdf.md - PDF merging (MERGE PDF with spaces) - keyword-kb-statistics.md - KB statistics overview - keyword-kb-collection-stats.md - Per-collection stats - keyword-kb-documents-count.md - Document counting - keyword-kb-documents-added-since.md - Recent document tracking - keyword-kb-list-collections.md - Collection listing - keyword-kb-storage-size.md - Storage monitoring Updated documentation: - keyword-generate-pdf.md - Updated to GENERATE PDF (spaces) - keyword-delete.md - Rewritten for unified DELETE - keyword-delete-http.md - Redirects to unified DELETE - keyword-delete-file.md - Redirects to unified DELETE - All keyword docs updated to use spaces not underscores PROMPT.md updates: - Added keyword naming rules (NO underscores) - Added keyword mapping table - Added quick reference for all keywords - Added error handling examples TASKS.md created: - Comprehensive discrepancy report - Model name update tracking (17 files) - Config parameter documentation - Architecture notes Key clarifications: - GENERATE FROM TEMPLATE = FILL keyword - GENERATE WITH PROMPT = LLM keyword - ON ERROR RESUME NEXT now implemented - DELETE is unified (HTTP/DB/File auto-detect)
2025-12-05 09:55:38 -03:00
| **API Key Config** | `llm-api-key` (stored in Vault) |
- Split from botserver.
2025-12-03 19:56:35 -03:00
| **Documentation** | [docs.anthropic.com](https://docs.anthropic.com) |
| **BASIC Keywords** | `LLM` |
docs: comprehensive keyword documentation update Completed stub files: - keyword-soap.md - SOAP web service integration - keyword-merge-pdf.md - PDF merging (MERGE PDF with spaces) - keyword-kb-statistics.md - KB statistics overview - keyword-kb-collection-stats.md - Per-collection stats - keyword-kb-documents-count.md - Document counting - keyword-kb-documents-added-since.md - Recent document tracking - keyword-kb-list-collections.md - Collection listing - keyword-kb-storage-size.md - Storage monitoring Updated documentation: - keyword-generate-pdf.md - Updated to GENERATE PDF (spaces) - keyword-delete.md - Rewritten for unified DELETE - keyword-delete-http.md - Redirects to unified DELETE - keyword-delete-file.md - Redirects to unified DELETE - All keyword docs updated to use spaces not underscores PROMPT.md updates: - Added keyword naming rules (NO underscores) - Added keyword mapping table - Added quick reference for all keywords - Added error handling examples TASKS.md created: - Comprehensive discrepancy report - Model name update tracking (17 files) - Config parameter documentation - Architecture notes Key clarifications: - GENERATE FROM TEMPLATE = FILL keyword - GENERATE WITH PROMPT = LLM keyword - ON ERROR RESUME NEXT now implemented - DELETE is unified (HTTP/DB/File auto-detect)
2025-12-05 09:55:38 -03:00
| **Supported Models** | `claude-opus-4.5`, `claude-sonnet-4.5` |
- Split from botserver.
2025-12-03 19:56:35 -03:00
### Azure OpenAI
| Property | Value |
|----------|-------|
| **Service URL** | `https://{resource}.openai.azure.com/` |
| **Config Key** | `llm-provider=azure` |
docs: comprehensive keyword documentation update Completed stub files: - keyword-soap.md - SOAP web service integration - keyword-merge-pdf.md - PDF merging (MERGE PDF with spaces) - keyword-kb-statistics.md - KB statistics overview - keyword-kb-collection-stats.md - Per-collection stats - keyword-kb-documents-count.md - Document counting - keyword-kb-documents-added-since.md - Recent document tracking - keyword-kb-list-collections.md - Collection listing - keyword-kb-storage-size.md - Storage monitoring Updated documentation: - keyword-generate-pdf.md - Updated to GENERATE PDF (spaces) - keyword-delete.md - Rewritten for unified DELETE - keyword-delete-http.md - Redirects to unified DELETE - keyword-delete-file.md - Redirects to unified DELETE - All keyword docs updated to use spaces not underscores PROMPT.md updates: - Added keyword naming rules (NO underscores) - Added keyword mapping table - Added quick reference for all keywords - Added error handling examples TASKS.md created: - Comprehensive discrepancy report - Model name update tracking (17 files) - Config parameter documentation - Architecture notes Key clarifications: - GENERATE FROM TEMPLATE = FILL keyword - GENERATE WITH PROMPT = LLM keyword - ON ERROR RESUME NEXT now implemented - DELETE is unified (HTTP/DB/File auto-detect)
2025-12-05 09:55:38 -03:00
| **API Key Config** | `llm-api-key` (stored in Vault) |
- Split from botserver.
2025-12-03 19:56:35 -03:00
| **Documentation** | [learn.microsoft.com/azure/ai-services/openai](https://learn.microsoft.com/azure/ai-services/openai) |
| **BASIC Keywords** | `LLM` |
docs: comprehensive keyword documentation update Completed stub files: - keyword-soap.md - SOAP web service integration - keyword-merge-pdf.md - PDF merging (MERGE PDF with spaces) - keyword-kb-statistics.md - KB statistics overview - keyword-kb-collection-stats.md - Per-collection stats - keyword-kb-documents-count.md - Document counting - keyword-kb-documents-added-since.md - Recent document tracking - keyword-kb-list-collections.md - Collection listing - keyword-kb-storage-size.md - Storage monitoring Updated documentation: - keyword-generate-pdf.md - Updated to GENERATE PDF (spaces) - keyword-delete.md - Rewritten for unified DELETE - keyword-delete-http.md - Redirects to unified DELETE - keyword-delete-file.md - Redirects to unified DELETE - All keyword docs updated to use spaces not underscores PROMPT.md updates: - Added keyword naming rules (NO underscores) - Added keyword mapping table - Added quick reference for all keywords - Added error handling examples TASKS.md created: - Comprehensive discrepancy report - Model name update tracking (17 files) - Config parameter documentation - Architecture notes Key clarifications: - GENERATE FROM TEMPLATE = FILL keyword - GENERATE WITH PROMPT = LLM keyword - ON ERROR RESUME NEXT now implemented - DELETE is unified (HTTP/DB/File auto-detect)
2025-12-05 09:55:38 -03:00
### Google (Gemini)
| Property | Value |
|----------|-------|
| **Service URL** | `https://generativelanguage.googleapis.com/v1` |
| **Config Key** | `llm-provider=google` |
| **API Key Config** | `llm-api-key` (stored in Vault) |
| **Documentation** | [ai.google.dev/docs](https://ai.google.dev/docs) |
| **BASIC Keywords** | `LLM` |
| **Supported Models** | `gemini-3-pro`, `gemini-2.5-pro`, `gemini-2.5-flash` |
### xAI (Grok)
| Property | Value |
|----------|-------|
| **Service URL** | `https://api.x.ai/v1` |
| **Config Key** | `llm-provider=xai` |
| **API Key Config** | `llm-api-key` (stored in Vault) |
| **Documentation** | [docs.x.ai](https://docs.x.ai) |
| **BASIC Keywords** | `LLM` |
| **Supported Models** | `grok-4` |
### DeepSeek
| Property | Value |
|----------|-------|
| **Service URL** | `https://api.deepseek.com/v1` |
| **Config Key** | `llm-provider=deepseek` |
| **API Key Config** | `llm-api-key` (stored in Vault) |
| **Documentation** | [platform.deepseek.com/docs](https://platform.deepseek.com/docs) |
| **BASIC Keywords** | `LLM` |
docs: Update model names to latest (GPT-5, Claude 4.5, DeepSeek-R3) - Update all model references across 14+ documentation files - GPT-4.1 → GPT-5, GPT-5 mini - Claude Sonnet/Opus → Claude Sonnet 4.5, Claude Opus 4.5 - DeepSeek-R1 → DeepSeek-R3 - Add Template: Attendance CRM to SUMMARY.md - Update attendant.csv docs with multi-channel columns - Update TASKS.md with completed model updates
2025-12-05 14:54:59 -03:00
| **Supported Models** | `deepseek-v3.1`, `deepseek-r3` |
docs: comprehensive keyword documentation update Completed stub files: - keyword-soap.md - SOAP web service integration - keyword-merge-pdf.md - PDF merging (MERGE PDF with spaces) - keyword-kb-statistics.md - KB statistics overview - keyword-kb-collection-stats.md - Per-collection stats - keyword-kb-documents-count.md - Document counting - keyword-kb-documents-added-since.md - Recent document tracking - keyword-kb-list-collections.md - Collection listing - keyword-kb-storage-size.md - Storage monitoring Updated documentation: - keyword-generate-pdf.md - Updated to GENERATE PDF (spaces) - keyword-delete.md - Rewritten for unified DELETE - keyword-delete-http.md - Redirects to unified DELETE - keyword-delete-file.md - Redirects to unified DELETE - All keyword docs updated to use spaces not underscores PROMPT.md updates: - Added keyword naming rules (NO underscores) - Added keyword mapping table - Added quick reference for all keywords - Added error handling examples TASKS.md created: - Comprehensive discrepancy report - Model name update tracking (17 files) - Config parameter documentation - Architecture notes Key clarifications: - GENERATE FROM TEMPLATE = FILL keyword - GENERATE WITH PROMPT = LLM keyword - ON ERROR RESUME NEXT now implemented - DELETE is unified (HTTP/DB/File auto-detect)
2025-12-05 09:55:38 -03:00
### Mistral AI
| Property | Value |
|----------|-------|
| **Service URL** | `https://api.mistral.ai/v1` |
| **Config Key** | `llm-provider=mistral` |
| **API Key Config** | `llm-api-key` (stored in Vault) |
| **Documentation** | [docs.mistral.ai](https://docs.mistral.ai) |
| **BASIC Keywords** | `LLM` |
| **Supported Models** | `mixtral-8x22b` |
- Split from botserver.
2025-12-03 19:56:35 -03:00
---
## Weather Services
### OpenWeatherMap
| Property | Value |
|----------|-------|
| **Service URL** | `https://api.openweathermap.org/data/2.5` |
| **Config Key** | `weather-api-key` |
| **Documentation** | [openweathermap.org/api](https://openweathermap.org/api) |
| **BASIC Keywords** | `WEATHER` |
| **Free Tier** | 1,000 calls/day |
| **Required Plan** | Free or higher |
**Example Usage:**
```basic
weather = WEATHER "Seattle"
TALK weather
```
---
## Messaging Channels
### WhatsApp Business API
| Property | Value |
|----------|-------|
| **Service URL** | `https://graph.facebook.com/v17.0` |
| **Config Keys** | `whatsapp-api-key`, `whatsapp-phone-number-id`, `whatsapp-business-account-id` |
| **Documentation** | [developers.facebook.com/docs/whatsapp](https://developers.facebook.com/docs/whatsapp) |
| **BASIC Keywords** | `SEND WHATSAPP`, `SEND FILE` (WhatsApp) |
| **Webhook URL** | `/api/channels/whatsapp/webhook` |
### Microsoft Teams
| Property | Value |
|----------|-------|
| **Service URL** | `https://smba.trafficmanager.net/apis` |
| **Config Keys** | `teams-app-id`, `teams-app-password`, `teams-tenant-id` |
| **Documentation** | [learn.microsoft.com/microsoftteams/platform](https://learn.microsoft.com/microsoftteams/platform) |
| **BASIC Keywords** | `SEND TEAMS`, `SEND FILE` (Teams) |
| **Webhook URL** | `/api/channels/teams/messages` |
### Instagram Messaging
| Property | Value |
|----------|-------|
| **Service URL** | `https://graph.facebook.com/v17.0` |
| **Config Keys** | `instagram-access-token`, `instagram-page-id`, `instagram-account-id` |
| **Documentation** | [developers.facebook.com/docs/instagram-api](https://developers.facebook.com/docs/instagram-api) |
| **BASIC Keywords** | `SEND INSTAGRAM` |
| **Webhook URL** | `/api/channels/instagram/webhook` |
### Telegram
| Property | Value |
|----------|-------|
| **Service URL** | `https://api.telegram.org/bot{token}` |
| **Config Keys** | `telegram-bot-token` |
| **Documentation** | [core.telegram.org/bots/api](https://core.telegram.org/bots/api) |
| **BASIC Keywords** | `SEND TELEGRAM` |
| **Webhook URL** | `/api/channels/telegram/webhook` |
---
## Storage Services
### S3-Compatible Storage
General Bots uses S3-compatible object storage. Configuration is **automatically managed** by the Directory service (Zitadel).
| Property | Value |
|----------|-------|
| **Local Default** | MinIO on port 9000 |
| **Management** | Directory service (automatic) |
| **Console Port** | 9001 (when using MinIO) |
| **BASIC Keywords** | `GET` (file retrieval) |
**Compatible Services:**
- MinIO (default local installation)
- Backblaze B2
- Wasabi
- DigitalOcean Spaces
- Cloudflare R2
- Any S3-compatible provider
Storage credentials are provisioned and rotated automatically by the Directory service. No manual configuration required.
---
## Directory Services
### Zitadel (Identity Provider)
| Property | Value |
|----------|-------|
| **Local Default** | Port 8080 |
| **Environment Variables** | `DIRECTORY_URL`, `DIRECTORY_CLIENT_ID`, `DIRECTORY_CLIENT_SECRET` |
| **Documentation** | [zitadel.com/docs](https://zitadel.com/docs) |
| **Purpose** | User authentication, SSO, OAuth2/OIDC, service credential management |
The Directory service manages:
- User authentication
- Service credentials (database, storage, cache)
- OAuth applications
- Role-based access control
---
## Email Services
### Stalwart Mail Server
| Property | Value |
|----------|-------|
| **Ports** | 25 (SMTP), 993 (IMAPS), 587 (Submission) |
| **Management** | Directory service (automatic) |
| **Documentation** | [stalw.art/docs](https://stalw.art/docs) |
| **BASIC Keywords** | `SEND MAIL` |
Email accounts are created and managed through the Directory service.
### External IMAP/SMTP
| Property | Value |
|----------|-------|
| **Config Keys** | `smtp-server`, `smtp-port`, `imap-server`, `imap-port`, `email-username`, `email-password` |
| **BASIC Keywords** | `SEND MAIL` |
| **Supported Providers** | Gmail, Outlook, custom SMTP/IMAP |
**Gmail Configuration Example (in config.csv):**
```csv
smtp-server,smtp.gmail.com
smtp-port,587
imap-server,imap.gmail.com
imap-port,993
```
---
## Local Services (BotModels)
### Image Generation
| Property | Value |
|----------|-------|
| **Service URL** | `http://localhost:5000` (default) |
| **Config Keys** | `botmodels-enabled`, `botmodels-url` |
| **BASIC Keywords** | `IMAGE` |
| **Requires** | BotModels service running |
### Video Generation
| Property | Value |
|----------|-------|
| **Service URL** | `http://localhost:5000` (default) |
| **Config Keys** | `botmodels-enabled`, `botmodels-url` |
| **BASIC Keywords** | `VIDEO` |
| **Requires** | BotModels service running, GPU recommended |
### Audio Generation (TTS)
| Property | Value |
|----------|-------|
| **Service URL** | `http://localhost:5000` (default) |
| **Config Keys** | `botmodels-enabled`, `botmodels-url` |
| **BASIC Keywords** | `AUDIO` |
| **Requires** | BotModels service running |
### Vision/Captioning
| Property | Value |
|----------|-------|
| **Service URL** | `http://localhost:5000` (default) |
| **Config Keys** | `botmodels-enabled`, `botmodels-url` |
| **BASIC Keywords** | `SEE` |
| **Requires** | BotModels service running |
---
## Internal Services
These services are deployed locally as part of the General Bots stack. All are managed by the Directory service:
| Service | Default Port | Purpose | Management |
|---------|-------------|---------|------------|
| PostgreSQL | 5432 | Primary database | Vault |
| Qdrant | 6333 | Vector storage for KB | Vault |
| Cache | 6379 | Caching | Vault |
| Stalwart | 25, 993 | Email server (optional) | Vault |
| BotModels | 5000 | AI model inference | config.csv |
---
## Service Health Checks
All services can be checked via the monitoring API:
```
GET /api/monitoring/services
```
Response includes status for all configured external services.
---
## Troubleshooting
### Common Issues
1. **API Key Invalid** - Verify key in `config.csv`, ensure no trailing whitespace
2. **Rate Limited** - Check service quotas, implement caching with `SET BOT MEMORY`
3. **Connection Timeout** - Verify network access to external URLs
4. **Service Unavailable** - Check service status pages
### Debug Logging
Enable trace logging to see external API calls:
```bash
RUST_LOG=trace ./botserver
```
Reference in a new issue Copy permalink