# alt-f4-dev/phluxai.jl architecture

> Architecture diagram of the GitHub repository alt-f4-dev/phluxai.jl, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/alt-f4-dev/phluxai.jl
- Repository: https://github.com/alt-f4-dev/phluxai.jl

## Overview

PhluxAI.jl is a local multimodal agent framework. Users create or resume model and physics-agent sessions, converse through Ollama, and can request image generation through a separately configured ComfyUI workflow. Sessions also support persistence, artifacts, multimodal inputs, and sandboxed Julia/Python tools. The README documents these product capabilities, but no source excerpts were provided, so the graph omits unverified internal call relationships and cites documented links only.

Main entry points: [`src/core/ModelSession.jl`](https://github.com/alt-f4-dev/phluxai.jl/blob/main/src/core/ModelSession.jl) (Session API), [`src/PhluxAI.jl`](https://github.com/alt-f4-dev/phluxai.jl/blob/main/src/PhluxAI.jl) (Interactive Macros), [`src/tools/JupyTools.jl`](https://github.com/alt-f4-dev/phluxai.jl/blob/main/src/tools/JupyTools.jl) (Jupy Tools), [`src/core/ImageInterface.jl`](https://github.com/alt-f4-dev/phluxai.jl/blob/main/src/core/ImageInterface.jl) (Image Interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Julia Interface"]
  node_macros["Interactive Macros<br/>[PhluxAI.jl]"]
end

subgraph group_sessions["Sessions And Agents"]
  node_session_api["Session API<br/>[ModelSession.jl]"]
  node_agent["Physics Assistant"]
  node_artifacts["Session Artifacts<br/>[Artifacts.jl]"]
  node_protocol["Protocol Types<br/>[ProtocolTypes.jl]"]
end

subgraph group_models["Conversation Models"]
  node_ollama["Ollama Client<br/>[OllamaClient.jl]"]
  node_capabilities["Model Capabilities"]
end

subgraph group_images["Image Generation"]
  node_image_interface["Image Interface<br/>[ImageInterface.jl]"]
  node_comfy_workflow["Comfy Workflow<br/>[ComfyWorkflow.jl]"]
  node_comfy_client["Comfy Client<br/>[ComfyClient.jl]"]
  node_comfy_lifecycle["Comfy Lifecycle<br/>[ComfyLifecycle.jl]"]
end

subgraph group_tools["Tool Execution"]
  node_jupy_tools["Jupy Tools<br/>[JupyTools.jl]"]
  node_sandbox["Tool Sandbox<br/>[Sandbox.jl]"]
end

node_user(("User"))
node_ollama_service(("Ollama"))
node_comfy_service(("ComfyUI"))
node_jupy(("Jupy And Jupip"))

node_user -->|"starts session"| node_macros
node_macros -->|"creates session"| node_session_api
node_macros -->|"starts agent"| node_agent
node_user -->|"resumes session"| node_session_api
node_session_api -->|"uses model"| node_ollama
node_ollama -->|"requests inference"| node_ollama_service
node_session_api -->|"supports artifacts"| node_artifacts
node_user -->|"requests images"| node_image_interface
node_session_api -->|"generates images"| node_image_interface
node_image_interface -->|"uses workflow"| node_comfy_workflow
node_comfy_workflow -->|"submits workflow"| node_comfy_client
node_comfy_client -->|"sends requests"| node_comfy_service
node_comfy_lifecycle -->|"manages service"| node_comfy_service
node_session_api -->|"supports tools"| node_jupy_tools
node_jupy_tools -->|"executes sandboxed"| node_sandbox
node_jupy_tools -->|"runs Julia Python"| node_jupy

click node_macros "https://github.com/alt-f4-dev/phluxai.jl/blob/main/src/PhluxAI.jl"
click node_session_api "https://github.com/alt-f4-dev/phluxai.jl/blob/main/src/core/ModelSession.jl"
click node_agent "https://github.com/alt-f4-dev/phluxai.jl/blob/main/src/agents/PhysicalAssistant.jl"
click node_artifacts "https://github.com/alt-f4-dev/phluxai.jl/blob/main/src/core/Artifacts.jl"
click node_protocol "https://github.com/alt-f4-dev/phluxai.jl/blob/main/src/core/ProtocolTypes.jl"
click node_ollama "https://github.com/alt-f4-dev/phluxai.jl/blob/main/src/core/OllamaClient.jl"
click node_capabilities "https://github.com/alt-f4-dev/phluxai.jl/blob/main/src/core/ModelCapabilities.jl"
click node_image_interface "https://github.com/alt-f4-dev/phluxai.jl/blob/main/src/core/ImageInterface.jl"
click node_comfy_workflow "https://github.com/alt-f4-dev/phluxai.jl/blob/main/src/core/ComfyWorkflow.jl"
click node_comfy_client "https://github.com/alt-f4-dev/phluxai.jl/blob/main/src/core/ComfyClient.jl"
click node_comfy_lifecycle "https://github.com/alt-f4-dev/phluxai.jl/blob/main/src/core/ComfyLifecycle.jl"
click node_jupy_tools "https://github.com/alt-f4-dev/phluxai.jl/blob/main/src/tools/JupyTools.jl"
click node_sandbox "https://github.com/alt-f4-dev/phluxai.jl/blob/main/src/tools/Sandbox.jl"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_macros,node_user,node_comfy_service toneBlue
class node_session_api,node_agent,node_artifacts,node_protocol toneAmber
class node_ollama,node_capabilities toneMint
class node_image_interface,node_comfy_workflow,node_comfy_client,node_comfy_lifecycle toneRose
class node_jupy_tools,node_sandbox,node_ollama_service,node_jupy toneIndigo
```

## Components

### Julia Interface

- [Interactive Macros](https://github.com/alt-f4-dev/phluxai.jl/blob/main/src/PhluxAI.jl): `src/PhluxAI.jl`

### Sessions And Agents

- [Session API](https://github.com/alt-f4-dev/phluxai.jl/blob/main/src/core/ModelSession.jl): `src/core/ModelSession.jl`
- [Physics Assistant](https://github.com/alt-f4-dev/phluxai.jl/blob/main/src/agents/PhysicalAssistant.jl): `src/agents/PhysicalAssistant.jl`
- [Session Artifacts](https://github.com/alt-f4-dev/phluxai.jl/blob/main/src/core/Artifacts.jl): `src/core/Artifacts.jl`
- [Protocol Types](https://github.com/alt-f4-dev/phluxai.jl/blob/main/src/core/ProtocolTypes.jl): `src/core/ProtocolTypes.jl`

### Conversation Models

- [Ollama Client](https://github.com/alt-f4-dev/phluxai.jl/blob/main/src/core/OllamaClient.jl): `src/core/OllamaClient.jl`
- [Model Capabilities](https://github.com/alt-f4-dev/phluxai.jl/blob/main/src/core/ModelCapabilities.jl): `src/core/ModelCapabilities.jl`

### Image Generation

- [Image Interface](https://github.com/alt-f4-dev/phluxai.jl/blob/main/src/core/ImageInterface.jl): `src/core/ImageInterface.jl`
- [Comfy Workflow](https://github.com/alt-f4-dev/phluxai.jl/blob/main/src/core/ComfyWorkflow.jl): `src/core/ComfyWorkflow.jl`
- [Comfy Client](https://github.com/alt-f4-dev/phluxai.jl/blob/main/src/core/ComfyClient.jl): `src/core/ComfyClient.jl`
- [Comfy Lifecycle](https://github.com/alt-f4-dev/phluxai.jl/blob/main/src/core/ComfyLifecycle.jl): `src/core/ComfyLifecycle.jl`

### Tool Execution

- [Jupy Tools](https://github.com/alt-f4-dev/phluxai.jl/blob/main/src/tools/JupyTools.jl): `src/tools/JupyTools.jl`
- [Tool Sandbox](https://github.com/alt-f4-dev/phluxai.jl/blob/main/src/tools/Sandbox.jl): `src/tools/Sandbox.jl`

### Other components

- **User**
- **Ollama**
- **ComfyUI**
- **Jupy And Jupip**

## Connections

- User → Interactive Macros: starts session (evidence: `README.md`)
- Interactive Macros → Session API: creates session (evidence: `README.md`)
- Interactive Macros → Physics Assistant: starts agent (evidence: `README.md`)
- User → Session API: resumes session (evidence: `README.md`)
- Session API → Ollama Client: uses model (evidence: `README.md`)
- Ollama Client → Ollama: requests inference (evidence: `README.md`)
- Session API → Session Artifacts: supports artifacts (evidence: `README.md`)
- User → Image Interface: requests images (evidence: `README.md`)
- Session API → Image Interface: generates images (evidence: `README.md`)
- Image Interface → Comfy Workflow: uses workflow (evidence: `README.md`)
- Comfy Workflow → Comfy Client: submits workflow (evidence: `README.md`)
- Comfy Client → ComfyUI: sends requests (evidence: `README.md`)
- Comfy Lifecycle → ComfyUI: manages service (evidence: `README.md`)
- Session API → Jupy Tools: supports tools (evidence: `README.md`)
- Jupy Tools → Tool Sandbox: executes sandboxed (evidence: `README.md`)
- Jupy Tools → Jupy And Jupip: runs Julia Python (evidence: `README.md`)