nuqloud-ai/docs/ARCHITECTURE.md

# Talk AI Architecture

This document maps the current app structure to the main runtime flows.

## Application Stack

Talk AI is a standard Nextcloud app:

- PHP services and controllers use the Nextcloud app framework.
- Vue 2.7 components provide the personal app, admin settings, and Talk Smart Picker UI.
- Database access uses Nextcloud mapper entities.
- Background work runs through Nextcloud jobs.
- External model calls use OpenAI-compatible HTTP APIs.

The app ID is `educai`. The PHP namespace is `OCA\EducAI`.

## Main Backend Components

| Component | Responsibility |
| --- | --- |
| `BotService` | Bot lifecycle, permission-aware bot access, Talk message orchestration, tool loadout selection |
| `LLMClient` | Chat completions, streaming, model listing, endpoint-aware model resolution, fallback retry |
| `AgentExecutor` | Tool-calling loop, tool-call parsing, iteration cap, final answer synthesis |
| `SettingsService` | Admin settings, encrypted secrets, runtime defaults |
| `TalkHandler` | Incoming Talk webhook handling |
| `TalkBotRegistrationService` | Shared Talk bot registration and refresh |
| `BuiltInToolProvider` | RAG, room-document, attachment, and wiki tool definitions and execution |
| `ToolRegistry` | MCP tool lookup and per-bot tool assignment loading |
| `McpClient` | MCP `tools/list` and `tools/call` requests |
| `RagIngestionService` | Source resolution, text extraction, chunking, embedding, and source status updates |
| `WikiService` | Persistent personal bot wiki reads, writes, search, and log maintenance |
| `WikiRootRegistryService` | Registry of physical wiki roots and bot assignments for scalable file-event matching |
| `WikiFileEventSyncService` | Lightweight file-event handler that matches node ancestors and queues wiki index sync jobs |

## Frontend Entry Points

| File | Surface |
| --- | --- |
| `src/views/PersonalBots.vue` | Personal app view, pending approvals, bot lists |
| `src/components/BotForm.vue` | Bot creation and editing |
| `src/components/AdminSettings.vue` | Admin configuration accordions |
| `src/components/BotPickerElement.vue` | Talk Smart Picker entry |
| `src/components/BotPickerModal.vue` | Talk room bot activation UI |

The Vite build writes app bundles into `js/`.

## Data Model

Core tables use the `educai_` prefix in code and the configured Nextcloud database prefix at runtime.

| Table | Purpose |
| --- | --- |
| `educai_bots` | Bot configuration, visibility, model, temperature, approval state |
| `educai_conversations` | Stored user and assistant messages |
| `educai_settings` | Global provider, RAG, tool, rate-limit, and memory settings |
| `educai_bot_sources` | Bot-attached RAG files and folders |
| `educai_embeddings` | RAG chunks and embeddings |
| `educai_tools` | Admin-registered MCP endpoints |
| `educai_bot_tools` | Bot-to-tool assignments |
| `educai_chat_rooms` | Per-room onboarding and response mode |
| `educai_room_document_sources` | Talk-room document sources |
| `educai_room_document_embeddings` | Talk-room document embeddings |
| `educai_wiki_roots` | Physical wiki root folders keyed by stable Nextcloud node ID |
| `educai_wiki_root_bots` | Active mapping from personal bots to registered wiki roots |

## Message Flow

1. Nextcloud Talk sends a signed webhook to `/apps/educai/webhook/talk`.
2. `TalkHandler` parses the message, room, mention, and attachments.
3. `BotService` resolves the mentioned bot and checks visibility plus approval state.
4. The service builds the effective system prompt, onboarding context, attachment hints, RAG instructions, and wiki instructions.
5. `BotService` loads enabled built-in and MCP tools for the bot.
6. If tools are available, `AgentExecutor` runs the model-tool loop. If no tools are available, `LLMClient` sends a direct chat request.
7. The final assistant response is sent back to Talk.
8. Talk AI stores the user message and final assistant message. Tool results stay in memory for the turn.

## Tool Loop

`AgentExecutor` exposes OpenAI-style tool schemas to the model. It supports native tool calls plus fallback parsing for models that emit tool-call JSON or XML in text.

The hard cap is `MAX_TOOL_ITERATIONS = 50`. A request can ask for a smaller cap, but not a larger one. This prevents runaway agent loops while keeping complex workflows possible.

For audio-only Talk messages with exactly one audio attachment and no image or document attachment, `BotService` passes an initial tool choice for `attachment_transcribe_audio`. The executor applies that preference to the first tool step only.

## Model Endpoint Resolution

`LLMClient` resolves model references before each request:

- `primary:<model>` uses the primary endpoint.
- `secondary:<model>` uses the secondary endpoint.
- raw model names use the primary endpoint unless the configured model list resolves them to another endpoint.

Model listing combines primary and secondary `/v1/models` results when the secondary endpoint is configured.

Fallback retry uses the configured fallback model only for eligible timeout or connection failures. Streaming fallback runs only before the first streamed chunk.

## RAG And Embeddings

RAG source ingestion runs through background jobs. The ingestion service resolves files through Nextcloud storage APIs, extracts text, chunks content, requests embeddings, and stores vectors in JSON-compatible form.

The built-in `rag_search_documents` tool embeds the model-generated query and computes cosine similarity in PHP. This keeps the implementation database-portable.

## Wiki Index Sync

Wiki tools keep root-level `index.md` pages up to date through `WikiService::syncIndexForRoot()`. The same index sync also runs after manual file changes, but the hot file-event path stays small enough for large instances:

1. `BotService` refreshes the wiki-root registry whenever bot tools are created or updated. The registry stores the physical root folder node ID, root path, location, optional Collectives ID, and the active bot assignment.
2. App enable and app upgrade enqueue `RebuildWikiRootRegistryJob`, which backfills registry entries for existing personal bots with wiki tools.
3. `WikiFileEventListener` receives Nextcloud node events for create, write, delete, rename, and copy.
4. `WikiFileEventSyncService` ignores managed files (`index.md`, `log.md`, `schema.md`), hidden paths, and unsupported extensions. For the remaining node, it collects ancestor node IDs through `getId()` and `getParent()`.
5. The service queries only `educai_wiki_roots.root_node_id IN (...)` and schedules at most one `SyncWikiRootIndexJob` per root. `IJobList::has()` prevents duplicate queued jobs, and a five-second delay groups editor and upload spikes.
6. `SyncWikiRootIndexJob` loads the registered root, calls `WikiService::syncIndexForRoot()`, and writes either `last_synced_at` or `last_error` back to `educai_wiki_roots`.

The matching key is the Nextcloud node ID, not the path. `root_path` is stored for debugging and as a CLI background-job fallback when `IRootFolder::getById()` cannot resolve a folder in the current execution context. This keeps personal-file wikis and Collectives-backed wikis on the same path-independent implementation.

## Talk Bot Registration

The app includes a repair step that registers the shared `Talk AI` Talk bot when the app is installed or enabled. `SettingsService` refreshes registration after relevant settings changes. `TalkEnabledListener` handles the case where Talk becomes available after Talk AI.

If automatic registration cannot run because the environment lacks a usable CLI or Talk admin session, admins can still register the Talk bot with `occ talk:bot:install`.

## Security Notes

- Webhook requests use an HMAC secret.
- Admin secrets are encrypted through `CredentialService`.
- Nextcloud permission checks protect file access.
- Shared bot publishing uses approval checks tied to scopes.
- Admins register MCP tools centrally before users can assign them.
- Tool iteration, output size, request timeout, and rate-limit controls reduce blast radius.