agi-env API

agi_env provides the shared headless environment and path-resolution layer used by both AGILab and the core runtime packages. Streamlit/page dependencies live in the separate agi-gui package under src/agilab/lib/agi-gui.

Usage Example

Instanciation

import asyncio
from pathlib import Path

from agi_cluster.agi_distributor import AGI
from agi_env import AgiEnv


APP = "minimal_app_project"


def agilab_apps_path() -> Path:
    marker = Path.home() / ".local/share/agilab/.agilab-path"
    if not marker.is_file():
        raise SystemExit(
            "AGILAB is not initialized. Run the AGILAB installer or "
            "`agilab first-proof --json` before this example."
        )
    return Path(marker.read_text(encoding="utf-8").strip()) / "apps" / "builtin"


async def main():
    app_env = AgiEnv(apps_path=agilab_apps_path(), app=APP, verbose=1)
    res = await AGI.get_distrib(app_env)
    print(res)
    return res


if __name__ == "__main__":
    asyncio.run(main())

Note

AgiEnv behaves as a singleton. Repeated instantiation updates the same environment instance. Call AgiEnv.reset() before configuring a new environment, or AgiEnv.current() to retrieve the active one.

Share directory resolution

AgiEnv exposes the resolved data root through AgiEnv.agi_share_path_abs. The path is derived from environment settings using the following precedence:

1. AGI_CLUSTER_SHARE from the persisted .env configuration, then the current process environment when the persisted value is unset or blank.

2. AGI_CLUSTER_SHARE fallback clustershare/<user> when no explicit cluster share is configured.

3. AGI_LOCAL_SHARE (default ~/localshare/<user>) when cluster mode is disabled.

The <user> segment is derived from AGILAB_SHARE_USER, then USER, then USERNAME, and is sanitised before being used as a path component.

This ordering lets operators set one shared-data knob in the UI/installer while still allowing remote workers to honour host-specific cluster-share settings. The behaviour differs depending on whether cluster mode is enabled:

• Cluster mode enabled – AgiEnv uses AGI_CLUSTER_SHARE. Relative inputs are expanded against AgiEnv.home_abs on manager/developer shells. The configured share must be mounted and writable, and it must be distinct from AGI_LOCAL_SHARE. The implicit fallback is clustershare/<user>; if you override it in a multi-user deployment, keep the override per-user rather than pointing several operators at the same writable directory. The scheduler source must also be a dedicated directory; filesystem, home, and exact operating-system roots are rejected before remote fan-out. Missing or read-only shares now raise immediately instead of silently degrading to a local path.

• Cluster mode disabled – AgiEnv uses AGI_LOCAL_SHARE for local datasets and outputs.

• Remote workers – the configured cluster-share value remains relative (for example, clustershare/<user>) and is not created automatically. Workers never fall back to per-user local paths; the configured share path must already be mounted and writable on the remote host. When an absolute path under /Users/<user> or /home/<user> is provided, the leading segments are stripped so the worker can re-root the remainder under its own home directory or mount point. An explicit worker mount target must name a dedicated directory such as /mnt/agilab: filesystem roots, worker-home roots, and exact operating-system directories such as /mnt, /var, or /tmp are rejected before AGILAB creates a directory, mounts SSHFS, or updates the worker environment.

Because the worker value stays relative, it will fail fast if agi_share_path is not mounted. This makes data provenance explicit and avoids hidden copies of datasets on remote machines.

Workflow/session data root

AGILAB_WORKFLOW_DATA_ROOT optionally narrows the active data namespace for one workflow or cluster run without changing the physical AGI_CLUSTER_SHARE mount root. AGILAB normally manages this value for workflow sessions and writes the corresponding worker-side value during remote deployment; it is not intended as a second global share setting.

Relative values resolve under the runtime user’s home directory. Output paths are confined to this workflow root. Input paths prefer the workflow root and may fall back to the same relative dataset path under the physical share root when that pre-existing dataset is not copied into the workflow directory. Absolute input and output values are still accepted only when the applicable resolver confirms they remain inside one of those declared roots.

Per-user cluster-share isolation is part of that contract: each user should resolve to their own share root so one operator’s datasets and cluster-visible outputs do not overwrite another operator’s workspace. Generated snippets and operator logs remain local under AGI_LOG_DIR.

Reference

AGILab environment bootstrapper and utility helpers.

The module exposes the AgiEnv class which orchestrates project discovery, virtual-environment management, packaging helpers, and convenience utilities used by installers as well as runtime workers. Supporting free functions provide small parsing and path utilities leveraged during setup.

Notes on singleton and pre‑init behavior

• AgiEnv behaves as a true singleton. Instance attributes are the source of truth; class attribute reads proxy to the singleton instance when initialised. Methods and descriptors are never shadowed by the delegation.

• A small subset of helpers is pre‑init safe and can be used before constructing an instance: AgiEnv.set_env_var(), AgiEnv.read_agilab_path(), AgiEnv._build_env, and AgiEnv.log_info(). These functions avoid hard failures when the shared logger/environment has not been configured yet. Logging in that mode is best‑effort and may fall back to print.