StarTripper/ticket_ordering

1---2title: Ticket Ordering Environment Server3emoji: 🎟️4colorFrom: blue5colorTo: blue6sdk: docker7pinned: false8app_port: 80009base_path: /web10tags:11  - openenv12---13 14# Ticket Ordering Environment15 16An environment that can be used to prioritize tickets by an arbitrary metric of importance. Perfect for ordering things like GitHub issues,17Jira tickets, etc.18 19## Quick Start20 21The simplest way to use the Ticket Ordering environment is through the `TicketOrderingEnv` class:22 23```python24from ticket_ordering import TicketOrderingAction, TicketOrderingEnv25import random26 27try:28    # Create environment from Docker image29    ticket_orderingenv = TicketOrderingEnv.from_docker_image("ticket_ordering-env:latest")30 31    # Reset32    result = ticket_orderingenv.reset()33    print(f"Reset: {result.observation}")34 35    result = ticket_orderingenv.step(36        TicketOrderingAction(37            candidate_priority=0.5,38            candidate_summary="issue",39            next_reference_ids=[],40            next_candidate_id=random.choice(list(obs.ticket_heuristics.keys())),41            end_ordering=False,42        )43    )44    print(f"Step observation: {result.observation}")45    print(f"Step reward: {result.reward}")46 47finally:48    # Always clean up49    ticket_orderingenv.close()50```51 52That's it! The `TicketOrderingEnv.from_docker_image()` method handles:53- Starting the Docker container54- Waiting for the server to be ready55- Connecting to the environment56- Container cleanup when you call `close()`57 58## Building the Docker Image59 60Before using the environment, you need to build the Docker image:61 62```bash63# From project root64docker build -t ticket_ordering-env:latest -f server/Dockerfile .65```66 67## Deploying to Hugging Face Spaces68 69You can easily deploy your OpenEnv environment to Hugging Face Spaces using the `openenv push` command:70 71```bash72# From the environment directory (where openenv.yaml is located)73openenv push74 75# Or specify options76openenv push --namespace my-org --private77```78 79The `openenv push` command will:801. Validate that the directory is an OpenEnv environment (checks for `openenv.yaml`)812. Prepare a custom build for Hugging Face Docker space (enables web interface)823. Upload to Hugging Face (ensuring you're logged in)83 84### Prerequisites85 86- Authenticate with Hugging Face: The command will prompt for login if not already authenticated87 88### Options89 90- `--directory`, `-d`: Directory containing the OpenEnv environment (defaults to current directory)91- `--repo-id`, `-r`: Repository ID in format 'username/repo-name' (defaults to 'username/env-name' from openenv.yaml)92- `--base-image`, `-b`: Base Docker image to use (overrides Dockerfile FROM)93- `--private`: Deploy the space as private (default: public)94 95### Examples96 97```bash98# Push to your personal namespace (defaults to username/env-name from openenv.yaml)99openenv push100 101# Push to a specific repository102openenv push --repo-id my-org/my-env103 104# Push with a custom base image105openenv push --base-image ghcr.io/meta-pytorch/openenv-base:latest106 107# Push as a private space108openenv push --private109 110# Combine options111openenv push --repo-id my-org/my-env --base-image custom-base:latest --private112```113 114After deployment, your space will be available at:115`https://huggingface.co/spaces/<repo-id>`116 117The deployed space includes:118- **Web Interface** at `/web` - Interactive UI for exploring the environment119- **API Documentation** at `/docs` - Full OpenAPI/Swagger interface120- **Health Check** at `/health` - Container health monitoring121- **WebSocket** at `/ws` - Persistent session endpoint for low-latency interactions122 123## Environment Details124 125### Action126**TicketOrderingAction**: Contains the following fields:127- `candidate_priority` (float) - Assigned priority score for the candidate ticket, relative to other tickets.128- `candidate_summary` (str) - Short summary describing the candidate ticket, capturing key context for future comparisons.129- `next_reference_ids` (list[int]) - IDs of tickets to request as references in the next step, used to guide further comparisons.130- `next_candidate_id` (int) - ID of the next ticket to evaluate as the candidate in the following step.131- `end_ordering` (bool) - Whether the agent thinks it has finished ordering all tickets and wants to terminate the episode.132 133### Observation134**TicketOrderingObservation**: Contains the following:135- `reward` (float) - Reward based on last priority assignment and end ordering decision.136- `done` (bool) - True if `end_ordering` is set to true in the action or the episode has reached the maximum step count.137- `metadata` (dict) - Additional info.138 139- `ordering_criteria` (str) - Criteria by which tickets should be ordered.140- `reference_tickets` (list[Ticket]) - Subset of tickets provided as references to help evaluate and compare the current candidate ticket.141- `candidate_ticket` (Ticket) - The ticket currently being evaluated and assigned a heuristic by the agent.142- `ticket_heuristics` (dict[int, TicketHeuristic]) - Known heuristics for previously evaluated tickets, keyed by ticket ID, used for relative comparison.143- `total_tickets` (int) - Total number of tickets in the environment that need to be ordered.144- `completed_iterations` (int) - Number of ordering steps completed so far in the current episode.145 146 147### Reward148The reward is calculated as: `(post_action_optimality - pre_action_optimality) - (1.5 - current_step / max_steps) * action_end_ordering`149 150## Advanced Usage151 152### Connecting to an Existing Server153 154If you already have a Ticket Ordering environment server running, you can connect directly:155 156```python157from ticket_ordering import TicketOrderingEnv158 159# Connect to existing server160ticket_orderingenv = TicketOrderingEnv(base_url="<ENV_HTTP_URL_HERE>")161 162# Use as normal163result = ticket_orderingenv.reset()164result = ticket_orderingenv.step(...)165```166 167Note: When connecting to an existing server, `ticket_orderingenv.close()` will NOT stop the server.168 169### Using the Context Manager170 171The client supports context manager usage for automatic connection management:172 173```python174from ticket_ordering import TicketOrderingAction, TicketOrderingEnv175 176# Connect with context manager (auto-connects and closes)177with TicketOrderingEnv(base_url="http://localhost:8000") as env:178    result = env.reset()179    result = env.step(...)180```181 182The client uses WebSocket connections for:183- **Lower latency**: No HTTP connection overhead per request184- **Persistent session**: Server maintains your environment state185- **Efficient for episodes**: Better for many sequential steps186 187### Concurrent WebSocket Sessions188 189The server supports multiple concurrent WebSocket connections. To enable this,190modify `server/app.py` to use factory mode:191 192```python193# In server/app.py - use factory mode for concurrent sessions194app = create_app(195    TicketOrderingEnvironment,  # Pass class, not instance196    TicketOrderingAction,197    TicketOrderingObservation,198    max_concurrent_envs=4,  # Allow 4 concurrent sessions199)200```201 202Then multiple clients can connect simultaneously.203 204 205## Development & Testing206 207### Direct Environment Testing208 209Test the environment logic directly without starting the HTTP server:210 211```bash212# From the server directory213python3 server/ticket_ordering_environment.py214```215 216This verifies that:217- Environment resets correctly218- Step executes actions properly219- State tracking works220- Rewards are calculated correctly221 222### Running Locally223 224Run the server locally for development:225 226```bash227uvicorn server.app:app --reload228```229 230## Project Structure231 232```233ticket_ordering/234├── client.py              # Client for interacting with the Ticket Ordering environment235├── docker-build.sh        # Script to build the Docker image for the project236├── .dockerignore          # Files and directories excluded from Docker builds237├── inference.py           # Main inference logic for running ticket ordering or model predictions238├── __init__.py            # Package initialization and exports239├── load-env-vars.sh       # Script to load environment variables (e.g., API keys, configs)240├── models.py              # Pydantic models (Ticket, Observation, Action, etc.)241├── openenv.yaml           # OpenEnv configuration / environment manifest242├── problem_generator.py   # Generates synthetic ticket ordering problems for testing/training243├── pyproject.toml         # Project metadata and dependency definitions244├── README.md              # Project documentation and usage instructions245├── server/                # Server-side implementation246│   ├── app.py             # FastAPI app exposing HTTP/WebSocket endpoints247│   ├── Dockerfile         # Docker image definition for the server248│   ├── __init__.py        # Server module exports249│   ├── requirements.txt   # Python dependencies for the server environment250│   └── ticket_ordering_environment.py  # Core environment logic and state transitions251├── uv.lock                # Locked dependency versions (generated by uv)252└── validation-script.sh   # Script to validate environment behavior or submission correctness253```254