Metadata-Version: 2.4
Name: uv-venv-manager
Version: 0.1.1
Summary: UV-based virtual environment provisioning service (FastAPI + gRPC)
Author: KataDavidXD
License-Expression: MIT
Project-URL: Homepage, https://github.com/HKU-MAS-Infra-Layer/uv_venv_manager
Project-URL: Repository, https://github.com/HKU-MAS-Infra-Layer/uv_venv_manager
Project-URL: Issues, https://github.com/HKU-MAS-Infra-Layer/uv_venv_manager/issues
Keywords: uv,venv,virtual-environment,langgraph,grpc,environment-provisioning
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: grpcio>=1.60.0
Requires-Dist: grpcio-tools>=1.60.0
Requires-Dist: grpcio-health-checking>=1.60.0
Requires-Dist: grpcio-reflection>=1.60.0
Requires-Dist: pydantic>=2.5.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: fastapi>=0.109.0
Requires-Dist: uvicorn>=0.27.0
Requires-Dist: python-multipart>=0.0.6
Requires-Dist: sqlalchemy>=2.0.0
Provides-Extra: postgres
Requires-Dist: psycopg2-binary>=2.9.0; extra == "postgres"
Provides-Extra: client
Requires-Dist: httpx>=0.26.0; extra == "client"
Requires-Dist: requests>=2.31.0; extra == "client"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Provides-Extra: all
Requires-Dist: uv-venv-manager[client,postgres]; extra == "all"

# uv-venv-manager

Standalone environment provisioning service built on [uv](https://github.com/astral-sh/uv).
Exposes both a **REST API** (FastAPI) and a **gRPC** interface for creating,
managing, and cleaning up Python virtual environments.

---

## Architecture

uv-venv-manager is a **pure environment provisioning service**.
It does **not** depend on Ray or any execution engine.
The WTB SDK orchestrates both Ray (for distributed execution) and
uv-venv-manager (for environment provisioning) -- the two services never
talk to each other directly.

```
                          +-----------------------+
                          |       WTB SDK         |
                          |  (orchestrator)       |
                          +---+---------------+---+
                              |               |
                  gRPC :50051 |               | Ray API
                              v               v
                  +-----------------+   +------------+
                  | uv-venv-manager |   | Ray Cluster|
                  |  (this service) |   +------+-----+
                  +--------+--------+          |
                           |           py_executable
                           v                   |
                  +--------+--------+          |
                  |  Shared Storage  |<--------+
                  |  (NAS / local)   |
                  +-----------------+
```

**uv-venv-manager provisions `.venv` paths.  WTB tells Ray to use them.**

---

## Quick Start

### Option A: Docker (recommended)

```bash
# Build
cd uv_venv_manager
docker build -t uv-venv-manager .

# Run
docker run -d \
  -p 10900:10900 \
  -p 50051:50051 \
  -v ./data:/data \
  --name uv-venv-manager \
  uv-venv-manager
```

Or with docker compose:

```bash
docker compose up -d
```

### Option B: pip install

```bash
pip install uv-venv-manager
# or from source:
pip install -e ".[all]"

# Start the server
uv-venv-server
```

The server starts on port **10900** (REST) with a gRPC sidecar on port **50051**.

---

## Configuration

All settings are read from environment variables (or a `.env` file).

| Variable | Default | Description |
|---|---|---|
| `DATA_ROOT` | `./data` | Base directory for all persistent data |
| `ENVS_BASE_PATH` | `$DATA_ROOT/envs` | Where virtual environments are created |
| `UV_CACHE_DIR` | `$DATA_ROOT/uv_cache` | uv package cache (must be sibling of `ENVS_BASE_PATH` for hardlinks) |
| `DEFAULT_PYTHON` | `3.11` | Python version for new environments |
| `PORT` | `10900` | REST API listen port |
| `GRPC_PORT` | `50051` | gRPC listen port |
| `DATABASE_URL` | `sqlite:///data/env_audit.db` | Audit database (SQLite default, PostgreSQL supported) |
| `EXECUTION_TIMEOUT` | `30` | UV command timeout in seconds |
| `CLEANUP_IDLE_HOURS` | `72` | Auto-cleanup threshold for idle environments |

---

## WTB Integration

WTB connects to uv-venv-manager through its `GrpcEnvironmentProvider`.
No extra setup is needed on the uv-venv-manager side.

```bash
# Run the install checker with venv service validation
python install_checker.py --grpc-url localhost:50051
```

In code:

```python
from wtb.infrastructure.environment.providers import GrpcEnvironmentProvider

provider = GrpcEnvironmentProvider(grpc_address="localhost:50051")
env = provider.create_environment("variant-1", {
    "workflow_id": "ml_pipeline",
    "node_id": "rag_node",
    "packages": ["langchain", "chromadb"],
})
# env contains env_path, python_path for Ray to use via WTB
```

---

## REST API

Base URL: `http://localhost:10900`

| Method | Endpoint | Description |
|---|---|---|
| POST | `/envs` | Create a new environment |
| GET | `/envs/{workflow_id}/{node_id}` | Get environment info |
| DELETE | `/envs/{workflow_id}/{node_id}` | Delete an environment |
| POST | `/envs/{workflow_id}/{node_id}/deps` | Add packages |
| DELETE | `/envs/{workflow_id}/{node_id}/deps` | Remove packages |
| POST | `/envs/{workflow_id}/{node_id}/sync` | Sync from lock file |
| POST | `/envs/{workflow_id}/{node_id}/export` | Export environment |
| POST | `/cleanup` | Clean up stale environments |

Interactive docs available at `http://localhost:10900/docs` (Swagger UI).

---

## gRPC API

Port: `50051` (configurable via `GRPC_PORT`)

The gRPC service mirrors the REST API. Proto definition is at
`uv_venv_manager/protos/env_manager.proto`. Enable reflection for
debugging with `GRPC_REFLECTION=true`.

---

## Storage Layout

```
$DATA_ROOT/
  envs/                          # ENVS_BASE_PATH
    workflow123_node123/         # One UV project per environment
      .venv/                    # Virtual environment
        bin/python              # py_executable target
      pyproject.toml            # Dependency declaration
      uv.lock                   # Byte-level version lock
      metadata.json             # Environment metadata
  uv_cache/                      # UV_CACHE_DIR (shared cache)
    wheels/                     # Hardlinked into .venv/lib/
    archives/
  env_audit.db                   # SQLite audit log (default)
```

`UV_CACHE_DIR` and `ENVS_BASE_PATH` must share the same parent
filesystem for uv's hardlink deduplication to work.

---

## Development

```bash
cd uv_venv_manager
uv sync
uv run pytest
uv run ruff check .
```
