# ai-vidence/antakia architecture

> Architecture diagram of the GitHub repository ai-vidence/antakia, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ai-vidence/antakia
- Repository: https://github.com/ai-vidence/antakia

## Overview

##### Project type and purpose
- It ships as a pip-installable package, provides a CLI entry point, a GUI module, and Jupyter notebook integrations.

##### File structure
- Top-level:
- src/antakia/antakia.py → core engine, entry points for CLI and notebook API
- src/antakia/config.py → configuration loader (.env support)
- src/antakia/utils → helper functions (data loaders, stats, logging utilities)
- src/antakia/gui → GUI implementation (app bar, tabs, high-dimensional explorer, graphical elements)
- “dev/” scripts: helpers to run demos and examples locally
- “docs/” and “examples/”: user-facing tutorials, data, and demonstration notebooks
- CI/CD: GitHub workflows (lint, pytest, build & publish), Dockerfile to bundle Jupyter Lab demo

##### Key insights from README
- Two modes of use:
a) CLI/API mode (pure Python or notebooks)
b) GUI mode (interactive mosaic explorer)
- Sends anonymous usage logs by default to a remote logging server (configurable via .env)
- Packaged for PyPI, Dockerized for Jupyter demo

##### Main components
a. User Interfaces
- CLI / Python API (calls into core engine)
- Jupyter Notebook Kernel (imports antakia)
- Desktop GUI Module (tkinter/PyQt-based under src/antakia/gui)
b. Core Engine
- antakia.py: orchestrates region-splitting algorithm, rule extraction
- config loader: handles .env, CLI flags
- utils: data ingestion, stats computations, logging hooks
c. Data Layer
- Input: user’s ML model + dataset
- Output: rule sets, region definitions, visual artifacts
d. Visualization Layer
- GUI subcomponents: app bar, tabs, sliders, tables, figure displays
- Notebook renderers: inline plots, tables
e. External Services
- Anonymous Usage Logging Server (HTTP endpoint)
- PyPI Registry (package distribution)
- Docker Container runtime (Jupyter Lab server)
f. DevOps / CI
- GitHub Actions (pylint, pytest, build & publish to PyPI)
- Pre-commit and formatting scripts
- Release scripts (version bump, publish)

##### Relationships and data flows
- User invokes CLI/API or launches GUI/notebook → Core Engine
- Core Engine loads config → loads user model + data → runs region-split algorithm → returns explanation objects
- Explanation objects → passed to Visualization Layer (GUI or Notebook) → user interacts → may trigger further core computations
- Core Engine logs usage events → HTTP POST to remote logging service
- Packaging pipelines (CI) build/test/publish new releases to PyPI; Dockerfile bundles Jupyter Lab environment

##### Architectural patterns & design principles
- Modular separation:
- Core algorithm (antakia.py) is independent of UI
- GUI is organized in subpackages (tabs, graphical_elements) following MVC-like structure:
– Model: explanation objects
– View: widgets, charts
– Controller: GUI event handlers
- Config-driven behavior (.env) for logging and feature flags
- Extensive test suite validating core and GUI components separately

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Interfaces Layer
    subgraph "User Interfaces"
        CLI_API["CLI / Python API"]:::ui
        Notebook["Jupyter Notebook Kernel"]:::ui
        GUI["Desktop GUI Module"]:::ui
    end

    %% Core Logic Layer
    subgraph "Core Engine & Utilities"
        CoreEngine["Core Engine<br/>(region-splitting)"]:::core
        ConfigLoader["Configuration Loader"]:::core
        subgraph "Utilities"
            Checks["checks.py"]:::core
            Colors["colors.py"]:::core
            DummyDatasets["dummy_datasets.py"]:::core
            ExamplesUtil["examples.py"]:::core
            LoggingUtils["logging_utils.py"]:::core
            OtherUtils["other_utils.py"]:::core
            Stats["stats.py"]:::core
        end
    end

    %% Data Layer
    DataInput["Input: Model & Dataset"]:::data
    DataOutput["Output: Rules & Visuals"]:::data

    %% Visualization Layer
    subgraph "Visualization Layer"
        NotebookRenderers["Notebook Renderers"]:::ui
        GUIComponents["GUI Subcomponents"]:::ui
    end

    %% External Services
    subgraph "External Services"
        LoggingService["Anonymous Usage Logging Service"]:::ext
        PyPIRegistry["PyPI Registry"]:::ext
        DockerRuntime["Docker Container Runtime"]:::ext
    end

    %% DevOps / CI
    subgraph "DevOps / CI"
        GH_Pylint[".github/workflows/pylint.yaml"]:::dev
        GH_Pytest[".github/workflows/pytest.yaml"]:::dev
        GH_PyPI[".github/workflows/pypi.yaml"]:::dev
        GH_YAPF[".github/workflows/yapf.yaml"]:::dev
        PreCommit["Pre-commit & Quality Scripts"]:::dev
        ReleaseScripts["Release & Versioning Scripts"]:::dev
        DevHelpers["Dev Helpers & Demo Runners"]:::dev
        Documentation["Documentation & Tutorials"]:::dev
        DockerfileNode["Dockerfile"]:::dev
    end

    %% Connections
    CLI_API -->|"invokes"| CoreEngine
    Notebook -->|"imports & calls"| CoreEngine
    GUI -->|"launches"| CoreEngine

    CoreEngine -->|"loads config"| ConfigLoader
    CoreEngine -->|"uses utils"| Checks
    CoreEngine -->|"uses utils"| Colors
    CoreEngine -->|"uses utils"| DummyDatasets
    CoreEngine -->|"uses utils"| ExamplesUtil
    CoreEngine -->|"uses utils"| LoggingUtils
    CoreEngine -->|"uses utils"| OtherUtils
    CoreEngine -->|"uses utils"| Stats

    DataInput -->|"provided to"| CoreEngine
    CoreEngine -->|"generates"| DataOutput
    DataOutput -->|"rendered by"| NotebookRenderers
    DataOutput -->|"rendered by"| GUIComponents

    CoreEngine -->|"logs usage via HTTP"| LoggingService

    GH_Pylint -->|"builds/tests"| PyPIRegistry
    GH_Pytest -->|"builds/tests"| PyPIRegistry
    GH_PyPI -->|"publishes"| PyPIRegistry
    GH_YAPF -->|"formats"| PyPIRegistry

    GH_PyPI -->|"builds"| DockerRuntime
    DockerfileNode -->|"bundles Jupyter Lab"| DockerRuntime

    DevHelpers -->|"runs demos"| CoreEngine
    ReleaseScripts -->|"updates versions"| PyPIRegistry
    PreCommit -->|"enforces quality"| CoreEngine
    Documentation -->|"onboards users"| CLI_API

    %% Click Events
    click CLI_API "https://github.com/ai-vidence/antakia/blob/dev/src/antakia/antakia.py"
    click CoreEngine "https://github.com/ai-vidence/antakia/blob/dev/src/antakia/antakia.py"
    click ConfigLoader "https://github.com/ai-vidence/antakia/blob/dev/src/antakia/config.py"
    click Checks "https://github.com/ai-vidence/antakia/blob/dev/src/antakia/utils/checks.py"
    click Colors "https://github.com/ai-vidence/antakia/blob/dev/src/antakia/utils/colors.py"
    click DummyDatasets "https://github.com/ai-vidence/antakia/blob/dev/src/antakia/utils/dummy_datasets.py"
    click ExamplesUtil "https://github.com/ai-vidence/antakia/blob/dev/src/antakia/utils/examples.py"
    click LoggingUtils "https://github.com/ai-vidence/antakia/blob/dev/src/antakia/utils/logging_utils.py"
    click OtherUtils "https://github.com/ai-vidence/antakia/blob/dev/src/antakia/utils/other_utils.py"
    click Stats "https://github.com/ai-vidence/antakia/blob/dev/src/antakia/utils/stats.py"
    click GUI "https://github.com/ai-vidence/antakia/blob/dev/src/antakia/gui/gui.py"
    click Notebook "https://github.com/ai-vidence/antakia/blob/dev/src/antakia/antakia.py"
    click NotebookRenderers "https://github.com/ai-vidence/antakia/tree/dev/examples/"
    click NotebookRenderers "https://github.com/ai-vidence/antakia/blob/dev/dev/widget_lab.ipynb"
    click GUIComponents "https://github.com/ai-vidence/antakia/tree/dev/src/antakia/gui/app_bar/"
    click GUIComponents "https://github.com/ai-vidence/antakia/tree/dev/src/antakia/gui/graphical_elements/"
    click GUIComponents "https://github.com/ai-vidence/antakia/tree/dev/src/antakia/gui/helpers/"
    click GUIComponents "https://github.com/ai-vidence/antakia/tree/dev/src/antakia/gui/high_dim_exp/"
    click GUIComponents "https://github.com/ai-vidence/antakia/tree/dev/src/antakia/gui/tabs/"
    click GUIComponents "https://github.com/ai-vidence/antakia/blob/dev/src/antakia/gui/widget_utils.py"
    click GUIComponents "https://github.com/ai-vidence/antakia/blob/dev/src/antakia/gui/splash_screen.py"
    click LoggingService "https://github.com/ai-vidence/antakia/blob/dev/src/antakia/utils/logging_utils.py"
    click DockerfileNode "https://github.com/ai-vidence/antakia/tree/dev/Dockerfile"
    click GH_Pylint "https://github.com/ai-vidence/antakia/blob/dev/.github/workflows/pylint.yaml"
    click GH_Pytest "https://github.com/ai-vidence/antakia/blob/dev/.github/workflows/pytest.yaml"
    click GH_PyPI "https://github.com/ai-vidence/antakia/blob/dev/.github/workflows/pypi.yaml"
    click GH_YAPF "https://github.com/ai-vidence/antakia/blob/dev/.github/workflows/yapf.yaml"
    click PreCommit "https://github.com/ai-vidence/antakia/blob/dev/.pre-commit-config.yaml"
    click ReleaseScripts "https://github.com/ai-vidence/antakia/blob/dev/scripts/release.sh"
    click DevHelpers "https://github.com/ai-vidence/antakia/blob/dev/dev/run.py"
    click Documentation "https://github.com/ai-vidence/antakia/tree/dev/docs/"
    
    %% Styles
    classDef ui fill:#D0E6FF,stroke:#0366d6,stroke-width:1px;
    classDef core fill:#E6FFEA,stroke:#2F8F2F,stroke-width:1px;
    classDef data fill:#FFF4E6,stroke:#FFA500,stroke-width:1px;
    classDef ext fill:#FFEFD5,stroke:#FF8C00,stroke-width:1px;
    classDef dev fill:#F0F0F0,stroke:#606060,stroke-width:1px;
```
