agi-node API

Path handling

Workers resolve any dataset or workspace URI through BaseWorker.normalize_data_uri before touching the filesystem. The helper accepts str or pathlib.Path inputs and normalises them as follows:

• UNC-style shares on Windows (for example \\server\share) are preserved by wrapping them in PureWindowsPath and returning the os.path.normpath representation so network drives keep their double backslashes.

• Every other value is first joined against env.agi_share_path_abs when the environment exposes one; otherwise the helper falls back to the current home directory. This lets configuration files ship entries such as sat_trajectory/dataset while still resolving to the correct worker share (/Users/agi/clustershare/sat_trajectory/dataset on macOS, the mounted share on Linux remotes, and so on).

• Path.resolve(strict=False) is applied to keep symlinks or bind mounts created by installers while still accepting directories that are created later during the run.

• On non-managed Windows installs the helper also attempts to map the dataset under \\127.0.0.1\… via net use so local workers gain access to the same share paths used on Linux.

• The function emits POSIX-style strings on Unix-like systems and uses os.path.normpath on Windows so downstream code can hand the value to shell commands or pathlib without further tweaks.

All built-in workers, including flight_worker and mycode_worker, call this helper in start and work_pool to populate self.args.data_uri and any per-file path passed to the pool. Extending these workers means you get consistent path semantics across local and distributed executions without copy-pasting platform-specific logic.

Argument helpers

Recent updates to BaseWorker standardise how workers load, merge, and persist their argument models. Every subclass can opt into the following hooks:

• default_settings_path and default_settings_section control the TOML source used by from_toml / to_toml.

• args_loader and args_merger are callables that fetch and combine raw settings with user overrides before instantiating the worker.

• args_ensure_defaults lets workers patch derived values (for example, normalising paths) after the merge but before instantiation.

• args_dumper and args_dump_mode define how to_toml emits the active configuration, enabling round-trips back into app_settings.toml.

If these helpers live in the worker module (for example load_args or dump_args defined alongside the class) or inside a sibling *_args/app_args module, BaseWorker auto-binds them during class creation. That lets most apps drop the explicit args_loader = … boilerplate while still allowing manual overrides for custom integrations.

Managed PC path remapping

• managed_pc_path_fields lists argument attributes that should be remapped to the managed-machine workspace (~/MyApp by default) when AgiEnv reports a managed PC.

• managed_pc_home_suffix customises the managed workspace folder name if your deployment uses something other than MyApp.

• BaseWorker.from_toml applies the remapping automatically; when instantiating a worker manually, use setup_args to apply defaults and remap paths in a single call.

• setup_args optionally accepts output_field (e.g. "data_uri") along with output_subdir, output_attr, output_clean and output_parents_up so managers can prepare their output directories without repeating boilerplate.

Output directory helpers

• prepare_output_dir centralises the setup of manager-side output folders (defaulting to dataframe). Hand it the base path you want to target and it normalises the path, clears old contents when auto_clean_data_out is enabled, creates the directory, and stores it on self.data_out unless you override the target attribute.

With these attributes in place, BaseWorker.from_toml produces a configured instance and BaseWorker.to_toml writes the updated schema without each app copying boilerplate. BaseWorker.as_dict exposes a serialisable payload for Streamlit pages and API consumers, while _extend_payload stays available for apps that need to enrich the exported structure.

Reference

dag_worker

---

---

---

pandas_worker

---

---

---

polars_worker

---

---

---