# caru-ini/novelai-sdk architecture

> Architecture diagram of the GitHub repository caru-ini/novelai-sdk, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/caru-ini/novelai-sdk
- Repository: https://github.com/caru-ini/novelai-sdk

## Overview

##### Project type and purpose
- This is an open-source Python SDK (“novelai-sdk”) whose sole purpose is to provide a modern, type-safe interface to NovelAI’s image-generation REST API.
- It exposes a high-level client API (with Pydantic validation, convenience methods, PIL support and SSE streaming) and a low-level HTTP wrapper for advanced use.

##### File structure
- Top-level:
‣ src/novelai/ – main package
· __main__.py – CLI entrypoint if invoked as `python -m novelai`
· _api/client.py – low-level HTTP/REST interface (HTTPX calls, JSON marshaling)
· _client/client.py – high-level façade, exposes .image.generate(), .image.generate_stream(), etc.
· _utils/ – helpers (image I/O, converter functions)
· constants/ – enumeration of models, samplers, sizes, schedules, presets
· types/ – Pydantic models for request/response schemas (api/image.py, user/image.py)
· exceptions.py – custom exceptions for error handling
‣ examples/ – usage demos
‣ docs/ – images and Markdown docs
‣ tests/ – placeholder for future tests
‣ pyproject.toml, pre-commit, CI configs – build and style enforcement

##### README for additional insights
- Confirms two-layer API design (high-level vs. low-level).
- Lists dependencies: HTTPX, Pillow, Pydantic v2, python-dotenv.
- Describes features: streaming (SSE), ControlNet, character references, multi-character positioning.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Application
    subgraph "User Application"
        UserApp["Usage Demos"]:::examples
    end
    click UserApp "https://github.com/caru-ini/novelai-sdk/tree/main/examples/"

    %% SDK Internals
    subgraph "SDK Internals" 
        direction TB

        CLI["CLI Entrypoint (__main__.py)"]:::sdkInternals
        click CLI "https://github.com/caru-ini/novelai-sdk/blob/main/src/novelai/__main__.py"

        subgraph "High-Level SDK Layer" 
            HL["_client.client"]:::sdkInternals
        end
        click HL "https://github.com/caru-ini/novelai-sdk/blob/main/src/novelai/_client/client.py"

        subgraph "Low-Level SDK Layer"
            LL["_api.client"]:::sdkInternals
        end
        click LL "https://github.com/caru-ini/novelai-sdk/blob/main/src/novelai/_api/client.py"

        subgraph "Utilities & Helpers"
            Conv["converter.py"]:::sdkInternals
            ImgUtil["image.py"]:::sdkInternals
        end
        click Conv "https://github.com/caru-ini/novelai-sdk/blob/main/src/novelai/_utils/converter.py"
        click ImgUtil "https://github.com/caru-ini/novelai-sdk/blob/main/src/novelai/_utils/image.py"

        subgraph "Constants"
            Models["models.py"]:::sdkInternals
            Samplers["samplers.py"]:::sdkInternals
            Sizes["sizes.py"]:::sdkInternals
            Schedule["noise_schedule.py"]:::sdkInternals
            Position["position.py"]:::sdkInternals
            Presets["presets.py"]:::sdkInternals
        end
        click Models "https://github.com/caru-ini/novelai-sdk/blob/main/src/novelai/constants/models.py"
        click Samplers "https://github.com/caru-ini/novelai-sdk/blob/main/src/novelai/constants/samplers.py"
        click Sizes "https://github.com/caru-ini/novelai-sdk/blob/main/src/novelai/constants/sizes.py"
        click Schedule "https://github.com/caru-ini/novelai-sdk/blob/main/src/novelai/constants/noise_schedule.py"
        click Position "https://github.com/caru-ini/novelai-sdk/blob/main/src/novelai/constants/position.py"
        click Presets "https://github.com/caru-ini/novelai-sdk/blob/main/src/novelai/constants/presets.py"

        subgraph "Pydantic Types"
            APITypes["api/image.py"]:::sdkInternals
            UserTypes["user/image.py"]:::sdkInternals
        end
        click APITypes "https://github.com/caru-ini/novelai-sdk/blob/main/src/novelai/types/api/image.py"
        click UserTypes "https://github.com/caru-ini/novelai-sdk/blob/main/src/novelai/types/user/image.py"

        Exceptions["exceptions.py"]:::sdkInternals
        click Exceptions "https://github.com/caru-ini/novelai-sdk/blob/main/src/novelai/exceptions.py"
    end

    %% Third-Party Dependencies
    subgraph "Third-Party Libraries"
        HTTPX["HTTPX"]:::thirdParty
        Pydantic["Pydantic v2"]:::thirdParty
        Pillow["Pillow"]:::thirdParty
        SSE["SSE Streaming"]:::thirdParty
        DotEnv["python-dotenv"]:::thirdParty
    end

    %% External Service
    NovelAIAPI["NovelAI Image-Generation API"]:::external

    %% Configuration & CI
    subgraph "Project Config & CI"
        PyProj["pyproject.toml"]:::config
        PreCommit[".pre-commit-config.yaml"]:::config
        CI["ci.yaml"]:::config
    end

    %% Data Flows
    UserApp -->|"import & invoke"| HL
    CLI -->|"python -m novelai"| HL
    HL -->|"validate via Pydantic"| APITypes
    HL -->|"validate via Pydantic"| UserTypes
    HL -->|"delegate call"| LL
    LL -->|"HTTP JSON"| NovelAIAPI
    LL -->|"SSE stream"| NovelAIAPI
    NovelAIAPI -->|"JSON/B64 chunks"| LL
    LL -->|"wrap errors"| Exceptions
    LL -->|"convert to PIL"| ImgUtil
    LL -->|"convert formats"| Conv

    HL -->|"use presets/models"| Models
    HL -->|"use presets/models"| Samplers
    LL -->|"use sizes/schedule"| Sizes
    LL -->|"use positions"| Position
    HL -->|"use presets"| Presets

    LL -->|"HTTPX client"| HTTPX
    HL -->|"validation DI"| Pydantic
    ImgUtil -->|"image ops"| Pillow
    LL -->|"stream handler"| SSE
    HL -->|"env load"| DotEnv

    %% Config usage
    CLI -->|"configuration"| PyProj
    CLI -->|"pre-commit hooks"| PreCommit
    CLI -->|"CI pipeline"| CI

    %% Classes
    classDef sdkInternals fill:#E8F1FC,stroke:#4A90E2,stroke-width:1px;
    classDef thirdParty fill:#FFF4E5,stroke:#FFA500,stroke-width:1px;
    classDef external fill:#F0F9F0,stroke:#2E8B57,stroke-width:2px,stroke-dasharray: 5 5;
    classDef examples fill:#FDF6E3,stroke:#B58900,stroke-width:1px;
    classDef config fill:#F9F9F9,stroke:#666666,stroke-width:1px;
```
