README.md

---
license: mit
tags:
- desktop-application
- ai-tools
- dataset-management
- lora-training
- windows
---

# ADAM — AI Development and Automation Manager

ADAM is a local, safety-first desktop hub for orchestrating AI project tools.
It includes registered dataset, DDPM, and SDXL LoRA workflows with background
planning, approval gates, progress reporting, and persistent asset history.

![ADAM command center](docs/screenshots/command-center.png)

Dataset preparation, captioning, and preview placeholders remain clearly marked
as demo tools. The connected Dataset Collector, DDPM trainer, and Local SDXL
LoRA Trainer use real adapters and never fall back to simulated training.

Existing program folders can be connected from **Settings → Tool folders**.
ADAM stores only the path and scans for likely entry points; it does not copy or
modify the external project. Folder assignments can also be pasted into chat:

```text
DDPM Trainer: D:\AI\DDPM
Flow Matching Trainer: D:\AI\FlowMatchImageGenerator
```

On a new computer, install `requirements.txt` in your chosen Python environment
before running `Launch ADAM.bat`. The launcher checks desktop dependencies and
does not install packages automatically or depend on the developer's personal
trainer folders. Install each optional trainer's dependencies according to that
tool's setup instructions before using its ADAM workflow.

Remote access is disabled by default. Devices with an access token can browse
datasets, edit captions/review marks and submit work. Only enable it for trusted
devices. The desktop **Allow remote job controls and approval changes** setting
also permits remote confirmation, stopping and retrying jobs. A remote browser
can enable training auto-approval only after that desktop permission is granted;
it can always turn auto-approval off. Saved token changes and disabled access
take effect for new requests without restarting the server.

Use private Tailscale access for connections beyond a trusted local network;
the built-in HTTP listener does not provide transport encryption by itself.
Phone URLs and QR codes contain the access token and should be treated as
credentials. Remote commands require JSON, have bounded request sizes and
connection counts, and reject cross-site browser submissions. These controls
do not sandbox installed Python plugins or connected trainers: install only
code you trust.

Detection does not automatically authorize training. A real training adapter
remains gated until its dataset, model name, run settings, and output location
are explicit.

## Training agents

![ADAM model creation settings](docs/screenshots/create-model.png)

ADAM's training lifecycle is divided into four explainable responsibilities:

- **EVE** reviews dataset membership and leaves uncertain images for the user.
- **ORION** reviews planned epochs, batch size, resolution, image exposures, and
  estimated optimizer steps. He can require approval but never silently changes
  the requested settings. In the Model Creation Assistant, **ORION: apply a
  starting recipe** fills a conservative, editable draft from the image count
  and selected resolution before a plan is built.
- **ATLAS** watches active training for non-finite loss, sustained critical GPU
  temperature, critically low disk space, stalls, and large runtime overruns.
  Critical conditions pause the trainer process tree so the user can inspect it.
- **NOVA** examines available post-training previews and samples for unreadable
  files and exact-looking duplicate collapse. Her report explicitly separates
  technical sample health from subjective or subject-quality review.

ORION, ATLAS, and NOVA reports are stored with each durable job record and are
shown in Current Plan, Active Job, and Jobs / History respectively. ATLAS's
default thresholds can be overridden in `config/settings.json` with the
`atlas_*` settings defined in `adam/config.py`.

Every new job passes through the shared preflight and ORION review before its
queue state is chosen. Desktop plans, Remote prompts, and Remote training forms
use the same review. Remote training auto-approval still applies to ordinary
plans, but an ORION warning leaves the job awaiting explicit approval. Reviewing
a plan does not change the requested training settings.

## Real image collection

When a valid Dataset Collector folder is connected, the `dataset_collector`
registry entry uses ADAM's real visible-browser adapter. After plan approval it:

- opens Bing Images in a normal visible Chrome window;
- waits when consent/CAPTCHA/human-verification text is detected;
- resumes automatically after the user resolves the page;
- downloads valid images at least 256×256;
- removes exact duplicate downloads;
- writes a matching `.txt` caption beside every image; and
- records URLs, captions, sources, and dimensions in `metadata.csv`.

No CAPTCHA or website restriction is bypassed. Closing Chrome or stopping the
job ends collection safely. A new timestamped dataset folder is used rather
than overwriting an existing collection.

ADAM keeps an incomplete DDPM request in conversation memory. A follow-up such
as `dataset folder Mario, model name Mario V2, epoch count 100, output D:\Runs`
fills the pending fields and validates named datasets against the connected
collector. It will not start if the dataset cannot be found.

## Showcase videos

The **Showcase Video** workspace creates a finished MP4 directly from completed
DDPM and Flow Matching models. Select and reorder the models, choose 12–24
images per model, a 3-, 4-, or 5-second image duration, shared steps and aspect
ratio, provider-compatible samplers, seed, and 720p or 1080p output. ADAM runs
the image batches sequentially and then renders a request-list interface that
tracks the active model, image number, trainer, steps, sampler, and aspect ratio.
LoRA models are intentionally excluded from this streamlined workflow.

When Ollama is reachable, messages that are not workflow commands receive a
short conversational answer. Ollama may explain or plan, but it still cannot
bypass the registry or confirmation gates.

## Web search in Chat Mode

Chat Mode can give local Ollama current web context without an API key. Enable
it in **Settings → Planning model**, then ask naturally, for example:

```text
Search the web for Dandy's World character ideas.
What are the latest Ollama release notes?
Look up a reference for a cyberpunk city character.
```

ADAM sends only that search query to Bing's public results feed, reads the
result titles and snippets,
and passes up to five titles, snippets, and links to Ollama. It does not open
the result pages, download anything, or let web content run tools. Results are
untrusted reference material, so ADAM is instructed to cite the links and flag
uncertainty. Disable the setting to keep Chat Mode fully local.

When you explicitly ask ADAM to **read**, **open**, or **research** result links,
it can read up to three public HTML/text pages and give Ollama short extracts.
For example: `Search the web for Undertale character ideas and read the most
relevant links.` Direct links can be read with `Read https://example.com/ and
summarize it.` Private/local addresses, non-web protocols, oversized pages,
downloads, and more than three pages are blocked. This control can be disabled
in Settings.

Planning runs away from the interface thread, and conversational Ollama output
is streamed into the chat. ADAM validates training commands against a strict
schema and each registered trainer's declared capabilities before offering a
job.

In **Settings → Planning model**, **Chat response length** sets the maximum
number of generated tokens for a Chat Mode reply. Higher values allow longer
research summaries but use more time and GPU memory. The default is 1,024,
which gives Qwen3 enough room to reason and still produce a visible response.

ADAM stores friendly dataset/model names, paths, trainer types, epochs, and
resume checkpoints in `data/assets.json`. Requests such as:

```text
From the Mario dataset, train it on a DDPM for 300 epochs.
With the Mario dataset, train it on a LoRA for 100 epochs.
Continue the Mario model from the DDPM for 50 epochs.
```

are resolved to real paths before approval. Continuation is offered only when a
compatible checkpoint exists. New DDPM runs retain the latest resume checkpoint.

## Run

```powershell
python main.py
```

On Windows, you can also double-click `Launch ADAM.bat`.

The app requires Python 3.10+ and PySide6. Optional integrations use `psutil`
for system information and `pynvml` for NVIDIA GPU information.

```powershell
python -m pip install -r requirements.txt
```

Try:

- Click **Create a model…** in Trainer Mode for the guided Model Creation Assistant.
- `Adam, train a LoRA of Hatsune Miku`
- `Adam, collect a dataset of liminal spaces`
- `Adam, generate previews`
- `Adam, check GPU status`
- `From the Mario dataset, train it on a DDPM for 300 epochs`
- `With the Mario dataset, train it on a LoRA for 100 epochs`

Training and large collection plans are never started until you approve the
plan. All actions are recorded in `logs/adam.log`, while project artifacts live
under `data/projects/`.

The Model Creation Assistant can start from a built-in Character LoRA, Style
LoRA, DDPM, or Flow Matching preset. It can create a dataset or select a
registered one, recommends starting values, and saves personal presets. The
result still goes through ADAM's normal validated planner and approval gate.
Use **+ Add model** to build a multi-model training batch. Each wide model tab
keeps its own dataset, trainer, name, and settings; the minus button removes an
unwanted model, and tabs can be dragged to change the run order. ADAM validates
all models, presents one combined approval plan, and runs them sequentially so
only one training workflow uses the GPU at a time. A failed step stops the batch
before a later model starts.
Before approval, ADAM adds checks for connected tools, dataset contents, the
LoRA base model, and output-drive free space. Completed dataset and training
jobs also include a suggested next step.

### Model Batch Builder

Use **Create model batch…** to paste one requested subject per line. ADAM turns
the list into editable model tabs, removes duplicate names, and lets the current
trainer recipe be applied to any multi-selection of models. The batch is saved
as a draft so it can be closed and resumed later.

For a review-first workflow, choose **Collect missing datasets first**. This
queues only sequential dataset collection and leaves training in the saved
draft. After collection, reopen the draft, use **Find collected datasets**, and
review each dataset in Training Studio. **Exclude rejected** moves rejected
images out of the training folder into a recoverable quarantine, and **Restore
excluded** reverses it. **Keep all images** marks the whole selected dataset as
accepted in one action, after which individual bad images can still be rejected.
Training remains locked until each model is explicitly
marked as reviewed and ready. If every linked dataset is acceptable as-is,
**Approve all datasets** marks the entire batch ready after one confirmation;
it does not inspect individual images or apply pending rejection decisions.

Completed Flow Matching models can be selected in **Fine-tune**. ADAM uses the
saved Flow model folder as the continuation source, locks the continuation to
the model's original resolution, and writes the fine-tuned result to a new
output folder. This continues the saved weights while starting a fresh optimizer
and learning-rate schedule; it does not overwrite the original model.

## Training Studio

The **Training Studio** turns completed work into a reviewable experiment loop:

- **Datasets** provides an image gallery, keep/reject decisions, caption editing,
  exact duplicate detection, and visually similar duplicate candidates.
- **Experiments** compares job settings and outcomes, opens outputs, marks a
  preferred model, and converts successful settings into reusable recipes.
- **Checkpoint Lab** browses model checkpoints and output images, records
  consistent prompt/seed evaluations, and sends preview requests through the
  normal approval-aware planner.
- **Recipes** preserves training starting points and can import or export
  portable JSON recipe files.

### EVE AI Dataset Review

In Training Studio → Datasets, **EVE AI Review…** performs a local reference-
guided visual review. Add one or more good reference images and optional bad
references, then choose Keep and Reject confidence thresholds. EVE uses a small
DINOv2 vision model to divide the selected dataset into **Keep**, **Reject**, and
**Uncertain** galleries with confidence scores. The model is downloaded once on
first use and subsequent analysis stays local.

Nothing is applied automatically. Inspect both sides, double-click images for a
full view, and move selected results between the three groups before choosing
**Apply EVE review**. EVE's decisions remain ordinary Training Studio review
marks: they can be manually changed, and rejected files are not moved until
**Exclude rejected** is selected. The latest proposal is also saved under
`data/eve_reviews/` for auditing. Use **Select all in current group** (or
Ctrl/Shift selection) to move many images at once; EVE transfers only the
chosen thumbnails so manual sorting stays responsive on large datasets.

Training panels show elapsed time, a progress-based ETA, recent logs, and a
loss sparkline when the connected trainer reports `loss`. Preflight summaries
include clearly labelled workload, duration, VRAM, and disk estimates. These
estimates are planning hints rather than hardware guarantees.

Create a Model also supports live training previews with a configurable
epoch interval, prompt, and reproducible seed for each model tab. While a
training job is active, its newest 256×256 preview appears in the right sidebar
with the source epoch and next scheduled preview. The full-size trainer output
can be opened from the card. Built-in adapters may publish previews directly;
registered DDPM, Flow, LoRA, APVD, MaskGit, and other trainers can also
participate by writing conventionally named `preview`, `sample`, or `epoch`
images beneath their declared output folder.

## Generations

The **Generations** workspace runs compatible registered image generators
without opening their separate desktop interfaces. The connected DDPM and Flow
Matching projects can generate from completed models with a reproducible seed,
sampler or ODE method, step count, image count, and aspect ratio. Generation
work uses the normal ADAM job queue, progress reporting, cancellation, and
logging.

Every completed batch is stored under `data/generations/` with its images and a
`generation.json` sidecar. The history gallery can open an image or batch folder
and restore the exact settings for another run. DDPM creative notes are stored
with a batch for organization; they are not presented as text conditioning for
an unconditional DDPM model.

Generation history opens as automatic model folders. Each folder uses the
registered model name and a recent generated image as its cover. Double-clicking
a folder filters history to that model and selects its provider and model in the
generation controls, so the next batch is generated into the same existing model
directory. This view does not move or rewrite older generation files.

**Generation Cycle…** selects multiple compatible completed models and queues
one generation step per model. Choose images per model, a shared prompt or
creative note, starting seed, slideshow duration, looping, fullscreen playback,
and an optional model/trainer label. When the cycle finishes, ADAM opens the
results as a local slideshow while preserving every ordinary generation record
in history.

If ADAM discovers a job interrupted by an unexpected shutdown, it offers to
open Jobs & History. The previous record remains intact and can be retried as a
new approval-gated job. Job logs can also be exported for troubleshooting.

## Connect an existing tool

ADAM supports importable Python functions and command-line Python scripts.
For a no-code setup, open **Settings → External Tools → Add external tool**.
Choose the program folder, select its training entry script and important
configuration files, then review ADAM's static compatibility and safety report.
The report covers:

- detected command-line options and required inputs;
- likely dataset formats;
- output and checkpoint behavior;
- progress reporting;
- resume-training support; and
- potentially risky operations visible in the selected entry script.

The 1–10 rating measures how clearly the script fits ADAM's safe command-line
contract. It is not a guarantee that third-party code is harmless. ADAM does
not execute a script while scanning it, external tools cannot replace built-in
registry entries, and every external-tool run requires explicit approval.

After registration, a tool can be planned with a request such as:

```text
Run APVD Model Trainer with dataset=D:\DreamData, epochs=20, output=D:\APVD\output
```

ADAM will ask for any required inputs that were omitted before it offers the
approval plan.

For manual registry configuration, edit the relevant item in
`config/tools.json`:

```json
{
  "backend": {
    "type": "python",
    "module": "my_tools.lora",
    "function": "train"
  },
  "demo": false
}
```

The function receives a `ToolContext` as its first argument and keyword
arguments from the approved plan. This keeps training code in one place: your
existing GUI and ADAM can both call the same backend.

For scripts:

```json
{
  "backend": {
    "type": "script",
    "path": "D:/AI/LoRATrainer/train.py"
  },
  "demo": false
}
```

ADAM invokes scripts directly with the current Python interpreter, captures
stdout/stderr, and never drives another GUI with mouse clicks.

## Safety model

- Plans are shown before execution.
- Long, destructive, or high-volume work requires confirmation.
- Unregistered tools cannot be invoked.
- External paths and arguments are validated before execution.
- The LLM may propose a plan, but only registered tools can execute it.
- Pause, resume, and cancel controls are available for active jobs.
- Every tool action and state transition is logged.

## Tests

```powershell
python -m pytest -q
```