AdvancedTaskSystem

AdvancedTaskSystem is a local/server-ready automation scaffold for technical protocols. It ingests assignment files, lets a fresh Codex planning agent derive a task list, executes those tasks sequentially with a Codex work agent, gates every task through an independent Codex review agent, builds a LaTeX protocol, and prepares neutral review artifacts.

The default mode is dry-run. No real Codex CLI calls, Git pushes, MATLAB runs, or Qt runs are performed unless the project is explicitly switched to real mode and the matching tools are configured.

Installation

python -m venv .venv
.\.venv\bin\python.exe -m pip install -e ".[dev]"

Configuration

Defaults live in config/default.yaml.

git:
  server_base_url: "https://git.fxrz.de/TheoZockt"
  default_branch: "main"
  auto_push: false
codex:
  command: "codex"
  default_timeout_seconds: 1200
  max_retries: 2
  max_memory_mb: 0
latex:
  engine: "latexmk"
matlab:
  command: "matlab"
qt:
  preferred_binding: "PySide6"
workspace:
  dry_run: true

The app no longer stores or requests external AI API keys. The only AI backend is Codex: dry-run uses deterministic mock agents, while real mode uses configured Codex CLI commands.

Git Setup

This tool repository is prepared for:

• Version repo: https://git.fxrz.de/TheoZockt/AdvancedTaskSystem.git
• Tool context repo: https://git.fxrz.de/TheoZockt/AdvancedTaskSystem-context.git
• Per project context repo: https://git.fxrz.de/TheoZockt/<project-name>-context.git

Run:

ats init-tool-repos

Push is disabled by default. Authentication is expected through existing Git configuration, SSH keys, credential helpers, or tokens outside the repository.

In the desktop app, the Repos view can run the same safe Git flow used for this tool repository: prepare or find the project repo on the configured server, set origin, stage with git add -A, create a commit, and push main to origin. If the API login is missing or the remote cannot be reached, the GUI reports the exact failing step in the live log instead of silently continuing.

The Einstellungen view also contains a Git login area. Enter the Git server URL, namespace/organisation, username, and a personal access token or password, then use Git Login speichern to store the credential in the local Git Credential Helper. The secret is not written to settings.yaml, project.yaml, or logs. Tool-Repos auf Server anlegen creates AdvancedTaskSystem and AdvancedTaskSystem-context through a Forgejo/Gitea-compatible API, with GitLab supported as a fallback. In the Repos view, Commit & Push now performs the full project sync; Server-Repo anlegen is still available as a separate explicit preparation step.

CLI Workflow

ats --help
ats create-project demo --input examples/sample_assignment.pdf
ats create-project multi-demo --input assignment.pdf --input measurements.csv --input notes.md
ats create-project tool-demo --prompt "Baue ein Python-Tool, das Messdaten auswertet und Ergebnisse dokumentiert."
ats ingest demo
ats analyze demo
ats run-codex demo
ats build demo
ats review demo
ats final-review-prompt demo
ats git-sync demo --message "Sync project state"
ats delete-project demo --yes

Or run the full dry-run pipeline:

ats run-all demo

Generated project data lives under projects/<project-name>/ and is intentionally ignored by the tool repository.

Desktop GUI

The Figma/Vite GUI lives in frontend/. By default, ats gui starts a native PySide6 desktop window, not a website and not an embedded Chromium browser.

cd frontend
npm.cmd install
npm.cmd run build
cd ..
.\.venv\bin\python.exe -m pip install -e ".[desktop]"
ats gui

For frontend development or visual browser checks only:

ats gui --dev --port 5173
ats gui --web --port 5173

For a quick desktop startup check:

ats gui --smoke-test

Desktop startup diagnostics are written to logs/gui/desktop.log.

The experimental embedded browser engines can still be selected with ATS_DESKTOP_ENGINE=webview or ATS_DESKTOP_ENGINE=qtwebengine, but the default is the more stable native Qt Widgets shell.

Current native desktop workflow:

1. Start ats gui or double-click the built EXE.
2. Enter a project name.
3. Either type a project prompt directly or pick one or more PDF, text, data, or other supported input files. Prompt and files can be used together.
4. Click Projekt anlegen.
5. Select the project in the sidebar.
6. Optionally open Ressourcen and add measurement files, CSV data, images, or a resource folder.
7. Optionally open Einstellungen, configure the Codex command, timeout and retries, and switch the current project from Dry-Run to real Codex mode.
8. Click Run All.
9. Inspect Prompts, Artefakte, Reviews, Repos, Ressourcen, and Logs in the sidebar.
10. Delete local projects from the Projekte view with confirmation when they are no longer needed.

The GUI runs pipeline actions in a worker thread, keeps the live log readable, and persists every step status in project.yaml.

The Abhaengigkeiten sidebar view shows the project-wide shared dependency workspace. It lists installed Python and Node packages, cache sizes, the paths passed to Codex, and the agent context file that is also mirrored into the local context repository.

Build a double-clickable Windows executable with:

.\.venv-desktop\Scripts\python.exe -m PyInstaller --noconfirm --clean --windowed --name AdvancedTaskSystem --collect-data advanced_task_system --hidden-import advanced_task_system.desktop_native --hidden-import PySide6.QtXml --hidden-import PySide6.QtSvg --distpath release-desktop --workpath build\pyinstaller src\advanced_task_system\desktop_entry.py

After the first build, the checked-in spec can be reused:

.\.venv-desktop\Scripts\python.exe -m PyInstaller --noconfirm --clean --distpath release-desktop --workpath build\pyinstaller AdvancedTaskSystem.spec

Then start:

release-desktop\AdvancedTaskSystem\AdvancedTaskSystem.exe

The frozen EXE stores projects, logs, and generated artifacts in %LOCALAPPDATA%\AdvancedTaskSystem by default. Set ATS_TOOL_ROOT to override that location.

Project Layout

Each project contains:

• inputs/raw/ for copied original inputs
• inputs/raw/project_prompt.md when the project was created from a typed prompt
• inputs/extracted/ for extracted text
• analysis/assignment_text.md, assignment_analysis.json, and work_plan.md
• agent_tasks/ for the Codex planning result, task list, progress JSON, and per-task YAML
• agent_reviews/ for independent Codex review-agent decisions per task/attempt
• prompts/ for generated Codex and review prompts
• codex_runs/run_*/ for per-prompt logs and result JSON
• latex/ for protocol projects that really need main.tex, sections, tables, figures, and build.log
• matlab/ for scripts and mock or real result exports
• qt/ for visualization scripts and exported figures
• reviews/ for first review and final_review_prompt.md
• artifacts/ for generated project reports, PDFs, export ZIPs, EXEs or build metadata
• resources/raw/ for additional measurement data and other project resources
• resources/resources.yaml for resource metadata and checksums
• shared/dependencies/ for project-wide dependency caches and local installs
• shared/dependencies/python/.venv/ as the preferred reusable Python environment for that project
• shared/dependencies/python/pip-cache/ and shared/dependencies/node/npm-cache/ to avoid repeated downloads
• shared/dependencies/manifest.json, installed.md, and shared/agent_context.md for visible dependency documentation
• logs/ for command logs
• repos/context-repo/ as a separate local Git repository

Shared Dependencies

Every project gets its own shared/ workspace. Codex planner, worker, and reviewer prompts are told where it is, and real Codex subprocesses receive these environment variables:

• ATS_SHARED_ROOT
• ATS_PYTHON_SHARED_VENV
• PIP_CACHE_DIR
• npm_config_cache
• PLAYWRIGHT_BROWSERS_PATH

This lets all generated repos and task attempts reuse the same project-local caches instead of downloading dependencies again for every step. Heavy cache folders and virtual environments stay local and are ignored by Git; the manifest, report, and context notes remain visible in the UI and can be committed.

After a successful dry-run Run All, the expected key files are:

• analysis/assignment_text.md
• analysis/assignment_analysis.json
• analysis/work_plan.md
• agent_tasks/tasks.json
• agent_tasks/task_list.md
• agent_tasks/progress.json
• agent_reviews/task_001_attempt_01_review.json
• prompts/codex_prompt_001.md through codex_prompt_003.md
• codex_runs/run_001/result.json through run_003/result.json
• latex/main.tex for protocol-shaped dry-run projects, or app/build files for general software projects
• matlab/outputs/results.json
• qt/visualizations/visualization_app.py
• artifacts/protocol.tex
• artifacts/protocol.pdf
• artifacts/project_report.md and artifacts/export.zip for general software projects
• reviews/first_review.md
• reviews/final_review_prompt.md

Codex Agent Mode

The desktop Einstellungen view provides:

• default Dry-Run switch for new projects
• Codex CLI command setting
• Codex CLI automatisch finden to prefer the startable standalone CLI over the WindowsApps app alias
• Codex EXE auswaehlen for installations that are not available through PATH
• Codex timeout setting
• Codex retry setting
• soft RAM limit for external process trees such as Codex, LaTeX, MATLAB, or build tools
• a local Codex command availability check

Existing projects keep their own dry_run flag. To use real Codex CLI calls for a project, select it and click Aktuelles Projekt: echter Codex-Modus in Einstellungen. If the Codex CLI is missing, the app reports the error in the live log instead of crashing. Dry-run remains fully usable without external AI credentials or tools.

When Codex-Verfuegbarkeit pruefen cannot find the codex command while the selected project is still in dry-run mode, the GUI reports it as a warning-style status: dry-run can continue, real Codex mode needs a valid CLI command.

If codex is already available in the system PATH, keep the command as codex. Otherwise click Codex CLI automatisch finden or Codex EXE auswaehlen and choose the installed standalone codex.exe; the app stores the executable path and uses it for planner, worker, and reviewer calls. Typical Windows standalone installs live under %USERPROFILE%\.codex\packages\standalone\releases\...\bin\codex.exe.

The availability check now starts the command with --help. A WindowsApps file can be visible but still fail with "Zugriff verweigert"; in that case real Codex mode is not usable from this app yet and the project should stay in dry-run mode until a startable Codex CLI command is configured.

Real agent calls use codex exec -: prompts are sent over stdin, event output is logged as JSONL, and the final agent message is saved separately for planner/reviewer JSON parsing.

Set max_memory_mb to 0 to disable memory enforcement. Any positive value is treated as a soft cap for subprocess trees started by the app; when the tree goes over the limit, the app terminates that process tree and records a clear error in the step logs.

Dry-run is prompt-aware. For example, a prompt like "Baue eine EXE die Pong spielen kann" creates a Tkinter Pong scaffold, a Windows build script, a mock EXE artifact marker, and an export zip instead of LaTeX/MATLAB protocol placeholders.

The artifact step is intentionally general. It only runs a real LaTeX build when the assignment or Codex task list actually asks for a LaTeX/protocol output. For app, game, data, or tool projects it writes a generic project report/export and does not fail just because an old latex/main.tex exists.

The Codex integration is backend-based:

• MockCodexAgentBackend creates deterministic task plans, files, and approvals in dry-run mode.
• CliCodexAgentBackend starts fresh Codex CLI calls for planner, worker, and reviewer roles in real mode.
• A task only advances when the independent review agent returns approved.
• If the review returns needs_revision, the feedback is passed to the work agent and the same task is retried before the next task can start.

Timeout Handling

All real external commands go through a subprocess wrapper with:

• configurable timeout, default 1200 seconds
• stdout and stderr log files
• process-tree termination on timeout
• exit code, runtime, and timeout status capture
• retry support

Codex command retries are controlled by codex.max_retries and also serve as the maximum review-driven rework attempts per task.

Review Pipeline

Every Codex task is reviewed by an independent reviewer agent before the next task begins. The first protocol review summarizes those task reviews and the generated artifacts. The final review prompt is always written to:

projects/<project-name>/reviews/final_review_prompt.md

That prompt deliberately includes only the original assignment, final LaTeX protocol, and neutral criteria. It excludes internal planning, previous reviews, and execution history.

Limits

• Dry-run artifacts are structurally useful but not mathematically authoritative.
• Real Codex CLI/API integration is represented by a clear backend interface and a conservative CLI hook.
• MATLAB and Qt real execution hooks are intentionally minimal in this first pass.
• PDF extraction falls back to raw text decoding for mock PDFs and damaged documents.

Tests

.\.venv\bin\python.exe -m pytest

The tests cover configuration loading, local app settings, project creation, resource import, mock PDF ingestion, timeout handling, prompt generation, Git URL creation, final review prompt creation, and the full dry-run pipeline.

TODO

• Add a confirmed real Codex CLI/API adapter once the target interface is stable.
• Add richer MATLAB script discovery and result collection.
• Add a real PySide6 renderer for visualization exports.
• Add optional push workflows and remote repository creation through a provider-specific API.
• Add stronger LaTeX validation and PDF text extraction during review.