Scope

This document defines all models that cross the wire between Zoltraak Gateway and Ollama and ComfyUI. All models are grounded in actual API payloads confirmed from Ollama documentation. These models live in the adapters layer and are never exposed to gateway clients directly.

There are two Ollama instances in this system. The GPU pod Ollama handles vision, story generation, chat, and coding. The local Ollama on the home server handles intent classification for the Telegram bot only. Both use the same Ollama API so the same integration models apply to both, with different base URLs configured per instance.

Ollama Integration Models

Ollama base URL (GPU pod): configured via zoltraak.ollama.gpu-pod.url Ollama base URL (home server): configured via zoltraak.ollama.local.url

Confirmed endpoints used:

• Generate: POST /api/generate
• Chat: POST /api/chat
• List models: GET /api/tags
• Health: GET / returns "Ollama is running" as plain text with 200

classDiagram
    class OllamaGenerateRequest {
        String model
        String prompt
        List~String~ images
        boolean stream
        String system
    }

    class OllamaGenerateResponse {
        String model
        String createdAt
        String response
        boolean done
        String doneReason
    }

    class OllamaChatRequest {
        String model
        List~OllamaMessage~ messages
        boolean stream
    }

    class OllamaMessage {
        String role
        String content
        List~String~ images
    }

    class OllamaChatResponse {
        String model
        String createdAt
        OllamaMessage message
        boolean done
        String doneReason
    }

    class OllamaTagsResponse {
        List~OllamaModel~ models
    }

    class OllamaModel {
        String name
        String model
        String modifiedAt
        Long size
        String digest
    }

    OllamaChatRequest --> OllamaMessage
    OllamaChatResponse --> OllamaMessage
    OllamaTagsResponse --> OllamaModel

ComfyUI Integration Models

ComfyUI base URL: resolved from PodConnectionDetails.comfyUrl at runtime.

Confirmed endpoints used:

• Submit job: POST /prompt
• Poll job status: GET /history/{promptId}
• Retrieve image: GET /view?filename={filename}

ComfyUI is optional in the Fantasy Mode pipeline. These models are only used when the client sets includeImageGeneration to true in FantasyRequest.

classDiagram
    class ComfyUIPromptRequest {
        Map~String_Object~ prompt
        String clientId
    }

    class ComfyUIPromptResponse {
        String promptId
    }

    class ComfyUIHistoryEntry {
        String status
        Map~String_Object~ outputs
    }