Spaces:
Sleeping
Sleeping
| title: Agterm Environment Server | |
| emoji: 🎼 | |
| colorFrom: purple | |
| colorTo: blue | |
| sdk: docker | |
| pinned: false | |
| app_port: 8000 | |
| base_path: /web | |
| tags: | |
| - openenv | |
| # Agterm Environment | |
| Lightweight echo environment for testing OpenEnv-compatible clients and APIs. | |
| This repository provides: | |
| - A small FastAPI server that executes any command in a bash shell. | |
| - A minimal Python client to connect to a running environment. | |
| - A Dockerfile for building a containerized environment useful for CI or deployment. | |
| ## Quick Start — Python client | |
| Install the project dependencies (see `pyproject.toml`) and use the client: | |
| ```python | |
| from openenv_agterm import agtermAction, agtermEnv | |
| env = agtermEnv.from_docker_image("openenv_agterm-env:latest") | |
| try: | |
| res = env.reset() | |
| print("Reset echoed:", res.observation.echoed_message) | |
| r = env.step(AgtermAction(message="echo 'Hello World'")) | |
| print("Echo:", r.observation.result) | |
| print("Reward:", r.reward) | |
| finally: | |
| env.close() | |
| ``` | |
| Notes: | |
| - `from_docker_image()` starts the container, waits for readiness, and connects the client. | |
| - If you connect with `AgtermEnv(base_url=...)`, `close()` will not stop the external server. | |
| ## Build & Run | |
| Build the Docker image from the repository root: | |
| ```bash | |
| docker build -t agterm-env:latest -f server/Dockerfile . | |
| ``` | |
| Run the server locally (development): | |
| ```bash | |
| # from repository root | |
| uvicorn server.app:app --reload | |
| ``` | |
| Or run the built image: | |
| ```bash | |
| docker run --rm -p 8000:8000 agterm-env:latest | |
| ``` | |
| API surface (when server running): | |
| - `GET /health` — health check | |
| - `GET /docs` — OpenAPI/Swagger UI | |
| - `GET /web` — web UI (if included in the image) | |
| ## Environment API & Models | |
| Action (`AgtermAction`): | |
| - `message` (str): text to echo back. | |
| Observation (`AgtermObservation`): | |
| - `result` (str): result of the command | |
| - `reward` (float): computed reward | |
| - `done` (bool): True if error | |
| - `metadata` (dict): extra info (e.g., step count) | |
| Reward formula: | |
| - Successful result = 1.0 | |
| - Failed result = -1.0 | |
| ## Development & Tests | |
| Run the environment module directly for quick checks: | |
| ```bash | |
| python3 server/agterm_environment.py | |
| ``` | |
| Run the FastAPI app locally: | |
| ```bash | |
| uvicorn server.app:app --reload | |
| ``` | |
| ## Project layout | |
| - [client.py](client.py) — Python client implementation and helpers | |
| - [models.py](models.py) — pydantic models for actions and observations | |
| - [server/app.py](server/app.py) — FastAPI application entry | |
| - [server/agterm_environment.py](server/AGTerm_environment.py) — core environment logic (scriptable) | |
| - [server/Dockerfile](server/Dockerfile) — image definition used to build `agterm-env` | |
| - [openenv.yaml](openenv.yaml) — OpenEnv manifest | |
| - [pyproject.toml](pyproject.toml) — project metadata and dependencies | |
| ## Deployment | |
| You can push this environment to Hugging Face Spaces or similar container hosts. If using `openenv` tooling, run `openenv push` from the environment directory (where `openenv.yaml` is located) and follow its prompts. | |
| ## Next steps | |
| - Verify the server locally with `uvicorn` and exercise the client in a small script. | |
| - Build the Docker image and test containerized runs. | |
| - (Optional) Deploy to a Spaces/Cloud environment for public testing. | |
| --- | |
| See [client.py](client.py) and [server/app.py](server/app.py) for implementation details. | |