Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -133,7 +133,7 @@ and deserialized through a registry.
| `openenv/` | `build_app(bundle)`: the [OpenEnv](https://github.com/openenv/OpenEnv) server for a bundle's tasks, each session playing one episode through the Episode API, with the envs' MCP tools, an added `end_turn` tool and the task's verifier score as the reward. It prepares bundles as `agent-env run` does (`prepare_bundle(played=True)`, without the agent the client plays) and keeps namespace routing on for the app's life. `openenv` comes with the `openenv` extra, a floor with no cap; this package and `training/` are the only ones that import it. Each task's description in the Task API names its `toolset` (the played agent's envs, role, and whether it gets `bash`). With `token`, every request and WebSocket but `/health` must carry `Authorization: Bearer <token>`, for a server others reach. |
| `training/` | One module per outside trainer, each behind its own extra, and the modules they share; [Training helpers](#training-helpers) lists them. |
| `runner/` | The `[runner]` seam: `Runner.submit()` returns a `RunHandle` (`run_id`, `instance_id`) before the run starts; `LocalRunner` is built in. `runner/store.py` is the run index every runner writes and the explorer reads. |
| `bundle/` | A bundle is a folder of entities (`envs/`, `agents/`, `artifacts/`, `skills/`, `tasks/<name>.json`, `evals/<name>.toml`) that runs without a registry: `agent-env run` plans it, writes it into the `@local` namespace (reusing each version whose inputs haven't changed) and runs its evals or tasks; `agent-env run hf://<org>/<repo>[@<revision>][/<path>]` (`bundle/hub.py`) runs one from a Hugging Face Hub dataset, picked from the commit's file list (the path, else `bundles/`, else the root) and downloaded alone with the card into a folder per commit, under ids rooted at `@hf/<org>/<repo>`, which only that path produces, each run's context recording the commit (`metadata["bundle_source"]`); `agent-env bundle init` writes a stored task or eval as one, with every env, agent and artifact it uses in its own folder (each image as its build context, pruned to what its Dockerfile reads and pinned to the Python and npm versions of the stored image, or, given `--image-ref ID=REF`, as that registry image pinned by digest with its context beside it, `image = { ref, dockerfile }`, which a run pulls and builds only when it can't; `task_images` lists the images an import writes, downloading nothing, so an export can push them first) so it runs with no store; `agent-env bundle register` writes a folder into the configured stores under registry ids (`<prefix><name>`, and an installed bundle's agent, env or artifact a reference pulls in under its alias, an env only into a shared store), each task and eval naming the versions it reads and each image it builds pushed, through a ledger in the target store so registering again writes only what changed. |
| `bundle/` | A bundle is a folder of entities (`envs/`, `agents/`, `artifacts/`, `skills/`, `tasks/<name>.json`, `evals/<name>.toml`) that runs without a registry: `agent-env run` plans it, writes it into the `@local` namespace (reusing each version whose inputs haven't changed) and runs its evals or tasks; `agent-env run hf://<org>/<repo>[@<revision>][/<path>]` (`bundle/hub.py`) runs one from a Hugging Face Hub dataset, picked from the commit's file list (the path, else `bundles/`, else the root) and downloaded alone with the card into a folder per commit, under ids rooted at `@hf/<org>/<repo>`, which only that path produces, each run's context recording the commit (`metadata["bundle_source"]`); `agent-env bundle init` writes a stored task or eval as one, with every env, agent and artifact it uses in its own folder (each image as its build context, pruned to what its Dockerfile reads and pinned to the Python and npm versions of the stored image, or, given `--image-ref ID=REF`, as that registry image pinned by digest with its context beside it, `image = { ref, dockerfile }`, which a run pulls and builds only when it can't; `task_images` lists the images an import writes, downloading nothing, so an export can push them first; a computer env as its base, driver and apps, each with its files, never what it composed, which a run of the folder composes, and an env or artifact of an installed bundle, there or anywhere an entity names one, by its id) so it runs with no store; `agent-env bundle register` writes a folder into the configured stores under registry ids (`<prefix><name>`, and an installed bundle's agent, env or artifact a reference pulls in under its alias, an env only into a shared store), each task and eval naming the versions it reads and each image it builds pushed, through a ledger in the target store so registering again writes only what changed. |
| `eval/` | `Eval` (`eval`), a versioned list of task references, and its store. |
| `plugins/` | Entry-point plugins (see Extension points): the group names, `inventory()`, which `agent-env plugin list/show/check` report, `load_failures` and `settings`. The top level is public; the underscored modules are internal. |
| `explorer/` | Optional local web UI: `agent-env up`, binds loopback `:8234`. |
Expand Down
17 changes: 17 additions & 0 deletions src/agent_env/artifact/artifacts/computer.py
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,7 @@

if TYPE_CHECKING:
from agent_env.bundle.authoring import AuthoringContext
from agent_env.entity.export import ExportContext

FORMS = ("container", "disk", "vm_bundle")
#: A VM bundle's image that is already on the host that boots it, by its name there, as composing leaves one.
Expand Down Expand Up @@ -365,6 +366,22 @@ def from_toml(cls, data: dict[str, Any], ctx: AuthoringContext) -> Self:
except ValueError as e:
ctx.refuse([str(e)])

def to_toml(self, out: ExportContext) -> dict:
"""The artifact.toml of a folder each form's image is built from, or names from a registry, which ``from_toml``
reads back as it."""
forms = self.forms.model_dump(mode="json", exclude_none=True)
if self.forms.container is not None:
forms["container"]["image"] = out.image(self.image(), "forms.container.image")
if (disk := self.disk_image()) is not None:
forms["disk"]["image"] = out.image(disk, "forms.disk.image")
toml = {"type": self.type, **({"description": self.description} if self.description else {}),
"arch": list(self.arch), "os": self.os.model_dump(mode="json", exclude_none=True),
"session": self.session.model_dump(mode="json"), "forms": forms}
if self.config:
toml["config"] = {name: setting.model_dump(mode="json", exclude_defaults=True)
for name, setting in self.config.items()}
return toml

def image(self) -> DockerImageArtifact:
"""The container form's image artifact, refused when the store has no docker_image artifact of that id and
version."""
Expand Down
9 changes: 8 additions & 1 deletion src/agent_env/bundle/importer.py
Original file line number Diff line number Diff line change
Expand Up @@ -149,6 +149,9 @@ def __init__(self, importer: _Importer, folder: str, toml_name: str | None):

def ref(self, entity: Any) -> str | dict:
kind = _kind_of(entity)
if (bundle := self.importer._installed_for(kind, entity.id)) is not None:
self.importer.floating.append(Floating(self.folder, kind, entity.id, _from_bundle(bundle)))
return entity.id
local = self.importer.local(kind, entity, self.folder)
return local if local is not None else {kind.value: entity.id, "version": entity.version}

Expand Down Expand Up @@ -534,7 +537,7 @@ def _installed_for(self, kind: EntityKind, entity_id: str) -> InstalledBundle |

def _from_installed(self, site: RefSite, where: str, bundle: InstalledBundle) -> None:
"""An installed bundle's entity has no fixed version, so it isn't pinned, and a pin the store held is dropped."""
why = f"it comes with the installed bundle {bundle.qualified}, which a run writes it from"
why = _from_bundle(bundle)
if site.version is not None and site.version_key is not None:
why += f"; the stored pin to v{site.version} is dropped, as such an entity has no fixed version"
_unpin(site)
Expand Down Expand Up @@ -579,6 +582,10 @@ def _names_of(kind: BundleKind) -> str:
return BundleKind.ARTIFACT.value if kind is BundleKind.SKILL else kind.value


def _from_bundle(bundle: InstalledBundle) -> str:
return f"it comes with the installed bundle {bundle.qualified}, which a run writes it from"


def _kind_of(entity: Any) -> EntityKind:
if isinstance(entity, Env):
return EntityKind.ENV
Expand Down
13 changes: 13 additions & 0 deletions src/agent_env/env/envs/computer/app_env.py
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,7 @@
from collections.abc import Iterable

from agent_env.bundle.authoring import AuthoringContext
from agent_env.entity.export import ExportContext


#: What an app deployed alone adds to its name to name its computer.
Expand Down Expand Up @@ -171,6 +172,18 @@ def from_toml(cls, data: dict, ctx: AuthoringContext) -> ComputerAppEnv:
except ValueError as e:
ctx.refuse([str(e)])

def to_toml(self, out: ExportContext) -> dict:
"""The env.toml of a folder holding the app's files, which ``from_toml`` reads back as it."""
self.files.to_toml(out)
toml = {"type": self.type, "environment_name": self.environment_name, "module": self.module}
if self.computer is not None:
toml |= {"computer": out.ref(self.computer), "driver": out.ref(self.driver)}
if self.build_settings:
toml["build_settings"] = dict(self.build_settings)
if self.settings:
toml["settings"] = dict(self.settings)
Comment thread
earakely-scale marked this conversation as resolved.
Resolved
return toml

@classmethod
def accept_toml(cls, data: dict, ctx: AuthoringContext) -> dict:
"""The keys of ``data``, an env.toml, a computer app env takes: ``module = "<file>:<class>"``, naming a file of
Expand Down
15 changes: 15 additions & 0 deletions src/agent_env/env/envs/computer/driver_env.py
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,7 @@

if TYPE_CHECKING:
from agent_env.bundle.authoring import AuthoringContext
from agent_env.entity.export import ExportContext
from agent_env.env.env import DeployedEnv

#: How long reading a driver's class at put may take.
Expand Down Expand Up @@ -91,6 +92,20 @@ def from_toml(cls, data: dict, ctx: AuthoringContext) -> ComputerDriverEnv:
install=fields["install"], port=fields.get("port", DEFAULT_PORT),
known_failures=fields.get("known_failures"))

def to_toml(self, out: ExportContext) -> dict:
"""The env.toml of a folder holding the driver's files, which ``from_toml`` reads back as it."""
self.files.to_toml(out)
toml = {"type": self.type, "module": self.module}
if self.port != DEFAULT_PORT:
toml["port"] = self.port
if self.install:
toml["install"] = {key: install.model_dump(mode="json", exclude_none=True, exclude_defaults=True)
for key, install in self.install.items()}
if self.known_failures:
toml["known_failures"] = {key: [failure.model_dump(mode="json", exclude_defaults=True) for failure in failures]
for key, failures in self.known_failures.items()}
return toml

@classmethod
def accept_toml(cls, data: dict, ctx: AuthoringContext) -> dict:
"""The keys of ``data``, an env.toml, a computer driver env takes: ``module = "<file>:<class>"``, naming a file
Expand Down
20 changes: 20 additions & 0 deletions src/agent_env/env/envs/computer/env.py
Original file line number Diff line number Diff line change
Expand Up @@ -48,6 +48,7 @@
if TYPE_CHECKING:
from agent_env.artifact import EnvironmentArtifact, EnvironmentUniverseArtifact
from agent_env.bundle.authoring import AuthoringContext
from agent_env.entity.export import ExportContext
from agent_env.env.env import DeployedEnv
from agent_env.env.envs.computer.app_env import ComputerAppEnv
from agent_env.providers.env_providers.env_provider import EnvironmentProvider
Expand Down Expand Up @@ -168,6 +169,18 @@ def from_toml(cls, data: dict, ctx: AuthoringContext) -> ComputerEnv:
except ValueError as e:
ctx.refuse([str(e)])

def to_toml(self, out: ExportContext) -> dict:
"""The env.toml of a computer env naming its base, driver and apps, each app with its settings beside it, which
``from_toml`` reads back as it. What it composed isn't written: a run of the folder composes it."""
toml = {"type": self.type, "environment_name": self.environment_name, "computer": out.ref(self.computer),
"driver": out.ref(self.driver)}
if self.apps:
toml["apps"] = [_app_entry(out.ref(app), self.app_settings.get(app.environment_name)) for app in self.apps]
for key in ("display", "network", "computer_settings", "tools"):
if value := getattr(self, key):
toml[key] = value
return toml

@classmethod
def accept_toml(cls, data: dict, ctx: AuthoringContext) -> dict:
"""The keys of ``data``, an env.toml, a computer env takes: the ``computer`` and ``driver`` it's composed of,
Expand Down Expand Up @@ -521,6 +534,13 @@ def _listed_apps(refs: list, ctx: AuthoringContext) -> tuple[list[ComputerAppEnv
return apps, app_settings


def _app_entry(ref: str | dict, settings: Optional[dict]) -> str | dict:
"""An env.toml's ``apps`` entry: the app's ref, in a table with its ``settings`` beside it when it has some."""
if not settings:
return ref
return {**(ref if isinstance(ref, dict) else {"env": ref}), "settings": dict(settings)}


def _not_an_app(env: Env) -> str | None:
return f"{env.id} is a {env.type} env, not a {APP_TYPE} env" if env.type != APP_TYPE else None

Expand Down
Loading
Loading