Metadata-Version: 2.5
Name: opengrade-ai-server
Version: 0.1.1
Summary: OpenGrade server (FastAPI API + packaged UI)
Project-URL: Homepage, https://github.com/19Alma98/ai-eval-platform
Project-URL: Repository, https://github.com/19Alma98/ai-eval-platform
Project-URL: Issues, https://github.com/19Alma98/ai-eval-platform/issues
Project-URL: Documentation, https://github.com/19Alma98/ai-eval-platform#readme
Author-email: Alessandro Magliola <alessandromagliola1998@gmail.com>
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.12
Requires-Dist: aiosqlite>=0.20.0
Requires-Dist: alembic>=1.14.0
Requires-Dist: asyncpg>=0.30.0
Requires-Dist: fastapi>=0.115.0
Requires-Dist: httpx2>=2.13.0
Requires-Dist: jsonschema>=4.23.0
Requires-Dist: litellm>=1.55.0
Requires-Dist: opengrade-ai==0.1.1
Requires-Dist: opentelemetry-proto>=1.28.0
Requires-Dist: protobuf>=5.0.0
Requires-Dist: pydantic-settings>=2.6.0
Requires-Dist: pydantic>=2.10.0
Requires-Dist: python-multipart>=0.0.9
Requires-Dist: pyyaml>=6.0.2
Requires-Dist: rich>=13.9.0
Requires-Dist: sqlalchemy[asyncio]>=2.0.36
Requires-Dist: typer>=0.15.0
Requires-Dist: uvicorn[standard]>=0.32.0
Description-Content-Type: text/markdown

# opengrade-ai-server

OpenGrade server package (API + packaged UI).

- Distribution: `opengrade-ai-server` (PyPI)
- Import path: `opengrade_server` (e.g. `uvicorn opengrade_server.main:app`)
- Console scripts: `opengrade` (`ui`, `check`; provided by the `opengrade-ai` dependency) and `opengrade-server` (same commands)

## Local UI

Requires Node.js >= 22 to build the UI from a clone. Contributors should use `uv sync --all-extras` (plain `uv sync` strips extras from an existing venv).

```bash
# from repo root — build the Next static export into the package
python scripts/package_ui.py   # or ./scripts/package-ui.sh
cd backend && uv sync --all-extras
uv run opengrade ui
# → http://127.0.0.1:8000  (SQLite ./opengrade.db by default)
```

Local SQLite schema is applied with Alembic on startup (same revisions as Postgres). File-backed SQLite uses WAL and a 5s `busy_timeout`. If a pre-Alembic DB is stale (schema behind models), delete `./opengrade.db` (and any `-wal`/`-shm` sidecars) and restart.

**Backup:** stop the process (or run `PRAGMA wal_checkpoint(FULL)`), then copy `opengrade.db` plus any `opengrade.db-wal` / `opengrade.db-shm` files. Do not copy only the main file while the process is writing under WAL.

`opengrade ui` loads `.env` from the current working directory when present, prints LLM / content-capture settings, and exits if the bind port already has a listener (use `--port` or stop the other process).

Postgres:

```bash
uv run opengrade ui --backend-store-uri 'postgresql+asyncpg://opengrade:opengrade@localhost:5434/opengrade'
```

## Ops (container)

- **Single API replica** — scoring runs in-process; multi-replica recovery is not safe yet.
- Probes: `GET /health` (liveness), `GET /ready` (DB readiness). Compose healthchecks `/ready`.
- Requests carry `X-Request-ID` (echoed / generated).
- Entrypoint: `--proxy-headers`, `--forwarded-allow-ips` (`FORWARDED_ALLOW_IPS`), `--timeout-graceful-shutdown` (`SHUTDOWN_GRACE_SECONDS`).
- OTLP `/v1/traces` may return **429** / **503** with `Retry-After` when rate, inflight, or pending-score caps are hit (`OTLP_*` in `.env.example`).

See the repository root README for Docker Compose and SDK quickstart. Compose loads `backend/.env` when present (`env_file` is optional); copy from `.env.example` for LLM judges and other overrides.
