FAQ

This page captures recurring questions about the AGILab tooling and runtime.

Missing worker packages during AGI.run_*

If a run fails with ModuleNotFoundError inside a worker virtual environment, rerun the matching installer script (for example uv run --project src/agilab/core/agi-cluster python src/agilab/examples/flight/AGI.install_flight.py). The installer rebuilds the worker egg and provisions its environment so the next AGI.run_* picks up the dependencies.

Why installers still build eggs

The distributed upload path expects bdist_egg artifacts. Each app ships a build.py helper that produces eggs and symlinks the required modules before they are sent to Dask. Moving to pure wheels would break that upload contract, so eggs remain the canonical package format.

Do we already have DAG/task orchestration?

Yes. Managers hand WorkDispatcher a work plan and DagWorker executes it, enforcing dependencies and parallelism across workers. The improvement areas are telemetry and richer policies (retries, priorities), not building a brand-new planner.

Who manages multithreading when Dask is disabled?

agi_dispatcher owns the local process and thread pools. Dask only coordinates execution when you explicitly opt into distributed mode; otherwise, the dispatcher handles the orchestration end to end.

Regenerating IDE run configurations

pycharm/gen_app_script.py is the authoritative generator for JetBrains run configurations. Wrap it (and setup_pycharm.py) in a single helper command—e.g. just run-configs or make run-configs—so developers and CI regenerate configs consistently from the same entry point.

“VIRTUAL_ENV … does not match the project environment” warning

uv emits this when you launch a command from an activated shell whose $VIRTUAL_ENV differs from the target project’s .venv directory. The message is informational—the command will still run using the project lock. If you truly want to reuse the activated environment, pass --active to uv; otherwise you can safely ignore the warning.

Why does a run create distribution.json?

WorkDispatcher caches the last work-plan in distribution.json inside each app directory. On subsequent runs it reuses the plan if the workers layout and arguments are unchanged; delete the file (or change args) to force a full repartition.

Switching the active app in Streamlit

Use the project selector in the left sidebar of the Streamlit UI. AgiEnv will recreate symbolic links under ~/wenv and adjust the virtual environment for the chosen app. When you add a brand-new app under src/agilab/apps/, restart the Streamlit session so the selector picks it up.

Docs drift after touching core APIs

If you change BaseWorker or other primitives surfaced in the guides, rebuild the reference documentation with uv run python docs/gen-docs.py so the published docs match the updated source.

AGI.install_* fails looking for pyproject.toml

Each worker must carry its own pyproject.toml (for example src/agilab/apps/ilp_project/src/ilp_worker/pyproject.toml). If the installer raises FileNotFoundError for that path, add the file with the worker’s runtime dependencies—typically mirroring the manager’s requirements plus the appropriate dag-worker/polars-worker extra.

Where are installer logs written?

Every installer run streams output to the UI and also appends a timestamped log under $AGI_LOG_DIR/install_logs. By default $AGI_LOG_DIR is ~/log (see $HOME/.agilab/.env), so you will find files like ~/log/install_logs/install_20250921_072751.log_ with the full transcript.