CoolFace
Apppublic

akhilgattu02/autonomous_navigation

sourceHugging Faceupdated 5mo agoView on Hugging Face
0likes
App README

Autonomous Navigation Environment

A simple test environment that echoes back messages. Perfect for testing the env APIs as well as demonstrating environment usage patterns.

Quick Start

The simplest way to use the Autonomous Navigation environment is through the AutonomousNavigationEnv class:

python
from autonomous_navigation import AutonomousNavigationAction, AutonomousNavigationEnv

try:
    # Create environment from Docker image
    autonomous_navigationenv = AutonomousNavigationEnv.from_docker_image("autonomous_navigation-env:latest")

    # Reset
    result = autonomous_navigationenv.reset()
    print(f"Reset: {result.observation.echoed_message}")

    # Send multiple messages
    messages = ["Hello, World!", "Testing echo", "Final message"]

    for msg in messages:
        result = autonomous_navigationenv.step(AutonomousNavigationAction(message=msg))
        print(f"Sent: '{msg}'")
        print(f"  → Echoed: '{result.observation.echoed_message}'")
        print(f"  → Length: {result.observation.message_length}")
        print(f"  → Reward: {result.reward}")

finally:
    # Always clean up
    autonomous_navigationenv.close()

That's it! The AutonomousNavigationEnv.from_docker_image() method handles:

  • —Starting the Docker container
  • —Waiting for the server to be ready
  • —Connecting to the environment
  • —Container cleanup when you call close()

Building the Docker Image

Before using the environment, you need to build the Docker image:

bash
# From project root
docker build -t autonomous_navigation-env:latest -f server/Dockerfile .

Deploying to Hugging Face Spaces

You can easily deploy your OpenEnv environment to Hugging Face Spaces using the openenv push command:

bash
# From the environment directory (where openenv.yaml is located)
openenv push

# Or specify options
openenv push --namespace my-org --private

The openenv push command will:

  1. 1.Validate that the directory is an OpenEnv environment (checks for openenv.yaml)
  2. 2.Prepare a custom build for Hugging Face Docker space (enables web interface)
  3. 3.Upload to Hugging Face (ensuring you're logged in)

Prerequisites

  • —Authenticate with Hugging Face: The command will prompt for login if not already authenticated

Options

  • —--directory, -d: Directory containing the OpenEnv environment (defaults to current directory)
  • —--repo-id, -r: Repository ID in format 'username/repo-name' (defaults to 'username/env-name' from openenv.yaml)
  • —--base-image, -b: Base Docker image to use (overrides Dockerfile FROM)
  • —--private: Deploy the space as private (default: public)

Examples

bash
# Push to your personal namespace (defaults to username/env-name from openenv.yaml)
openenv push

# Push to a specific repository
openenv push --repo-id my-org/my-env

# Push with a custom base image
openenv push --base-image ghcr.io/meta-pytorch/openenv-base:latest

# Push as a private space
openenv push --private

# Combine options
openenv push --repo-id my-org/my-env --base-image custom-base:latest --private

After deployment, your space will be available at: https://huggingface.co/spaces/<repo-id>

The deployed space includes:

  • —Web Interface at /web - Interactive UI for exploring the environment
  • —API Documentation at /docs - Full OpenAPI/Swagger interface
  • —Health Check at /health - Container health monitoring
  • —WebSocket at /ws - Persistent session endpoint for low-latency interactions

Environment Details

Action

AutonomousNavigationAction: Contains a single field

  • —message (str) - The message to echo back

Observation

AutonomousNavigationObservation: Contains the echo response and metadata

  • —echoed_message (str) - The message echoed back
  • —message_length (int) - Length of the message
  • —reward (float) - Reward based on message length (length × 0.1)
  • —done (bool) - Always False for echo environment
  • —metadata (dict) - Additional info like step count

Reward

The reward is calculated as: message_length × 0.1

  • —"Hi" → reward: 0.2
  • —"Hello, World!" → reward: 1.3
  • —Empty message → reward: 0.0

Advanced Usage

Connecting to an Existing Server

If you already have a Autonomous Navigation environment server running, you can connect directly:

python
from autonomous_navigation import AutonomousNavigationEnv

# Connect to existing server
autonomous_navigationenv = AutonomousNavigationEnv(base_url="<ENV_HTTP_URL_HERE>")

# Use as normal
result = autonomous_navigationenv.reset()
result = autonomous_navigationenv.step(AutonomousNavigationAction(message="Hello!"))

Note: When connecting to an existing server, autonomous_navigationenv.close() will NOT stop the server.

Using the Context Manager

The client supports context manager usage for automatic connection management:

python
from autonomous_navigation import AutonomousNavigationAction, AutonomousNavigationEnv

# Connect with context manager (auto-connects and closes)
with AutonomousNavigationEnv(base_url="http://localhost:8000") as env:
    result = env.reset()
    print(f"Reset: {result.observation.echoed_message}")
    # Multiple steps with low latency
    for msg in ["Hello", "World", "!"]:
        result = env.step(AutonomousNavigationAction(message=msg))
        print(f"Echoed: {result.observation.echoed_message}")

The client uses WebSocket connections for:

  • —Lower latency: No HTTP connection overhead per request
  • —Persistent session: Server maintains your environment state
  • —Efficient for episodes: Better for many sequential steps

Concurrent WebSocket Sessions

The server supports multiple concurrent WebSocket connections. To enable this, modify server/app.py to use factory mode:

python
# In server/app.py - use factory mode for concurrent sessions
app = create_app(
    AutonomousNavigationEnvironment,  # Pass class, not instance
    AutonomousNavigationAction,
    AutonomousNavigationObservation,
    max_concurrent_envs=4,  # Allow 4 concurrent sessions
)

Then multiple clients can connect simultaneously:

python
from autonomous_navigation import AutonomousNavigationAction, AutonomousNavigationEnv
from concurrent.futures import ThreadPoolExecutor

def run_episode(client_id: int):
    with AutonomousNavigationEnv(base_url="http://localhost:8000") as env:
        result = env.reset()
        for i in range(10):
            result = env.step(AutonomousNavigationAction(message=f"Client {client_id}, step {i}"))
        return client_id, result.observation.message_length

# Run 4 episodes concurrently
with ThreadPoolExecutor(max_workers=4) as executor:
    results = list(executor.map(run_episode, range(4)))

Development & Testing

Direct Environment Testing

Test the environment logic directly without starting the HTTP server:

bash
# From the server directory
python3 server/autonomous_navigation_environment.py

This verifies that:

  • —Environment resets correctly
  • —Step executes actions properly
  • —State tracking works
  • —Rewards are calculated correctly

Running Locally

Run the server locally for development:

bash
uvicorn server.app:app --reload

Autonomous Navigation OpenEnv Environment

Overview

This project implements a real-world autonomous navigation environment using the OpenEnv specification. The environment simulates a robot navigating a grid world with obstacles, designed for training and evaluating AI agents on real-world navigation tasks.

Features

  • —Real-world scenario: The agent must navigate from a start position to a goal, avoiding obstacles.
  • —OpenEnv Spec: Implements reset(), step(), and state() APIs with typed models.
  • —Multiple Tasks: Includes at least three tasks (easy, medium, hard) with increasing difficulty and graders that score agent performance between 0.0 and 1.0.
  • —Meaningful Rewards: Dense reward function based on progress toward the goal and obstacle avoidance.
  • —Docker & HF Spaces Ready: Includes a Dockerfile and is deployable to Hugging Face Spaces.
  • —Baseline Agent: inference.py script for reproducible agent evaluation.

Action & Observation Spaces

  • —Action:
  • —direction: One of up, down, left, right (move agent in grid)
  • —Observation:
  • —position: Agent's (x, y) position
  • —goal_position: Goal (x, y) position
  • —done: Whether the episode is finished
  • —reward: Reward for the last action
  • —metadata: Additional info (e.g., obstacles, step count)

Tasks & Graders

  • —Easy: Small grid, few obstacles
  • —Medium: Larger grid, more obstacles
  • —Hard: Largest grid, complex obstacle layout
  • —Each task has a grader that returns a normalized score (0.0–1.0) based on agent performance.

Setup & Usage

  1. 1.Install dependencies:
sh
   pip install -r requirements.txt
   pip install openenv-core
  1. 1.Set environment variables: Create a .env file with:
env
   API_BASE_URL=https://api.openai.com/v1
   MODEL_NAME=gpt-3.5-turbo
   HF_TOKEN=your_hf_or_openai_api_key
  1. 1.Run locally:
sh
   uv run --project . server
  1. 1.Run baseline agent:
sh
   python3 inference.py
  1. 1.Validate submission:
sh
   ./scripts/validate-submission.sh <your-hf-space-url>

Deployment

  • —Deploy to Hugging Face Spaces (Docker backend recommended)
  • —Ensure /reset endpoint responds (OpenEnv API)
  • —Use openenv push for automated deployment

Project Structure

├── server/
│   ├── app.py
│   ├── autonomous_navigation_environment.py
│   ├── Dockerfile
├── models.py
├── client.py
├── inference.py
├── openenv.yaml
├── requirements.txt
├── .env
├── scripts/
│   └── validate-submission.sh
└── README.md

References

Author: akhilgattu02