README.md

metadata

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:

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:

docker build -t agterm-env:latest -f server/Dockerfile .

Run the server locally (development):

# from repository root
uvicorn server.app:app --reload

Or run the built image:

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:

python3 server/agterm_environment.py

Run the FastAPI app locally:

uvicorn server.app:app --reload

Project layout

• client.py — Python client implementation and helpers
• models.py — pydantic models for actions and observations
• server/app.py — FastAPI application entry
• server/agterm_environment.py — core environment logic (scriptable)
• server/Dockerfile — image definition used to build agterm-env
• openenv.yaml — OpenEnv manifest
• 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 and server/app.py for implementation details.