Upload folder using huggingface_hub

Dockerfile

@@ -0,0 +1,81 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+# Multi-stage build using openenv-base
+# This Dockerfile is flexible and works for both:
+# - In-repo environments (with local OpenEnv sources)
+# - Standalone environments (with openenv from PyPI/Git)
+# The build script (openenv build) handles context detection and sets appropriate build args.
+
+ARG BASE_IMAGE=ghcr.io/meta-pytorch/openenv-base:latest
+FROM ${BASE_IMAGE} AS builder
+
+WORKDIR /app
+
+# Ensure git is available (required for installing dependencies from VCS)
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends git && \
+    rm -rf /var/lib/apt/lists/*
+
+# Build argument to control whether we're building standalone or in-repo
+ARG BUILD_MODE=in-repo
+ARG ENV_NAME=lingua_env
+
+# Copy environment code (always at root of build context)
+COPY . /app/env
+
+# For in-repo builds, openenv is already vendored in the build context
+# For standalone builds, openenv will be installed via pyproject.toml
+WORKDIR /app/env
+
+# Ensure uv is available (for local builds where base image lacks it)
+RUN if ! command -v uv >/dev/null 2>&1; then \
+        curl -LsSf https://astral.sh/uv/install.sh | sh && \
+        mv /root/.local/bin/uv /usr/local/bin/uv && \
+        mv /root/.local/bin/uvx /usr/local/bin/uvx; \
+    fi
+    
+# Install dependencies using uv sync
+# If uv.lock exists, use it; otherwise resolve on the fly
+RUN --mount=type=cache,target=/root/.cache/uv \
+    if [ -f uv.lock ]; then \
+        uv sync --frozen --no-install-project --no-editable; \
+    else \
+        uv sync --no-install-project --no-editable; \
+    fi
+
+RUN --mount=type=cache,target=/root/.cache/uv \
+    if [ -f uv.lock ]; then \
+        uv sync --frozen --no-editable; \
+    else \
+        uv sync --no-editable; \
+    fi
+
+# Final runtime stage
+FROM ${BASE_IMAGE}
+
+WORKDIR /app
+
+# Copy the virtual environment from builder
+COPY --from=builder /app/env/.venv /app/.venv
+
+# Copy the environment code
+COPY --from=builder /app/env /app/env
+
+# Set PATH to use the virtual environment
+ENV PATH="/app/.venv/bin:$PATH"
+
+# Set PYTHONPATH so imports work correctly
+ENV PYTHONPATH="/app/env:$PYTHONPATH"
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+    CMD curl -f http://localhost:8000/health || exit 1
+
+# Run the FastAPI server
+# The module path is constructed to work with the /app/env structure
+ENV ENABLE_WEB_INTERFACE=true
+CMD ["sh", "-c", "cd /app/env && uvicorn server.app:app --host 0.0.0.0 --port 8000"]

README.md

@@ -1,10 +1,255 @@
 ---
-title: Lingua Env
-emoji: 🐢
-colorFrom: green
+title: Lingua Env Environment Server
+emoji: 📟
+colorFrom: yellow
 colorTo: red
 sdk: docker
 pinned: false
+app_port: 8000
+base_path: /web
+tags:
+  - openenv
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Lingua Env 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 Lingua Env environment is through the `LinguaEnv` class:
+
+```python
+from lingua_env import LinguaAction, LinguaEnv
+
+try:
+    # Create environment from Docker image
+    lingua_envenv = LinguaEnv.from_docker_image("lingua_env-env:latest")
+
+    # Reset
+    result = lingua_envenv.reset()
+    print(f"Reset: {result.observation.echoed_message}")
+
+    # Send multiple messages
+    messages = ["Hello, World!", "Testing echo", "Final message"]
+
+    for msg in messages:
+        result = lingua_envenv.step(LinguaAction(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
+    lingua_envenv.close()
+```
+
+That's it! The `LinguaEnv.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 lingua_env-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. Validate that the directory is an OpenEnv environment (checks for `openenv.yaml`)
+2. Prepare a custom build for Hugging Face Docker space (enables web interface)
+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
+**LinguaAction**: Contains a single field
+- `message` (str) - The message to echo back
+
+### Observation
+**LinguaObservation**: 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 Lingua Env environment server running, you can connect directly:
+
+```python
+from lingua_env import LinguaEnv
+
+# Connect to existing server
+lingua_envenv = LinguaEnv(base_url="<ENV_HTTP_URL_HERE>")
+
+# Use as normal
+result = lingua_envenv.reset()
+result = lingua_envenv.step(LinguaAction(message="Hello!"))
+```
+
+Note: When connecting to an existing server, `lingua_envenv.close()` will NOT stop the server.
+
+### Using the Context Manager
+
+The client supports context manager usage for automatic connection management:
+
+```python
+from lingua_env import LinguaAction, LinguaEnv
+
+# Connect with context manager (auto-connects and closes)
+with LinguaEnv(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(LinguaAction(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(
+    LinguaEnvironment,  # Pass class, not instance
+    LinguaAction,
+    LinguaObservation,
+    max_concurrent_envs=4,  # Allow 4 concurrent sessions
+)
+```
+
+Then multiple clients can connect simultaneously:
+
+```python
+from lingua_env import LinguaAction, LinguaEnv
+from concurrent.futures import ThreadPoolExecutor
+
+def run_episode(client_id: int):
+    with LinguaEnv(base_url="http://localhost:8000") as env:
+        result = env.reset()
+        for i in range(10):
+            result = env.step(LinguaAction(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/lingua_env_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
+```
+
+## Project Structure
+
+```
+lingua_env/
+├── .dockerignore         # Docker build exclusions
+├── __init__.py            # Module exports
+├── README.md              # This file
+├── openenv.yaml           # OpenEnv manifest
+├── pyproject.toml         # Project metadata and dependencies
+├── uv.lock                # Locked dependencies (generated)
+├── client.py              # LinguaEnv client
+├── models.py              # Action and Observation models
+└── server/
+    ├── __init__.py        # Server module exports
+    ├── lingua_env_environment.py  # Core environment logic
+    ├── app.py             # FastAPI application (HTTP + WebSocket endpoints)
+    └── Dockerfile         # Container image definition
+```

__init__.py

@@ -0,0 +1,16 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""Lingua Env Environment."""
+
+from .client import LinguaEnv
+from .models import LinguaAction, LinguaObservation
+
+__all__ = [
+    "LinguaAction",
+    "LinguaObservation",
+    "LinguaEnv",
+]

client.py

@@ -0,0 +1,99 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""Lingua Env Environment Client."""
+
+from typing import Dict
+
+from openenv.core.client_types import StepResult
+from openenv.core.env_server.types import State
+from openenv.core import EnvClient
+
+from .models import LinguaAction, LinguaObservation
+
+
+class LinguaEnv(
+    EnvClient[LinguaAction, LinguaObservation, dict]
+):
+    """
+    Client for the Lingua Env Environment.
+
+    This client maintains a persistent WebSocket connection to the environment server,
+    enabling efficient multi-step interactions with lower latency.
+    Each client instance has its own dedicated environment session on the server.
+
+    Example:
+        >>> # Connect to a running server
+        >>> with LinguaEnv(base_url="http://localhost:8000") as client:
+        ...     result = client.reset()
+        ...     print(result.observation.echoed_message)
+        ...
+        ...     result = client.step(LinguaAction(message="Hello!"))
+        ...     print(result.observation.echoed_message)
+
+    Example with Docker:
+        >>> # Automatically start container and connect
+        >>> client = LinguaEnv.from_docker_image("lingua_env-env:latest")
+        >>> try:
+        ...     result = client.reset()
+        ...     result = client.step(LinguaAction(message="Test"))
+        ... finally:
+        ...     client.close()
+    """
+
+    def _step_payload(self, action: LinguaAction) -> Dict:
+        """
+        Convert LinguaAction to JSON payload for step message.
+
+        Args:
+            action: LinguaAction instance
+
+        Returns:
+            Dictionary representation suitable for JSON encoding
+        """
+        return {
+            "message": action.message,
+        }
+
+    def _parse_result(self, payload: Dict) -> StepResult[LinguaObservation]:
+        """
+        Parse server response into StepResult[LinguaObservation].
+
+        Args:
+            payload: JSON response data from server
+
+        Returns:
+            StepResult with LinguaObservation
+        """
+        obs_data = payload.get("observation", {})
+        observation = LinguaObservation(
+            echoed_message=obs_data.get("echoed_message", ""),
+            message_length=obs_data.get("message_length", 0),
+            done=payload.get("done", False),
+            reward=payload.get("reward"),
+            metadata=obs_data.get("metadata", {}),
+        )
+
+        return StepResult(
+            observation=observation,
+            reward=payload.get("reward"),
+            done=payload.get("done", False),
+        )
+
+    def _parse_state(self, payload: Dict) -> State:
+        """
+        Parse server response into State object.
+
+        Args:
+            payload: JSON response from state request
+
+        Returns:
+            State object with episode_id and step_count
+        """
+        return State(
+            episode_id=payload.get("episode_id"),
+            step_count=payload.get("step_count", 0),
+        )

data/ambiguous_examples.jsonl

@@ -0,0 +1,10 @@
+{"sentence": ["Начальник", "областного", "управления", "связи", "Семен", "Еремеевич", "был", "человек", "простой", ",", "приходил", "на", "работу", "всегда", "вовремя", ",", "здоровался", "с", "секретаршей", "за", "руку", "и", "иногда", "даже", "писал", "в", "стенгазету", "заметки", "под", "псевдонимом", "\"", "Муха", "\"", "."], "target_index": 1, "word": "областного", "candidate_parses": [{"lemma": "областной", "tag": "ADJF neut,sing,gent", "score": 0.727272}, {"lemma": "областной", "tag": "ADJF masc,sing,gent", "score": 0.181818}, {"lemma": "областной", "tag": "ADJF anim,masc,sing,accs", "score": 0.090909}], "gold": {"lemma": "областной", "upos": "ADJ", "feats": {"Case": "Gen", "Degree": "Pos", "Gender": "Neut", "Number": "Sing"}}}
+{"sentence": ["Начальник", "областного", "управления", "связи", "Семен", "Еремеевич", "был", "человек", "простой", ",", "приходил", "на", "работу", "всегда", "вовремя", ",", "здоровался", "с", "секретаршей", "за", "руку", "и", "иногда", "даже", "писал", "в", "стенгазету", "заметки", "под", "псевдонимом", "\"", "Муха", "\"", "."], "target_index": 2, "word": "управления", "candidate_parses": [{"lemma": "управление", "tag": "NOUN,inan,neut sing,gent", "score": 0.989071}, {"lemma": "управление", "tag": "NOUN,inan,neut plur,nomn", "score": 0.005464}, {"lemma": "управление", "tag": "NOUN,inan,neut plur,accs", "score": 0.005464}], "gold": {"lemma": "управление", "upos": "NOUN", "feats": {"Animacy": "Inan", "Case": "Gen", "Gender": "Neut", "Number": "Sing"}}}
+{"sentence": ["Начальник", "областного", "управления", "связи", "Семен", "Еремеевич", "был", "человек", "простой", ",", "приходил", "на", "работу", "всегда", "вовремя", ",", "здоровался", "с", "секретаршей", "за", "руку", "и", "иногда", "даже", "писал", "в", "стенгазету", "заметки", "под", "псевдонимом", "\"", "Муха", "\"", "."], "target_index": 3, "word": "связи", "candidate_parses": [{"lemma": "связь", "tag": "NOUN,inan,femn sing,gent", "score": 0.759562}, {"lemma": "связь", "tag": "NOUN,inan,femn plur,accs", "score": 0.103825}, {"lemma": "связь", "tag": "NOUN,inan,femn plur,nomn", "score": 0.087431}, {"lemma": "связь", "tag": "NOUN,inan,femn sing,datv", "score": 0.032786}, {"lemma": "связь", "tag": "NOUN,inan,femn sing,loc2", "score": 0.010928}], "gold": {"lemma": "связь", "upos": "NOUN", "feats": {"Animacy": "Inan", "Case": "Gen", "Gender": "Fem", "Number": "Sing"}}}
+{"sentence": ["Начальник", "областного", "управления", "связи", "Семен", "Еремеевич", "был", "человек", "простой", ",", "приходил", "на", "работу", "всегда", "вовремя", ",", "здоровался", "с", "секретаршей", "за", "руку", "и", "иногда", "даже", "писал", "в", "стенгазету", "заметки", "под", "псевдонимом", "\"", "Муха", "\"", "."], "target_index": 7, "word": "человек", "candidate_parses": [{"lemma": "человек", "tag": "NOUN,anim,masc sing,nomn", "score": 0.569458}, {"lemma": "человек", "tag": "NOUN,anim,masc plur,gent", "score": 0.430541}], "gold": {"lemma": "человек", "upos": "NOUN", "feats": {"Animacy": "Anim", "Case": "Nom", "Gender": "Masc", "Number": "Sing"}}}
+{"sentence": ["Начальник", "областного", "управления", "связи", "Семен", "Еремеевич", "был", "человек", "простой", ",", "приходил", "на", "работу", "всегда", "вовремя", ",", "здоровался", "с", "секретаршей", "за", "руку", "и", "иногда", "даже", "писал", "в", "стенгазету", "заметки", "под", "псевдонимом", "\"", "Муха", "\"", "."], "target_index": 8, "word": "простой", "candidate_parses": [{"lemma": "простой", "tag": "ADJF,Qual femn,sing,gent", "score": 0.225806}, {"lemma": "простой", "tag": "ADJF,Qual femn,sing,datv", "score": 0.225806}, {"lemma": "простой", "tag": "ADJF,Qual femn,sing,ablt", "score": 0.193548}, {"lemma": "простой", "tag": "ADJF,Qual femn,sing,loct", "score": 0.129032}, {"lemma": "простой", "tag": "NOUN,inan,masc sing,nomn", "score": 0.064516}], "gold": {"lemma": "простой", "upos": "ADJ", "feats": {"Case": "Nom", "Degree": "Pos", "Gender": "Masc", "Number": "Sing"}}}
+{"sentence": ["Начальник", "областного", "управления", "связи", "Семен", "Еремеевич", "был", "человек", "простой", ",", "приходил", "на", "работу", "всегда", "вовремя", ",", "здоровался", "с", "секретаршей", "за", "руку", "и", "иногда", "даже", "писал", "в", "стенгазету", "заметки", "под", "псевдонимом", "\"", "Муха", "\"", "."], "target_index": 11, "word": "на", "candidate_parses": [{"lemma": "на", "tag": "PREP", "score": 0.998961}, {"lemma": "на", "tag": "PRCL", "score": 0.000849}, {"lemma": "на", "tag": "INTJ", "score": 0.000188}], "gold": {"lemma": "на", "upos": "ADP", "feats": {}}}
+{"sentence": ["Начальник", "областного", "управления", "связи", "Семен", "Еремеевич", "был", "человек", "простой", ",", "приходил", "на", "работу", "всегда", "вовремя", ",", "здоровался", "с", "секретаршей", "за", "руку", "и", "иногда", "даже", "писал", "в", "стенгазету", "заметки", "под", "псевдонимом", "\"", "Муха", "\"", "."], "target_index": 17, "word": "с", "candidate_parses": [{"lemma": "с", "tag": "PREP", "score": 0.997628}, {"lemma": "с", "tag": "NOUN,inan,femn,Fixd,Abbr plur,nomn", "score": 0.000406}, {"lemma": "с", "tag": "PRCL", "score": 0.000271}, {"lemma": "с", "tag": "NOUN,inan,femn,Fixd,Abbr sing,nomn", "score": 6.7e-05}, {"lemma": "с", "tag": "NOUN,inan,femn,Fixd,Abbr sing,gent", "score": 6.7e-05}], "gold": {"lemma": "с", "upos": "ADP", "feats": {}}}
+{"sentence": ["Начальник", "областного", "управления", "связи", "Семен", "Еремеевич", "был", "человек", "простой", ",", "приходил", "на", "работу", "всегда", "вовремя", ",", "здоровался", "с", "секретаршей", "за", "руку", "и", "иногда", "даже", "писал", "в", "стенгазету", "заметки", "под", "псевдонимом", "\"", "Муха", "\"", "."], "target_index": 21, "word": "и", "candidate_parses": [{"lemma": "и", "tag": "CONJ", "score": 0.998263}, {"lemma": "и", "tag": "PRCL", "score": 0.000306}, {"lemma": "и", "tag": "INTJ", "score": 0.000204}, {"lemma": "и", "tag": "NOUN,anim,masc,Fixd,Abbr sing,nomn", "score": 0.000102}, {"lemma": "и", "tag": "NOUN,anim,masc,Fixd,Abbr sing,gent", "score": 0.000102}], "gold": {"lemma": "и", "upos": "CCONJ", "feats": {}}}
+{"sentence": ["Начальник", "областного", "управления", "связи", "Семен", "Еремеевич", "был", "человек", "простой", ",", "приходил", "на", "работу", "всегда", "вовремя", ",", "здоровался", "с", "секретаршей", "за", "руку", "и", "иногда", "даже", "писал", "в", "стенгазету", "заметки", "под", "псевдонимом", "\"", "Муха", "\"", "."], "target_index": 24, "word": "писал", "candidate_parses": [{"lemma": "писать", "tag": "VERB,impf,tran masc,sing,past,indc", "score": 0.99115}, {"lemma": "писать", "tag": "VERB,impf,intr masc,sing,past,indc", "score": 0.008849}], "gold": {"lemma": "писать", "upos": "VERB", "feats": {"Aspect": "Imp", "Gender": "Masc", "Mood": "Ind", "Number": "Sing", "Tense": "Past", "VerbForm": "Fin", "Voice": "Act"}}}
+{"sentence": ["Начальник", "областного", "управления", "связи", "Семен", "Еремеевич", "был", "человек", "простой", ",", "приходил", "на", "работу", "всегда", "вовремя", ",", "здоровался", "с", "секретаршей", "за", "руку", "и", "иногда", "даже", "писал", "в", "стенгазету", "заметки", "под", "псевдонимом", "\"", "Муха", "\"", "."], "target_index": 25, "word": "в", "candidate_parses": [{"lemma": "в", "tag": "PREP", "score": 0.999327}, {"lemma": "в", "tag": "NOUN,inan,masc,Fixd,Abbr sing,gent", "score": 0.000249}, {"lemma": "в", "tag": "NOUN,inan,masc,Fixd,Abbr sing,loct", "score": 5.7e-05}, {"lemma": "в", "tag": "NOUN,inan,masc,Fixd,Abbr sing,nomn", "score": 1.9e-05}, {"lemma": "в", "tag": "NOUN,inan,masc,Fixd,Abbr sing,datv", "score": 1.9e-05}], "gold": {"lemma": "в", "upos": "ADP", "feats": {}}}

models.py

@@ -0,0 +1,32 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""
+Data models for the Lingua Env Environment.
+
+The lingua_env environment is a simple test environment that echoes back messages.
+"""
+
+from typing import Any
+
+from pydantic import Field
+from openenv.core.env_server import Action, Observation, State
+
+
+class LinguaAction(Action):
+    choice: int
+
+
+class LinguaObservation(Observation):
+    sentence: list[str]
+    target_index: int
+    word: str
+    candidate_parses: list[dict[str, Any]]
+
+
+class LinguaState(State):
+    gold: dict[str, Any] = Field(default_factory=dict)
+

openenv.yaml

@@ -0,0 +1,7 @@
+spec_version: 1
+name: lingua_env
+type: space
+runtime: fastapi
+app: server.app:app
+port: 8000
+

openenv_lingua_env.egg-info/PKG-INFO

@@ -0,0 +1,9 @@
+Metadata-Version: 2.4
+Name: openenv-lingua_env
+Version: 0.1.0
+Summary: Lingua Env environment for OpenEnv
+Requires-Python: >=3.10
+Requires-Dist: openenv-core[core]>=0.2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"

openenv_lingua_env.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+README.md
+pyproject.toml
+./__init__.py
+./client.py
+./models.py
+openenv_lingua_env.egg-info/PKG-INFO
+openenv_lingua_env.egg-info/SOURCES.txt
+openenv_lingua_env.egg-info/dependency_links.txt
+openenv_lingua_env.egg-info/entry_points.txt
+openenv_lingua_env.egg-info/requires.txt
+openenv_lingua_env.egg-info/top_level.txt
+server/__init__.py
+server/app.py
+server/lingua_env_environment.py

openenv_lingua_env.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

openenv_lingua_env.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+server = lingua_env.server.app:main

openenv_lingua_env.egg-info/requires.txt

@@ -0,0 +1,5 @@
+openenv-core[core]>=0.2.0
+
+[dev]
+pytest>=8.0.0
+pytest-cov>=4.0.0

openenv_lingua_env.egg-info/top_level.txt

@@ -0,0 +1 @@
+lingua_env

pyproject.toml

@@ -0,0 +1,45 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+[build-system]
+requires = ["setuptools>=45", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "openenv-lingua_env"
+version = "0.1.0"
+description = "Lingua Env environment for OpenEnv"
+requires-python = ">=3.10"
+dependencies = [
+    # Core OpenEnv runtime (provides FastAPI server + HTTP client types)
+    # install from github
+    # "openenv-core[core] @ git+https://github.com/meta-pytorch/OpenEnv.git",
+    "openenv-core[core]>=0.2.0",
+    # Environment-specific dependencies
+    # Add all dependencies needed for your environment here
+    # Examples:
+    # "numpy>=1.19.0",
+    # "torch>=2.0.0",
+    # "gymnasium>=0.29.0",
+    # "openspiel>=1.0.0",
+    # "smolagents>=1.22.0,<2",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-cov>=4.0.0",
+]
+
+[project.scripts]
+# Server entry point - enables running via: uv run --project . server
+# or: python -m lingua_env.server.app
+server = "lingua_env.server.app:main"
+
+[tool.setuptools]
+include-package-data = true
+packages = ["lingua_env", "lingua_env.server"]
+package-dir = { "lingua_env" = ".", "lingua_env.server" = "server" }

server/.ipynb_checkpoints/app-checkpoint.py

@@ -0,0 +1,60 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""
+FastAPI application for the Lingua Env Environment.
+
+This module creates an HTTP server that exposes the LinguaEnvironment
+over HTTP and WebSocket endpoints, compatible with EnvClient.
+
+Endpoints:
+    - POST /reset: Reset the environment
+    - POST /step: Execute an action
+    - GET /state: Get current environment state
+    - GET /schema: Get action/observation schemas
+    - WS /ws: WebSocket endpoint for persistent sessions
+
+Usage:
+    # Development (with auto-reload):
+    uvicorn server.app:app --reload --host 0.0.0.0 --port 8000
+
+    # Production:
+    uvicorn server.app:app --host 0.0.0.0 --port 8000 --workers 4
+
+    # Or run directly:
+    python -m server.app
+"""
+
+try:
+    from openenv.core.env_server.http_server import create_app
+except Exception as e:  # pragma: no cover
+    raise ImportError(
+        "openenv is required for the web interface. Install dependencies with:\n    uv sync\n"
+    ) from e
+
+from ..models import LinguaAction, LinguaObservation
+from .lingua_env_environment import LinguaEnvironment
+
+app = create_app(
+    LinguaEnvironment,
+    LinguaAction,
+    LinguaObservation,
+    env_name="lingua",
+    max_concurrent_envs=1,
+)
+
+
+def main() -> None:
+    import os
+    import uvicorn
+
+    host = os.getenv("HOST", "0.0.0.0")
+    port = int(os.getenv("PORT", "8000"))
+    uvicorn.run(app, host=host, port=port)
+
+
+if __name__ == "__main__":
+    main()

server/.ipynb_checkpoints/lingua_env_environment-checkpoint.py

@@ -0,0 +1,177 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""
+Lingua Env Environment Implementation.
+
+A simple test environment that echoes back messages sent to it.
+Perfect for testing HTTP server infrastructure.
+"""
+
+import json
+import random
+import uuid
+from pathlib import Path
+
+from openenv.core.env_server import Environment
+
+from ..models import LinguaAction, LinguaObservation, LinguaState
+
+
+PYMORPHY_FEATURE_MAP = {
+    "nomn": ("Case", "Nom"),
+    "gent": ("Case", "Gen"),
+    "datv": ("Case", "Dat"),
+    "accs": ("Case", "Acc"),
+    "ablt": ("Case", "Ins"),
+    "loct": ("Case", "Loc"),
+    "loc2": ("Case", "Loc"),
+    "sing": ("Number", "Sing"),
+    "plur": ("Number", "Plur"),
+    "masc": ("Gender", "Masc"),
+    "femn": ("Gender", "Fem"),
+    "neut": ("Gender", "Neut"),
+    "anim": ("Animacy", "Anim"),
+    "inan": ("Animacy", "Inan"),
+    "past": ("Tense", "Past"),
+    "pres": ("Tense", "Pres"),
+    "futr": ("Tense", "Fut"),
+    "1per": ("Person", "1"),
+    "2per": ("Person", "2"),
+    "3per": ("Person", "3"),
+    "COMP": ("Degree", "Cmp"),
+    "Supr": ("Degree", "Sup"),
+}
+
+POS_MAP = {
+    "NOUN": ["NOUN"],
+    "ADJ": ["ADJF", "ADJS"],
+    "VERB": ["VERB", "INFN", "GRND"],
+    "AUX": ["VERB", "INFN"],
+    "ADV": ["ADVB", "COMP", "PRED"],
+    "PRON": ["NPRO"],
+    "DET": ["ADJF", "NPRO"],
+    "NUM": ["NUMR"],
+    "ADP": ["PREP"],
+    "CCONJ": ["CONJ"],
+    "SCONJ": ["CONJ"],
+    "PART": ["PRCL"],
+    "INTJ": ["INTJ"],
+}
+
+
+def pymorphy_tag_to_ud_feats(tag_str: str) -> dict[str, str]:
+    feats = {}
+    for tok in tag_str.replace(",", " ").split():
+        if tok in PYMORPHY_FEATURE_MAP:
+            k, v = PYMORPHY_FEATURE_MAP[tok]
+            feats[k] = v
+    return feats
+
+
+def parse_pymorphy_pos(tag_str: str) -> str:
+    return tag_str.split()[0].split(",")[0]
+
+
+def score_candidate(candidate: dict, gold: dict) -> dict:
+    cand_lemma = candidate["lemma"]
+    cand_tag = candidate["tag"]
+
+    lemma_match = cand_lemma == gold["lemma"]
+
+    pymorphy_pos = parse_pymorphy_pos(cand_tag)
+    allowed_pos = POS_MAP.get(gold["upos"], [gold["upos"]])
+    pos_match = pymorphy_pos in allowed_pos
+
+    cand_feats = pymorphy_tag_to_ud_feats(cand_tag)
+    gold_feats = gold.get("feats", {})
+
+    reward = 0
+    if lemma_match:
+        reward += 1
+    if pos_match:
+        reward += 1
+
+    feature_matches = {}
+    for feat_name, gold_value in gold_feats.items():
+        cand_value = cand_feats.get(feat_name)
+        match = cand_value == gold_value
+        feature_matches[feat_name] = {
+            "candidate": cand_value,
+            "gold": gold_value,
+            "match": match,
+        }
+        if match:
+            reward += 1
+
+    return {
+        "reward": reward,
+        "lemma_match": lemma_match,
+        "pos_match": pos_match,
+        "candidate_feats": cand_feats,
+        "gold_feats": gold_feats,
+        "feature_matches": feature_matches,
+    }
+
+
+class LinguaEnvironment(Environment):
+    def __init__(self):
+        super().__init__()
+        data_path = Path(__file__).resolve().parents[1] / "data" / "ambiguous_examples.jsonl"
+        with open(data_path, "r", encoding="utf-8") as f:
+            self.examples = [json.loads(line) for line in f]
+
+        self.current = None
+        self._state = LinguaState(gold={})
+
+    def reset(self) -> LinguaObservation:
+        self.current = random.choice(self.examples)
+        self._state = LinguaState(
+            episode_id=str(uuid.uuid4()),
+            step_count=0,
+            gold=self.current["gold"],
+        )
+
+        return LinguaObservation(
+            sentence=list(self.current["sentence"]),
+            target_index=int(self.current["target_index"]),
+            word=str(self.current["word"]),
+            candidate_parses=list(self.current["candidate_parses"]),
+        )
+
+    def step(self, action: LinguaAction) -> LinguaObservation:
+        if self.current is None:
+            raise RuntimeError("Environment must be reset before step().")
+
+        choice = int(action.choice)
+        if choice < 0 or choice >= len(self.current["candidate_parses"]):
+            raise ValueError(f"Invalid choice index: {choice}")
+
+        self._state.step_count += 1
+
+        chosen = self.current["candidate_parses"][choice]
+        details = score_candidate(chosen, self.current["gold"])
+
+        self._state.gold = self.current["gold"]
+
+        obs = LinguaObservation(
+            sentence=list(self.current["sentence"]),
+            target_index=int(self.current["target_index"]),
+            word=str(self.current["word"]),
+            candidate_parses=list(self.current["candidate_parses"]),
+        )
+        obs.reward = float(details["reward"])
+        obs.done = True
+        obs.metadata = {
+            "chosen": chosen,
+            "gold": self.current["gold"],
+            "reward_breakdown": details,
+        }
+        return obs
+
+    @property
+    def state(self) -> LinguaState:
+        return self._state

server/__init__.py

@@ -0,0 +1,11 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""Lingua Env environment server components."""
+
+from .lingua_env_environment import LinguaEnvironment
+
+__all__ = ["LinguaEnvironment"]

server/app.py

@@ -0,0 +1,60 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""
+FastAPI application for the Lingua Env Environment.
+
+This module creates an HTTP server that exposes the LinguaEnvironment
+over HTTP and WebSocket endpoints, compatible with EnvClient.
+
+Endpoints:
+    - POST /reset: Reset the environment
+    - POST /step: Execute an action
+    - GET /state: Get current environment state
+    - GET /schema: Get action/observation schemas
+    - WS /ws: WebSocket endpoint for persistent sessions
+
+Usage:
+    # Development (with auto-reload):
+    uvicorn server.app:app --reload --host 0.0.0.0 --port 8000
+
+    # Production:
+    uvicorn server.app:app --host 0.0.0.0 --port 8000 --workers 4
+
+    # Or run directly:
+    python -m server.app
+"""
+
+try:
+    from openenv.core.env_server.http_server import create_app
+except Exception as e:  # pragma: no cover
+    raise ImportError(
+        "openenv is required for the web interface. Install dependencies with:\n    uv sync\n"
+    ) from e
+
+from ..models import LinguaAction, LinguaObservation
+from .lingua_env_environment import LinguaEnvironment
+
+app = create_app(
+    LinguaEnvironment,
+    LinguaAction,
+    LinguaObservation,
+    env_name="lingua",
+    max_concurrent_envs=1,
+)
+
+
+def main() -> None:
+    import os
+    import uvicorn
+
+    host = os.getenv("HOST", "0.0.0.0")
+    port = int(os.getenv("PORT", "8000"))
+    uvicorn.run(app, host=host, port=port)
+
+
+if __name__ == "__main__":
+    main()

server/lingua_env_environment.py

@@ -0,0 +1,177 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""
+Lingua Env Environment Implementation.
+
+A simple test environment that echoes back messages sent to it.
+Perfect for testing HTTP server infrastructure.
+"""
+
+import json
+import random
+import uuid
+from pathlib import Path
+
+from openenv.core.env_server import Environment
+
+from ..models import LinguaAction, LinguaObservation, LinguaState
+
+
+PYMORPHY_FEATURE_MAP = {
+    "nomn": ("Case", "Nom"),
+    "gent": ("Case", "Gen"),
+    "datv": ("Case", "Dat"),
+    "accs": ("Case", "Acc"),
+    "ablt": ("Case", "Ins"),
+    "loct": ("Case", "Loc"),
+    "loc2": ("Case", "Loc"),
+    "sing": ("Number", "Sing"),
+    "plur": ("Number", "Plur"),
+    "masc": ("Gender", "Masc"),
+    "femn": ("Gender", "Fem"),
+    "neut": ("Gender", "Neut"),
+    "anim": ("Animacy", "Anim"),
+    "inan": ("Animacy", "Inan"),
+    "past": ("Tense", "Past"),
+    "pres": ("Tense", "Pres"),
+    "futr": ("Tense", "Fut"),
+    "1per": ("Person", "1"),
+    "2per": ("Person", "2"),
+    "3per": ("Person", "3"),
+    "COMP": ("Degree", "Cmp"),
+    "Supr": ("Degree", "Sup"),
+}
+
+POS_MAP = {
+    "NOUN": ["NOUN"],
+    "ADJ": ["ADJF", "ADJS"],
+    "VERB": ["VERB", "INFN", "GRND"],
+    "AUX": ["VERB", "INFN"],
+    "ADV": ["ADVB", "COMP", "PRED"],
+    "PRON": ["NPRO"],
+    "DET": ["ADJF", "NPRO"],
+    "NUM": ["NUMR"],
+    "ADP": ["PREP"],
+    "CCONJ": ["CONJ"],
+    "SCONJ": ["CONJ"],
+    "PART": ["PRCL"],
+    "INTJ": ["INTJ"],
+}
+
+
+def pymorphy_tag_to_ud_feats(tag_str: str) -> dict[str, str]:
+    feats = {}
+    for tok in tag_str.replace(",", " ").split():
+        if tok in PYMORPHY_FEATURE_MAP:
+            k, v = PYMORPHY_FEATURE_MAP[tok]
+            feats[k] = v
+    return feats
+
+
+def parse_pymorphy_pos(tag_str: str) -> str:
+    return tag_str.split()[0].split(",")[0]
+
+
+def score_candidate(candidate: dict, gold: dict) -> dict:
+    cand_lemma = candidate["lemma"]
+    cand_tag = candidate["tag"]
+
+    lemma_match = cand_lemma == gold["lemma"]
+
+    pymorphy_pos = parse_pymorphy_pos(cand_tag)
+    allowed_pos = POS_MAP.get(gold["upos"], [gold["upos"]])
+    pos_match = pymorphy_pos in allowed_pos
+
+    cand_feats = pymorphy_tag_to_ud_feats(cand_tag)
+    gold_feats = gold.get("feats", {})
+
+    reward = 0
+    if lemma_match:
+        reward += 1
+    if pos_match:
+        reward += 1
+
+    feature_matches = {}
+    for feat_name, gold_value in gold_feats.items():
+        cand_value = cand_feats.get(feat_name)
+        match = cand_value == gold_value
+        feature_matches[feat_name] = {
+            "candidate": cand_value,
+            "gold": gold_value,
+            "match": match,
+        }
+        if match:
+            reward += 1
+
+    return {
+        "reward": reward,
+        "lemma_match": lemma_match,
+        "pos_match": pos_match,
+        "candidate_feats": cand_feats,
+        "gold_feats": gold_feats,
+        "feature_matches": feature_matches,
+    }
+
+
+class LinguaEnvironment(Environment):
+    def __init__(self):
+        super().__init__()
+        data_path = Path(__file__).resolve().parents[1] / "data" / "ambiguous_examples.jsonl"
+        with open(data_path, "r", encoding="utf-8") as f:
+            self.examples = [json.loads(line) for line in f]
+
+        self.current = None
+        self._state = LinguaState(gold={})
+
+    def reset(self) -> LinguaObservation:
+        self.current = random.choice(self.examples)
+        self._state = LinguaState(
+            episode_id=str(uuid.uuid4()),
+            step_count=0,
+            gold=self.current["gold"],
+        )
+
+        return LinguaObservation(
+            sentence=list(self.current["sentence"]),
+            target_index=int(self.current["target_index"]),
+            word=str(self.current["word"]),
+            candidate_parses=list(self.current["candidate_parses"]),
+        )
+
+    def step(self, action: LinguaAction) -> LinguaObservation:
+        if self.current is None:
+            raise RuntimeError("Environment must be reset before step().")
+
+        choice = int(action.choice)
+        if choice < 0 or choice >= len(self.current["candidate_parses"]):
+            raise ValueError(f"Invalid choice index: {choice}")
+
+        self._state.step_count += 1
+
+        chosen = self.current["candidate_parses"][choice]
+        details = score_candidate(chosen, self.current["gold"])
+
+        self._state.gold = self.current["gold"]
+
+        obs = LinguaObservation(
+            sentence=list(self.current["sentence"]),
+            target_index=int(self.current["target_index"]),
+            word=str(self.current["word"]),
+            candidate_parses=list(self.current["candidate_parses"]),
+        )
+        obs.reward = float(details["reward"])
+        obs.done = True
+        obs.metadata = {
+            "chosen": chosen,
+            "gold": self.current["gold"],
+            "reward_breakdown": details,
+        }
+        return obs
+
+    @property
+    def state(self) -> LinguaState:
+        return self._state

server/requirements.txt

@@ -0,0 +1,6 @@
+openenv[core]>=0.2.0
+fastapi>=0.115.0
+uvicorn>=0.24.0
+
+
+