OpenAI wrapper service review

.github/workflows/service-openai-wrapper-service.yml

@@ -0,0 +1,107 @@
+name: openai-wrapper-service
+
+on:
+  push:
+    branches: ["master"]
+    paths:
+      - "services/openai-wrapper-service/**"
+      - ".github/workflows/service-openai-wrapper-service.yml"
+  pull_request:
+    branches: ["master"]
+    paths:
+      - "services/openai-wrapper-service/**"
+      - ".github/workflows/service-openai-wrapper-service.yml"
+
+defaults:
+  run:
+    working-directory: services/openai-wrapper-service
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - uses: astral-sh/setup-uv@v5
+      - name: Install dependencies
+        run: uv sync
+      - name: Lint
+        run: make lint
+
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+    needs: lint
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - uses: astral-sh/setup-uv@v5
+      - name: Install dependencies
+        run: uv sync
+      - name: Run tests
+        run: make test
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v4
+        with:
+          files: services/openai-wrapper-service/coverage.xml
+          flags: openai-wrapper-service
+          token: ${{ secrets.CODECOV_TOKEN }}
+          fail_ci_if_error: false
+        if: always()
+
+  generate-openapi:
+    name: Generate OpenAPI Spec
+    runs-on: ubuntu-latest
+    needs: test
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - uses: astral-sh/setup-uv@v5
+      - name: Install dependencies
+        run: uv sync
+      - name: Generate OpenAPI spec
+        run: make generate-openapi
+      - name: Upload OpenAPI spec
+        uses: actions/upload-artifact@v4
+        with:
+          name: openapi-spec-openai-wrapper-service
+          path: services/openai-wrapper-service/openai-wrapper-service.openapi.json
+
+  build:
+    name: Build & Push Docker Image
+    runs-on: ubuntu-latest
+    needs: generate-openapi
+    if: github.event_name == 'push' && github.ref == 'refs/heads/master'
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - uses: actions/checkout@v4
+      - name: Log in to GitHub Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - name: Extract Docker metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ghcr.io/${{ github.repository_owner }}/openai-wrapper-service
+          tags: |
+            type=sha,prefix=sha-
+            type=raw,value=latest
+      - name: Build and push Docker image
+        uses: docker/build-push-action@v6
+        with:
+          context: services/openai-wrapper-service
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}

services/openai-wrapper-service/.dockerignore

@@ -0,0 +1,10 @@
+.venv
+.uv-cache
+__pycache__
+.pytest_cache
+.ruff_cache
+.coverage
+coverage.xml
+htmlcov
+.git
+.DS_Store

services/openai-wrapper-service/.gitignore

@@ -0,0 +1,9 @@
+.venv/
+.uv-cache/
+__pycache__/
+.pytest_cache/
+.ruff_cache/
+.coverage
+coverage.xml
+htmlcov/
+openai-wrapper-service.openapi.json

services/openai-wrapper-service/.python-version

@@ -0,0 +1 @@
+3.12

services/openai-wrapper-service/Dockerfile

@@ -0,0 +1,18 @@
+FROM python:3.12-slim-trixie
+
+RUN apt-get update && apt-get install -y --no-install-recommends curl ca-certificates \
+    && rm -rf /var/lib/apt/lists/*
+
+ADD https://astral.sh/uv/install.sh /uv-installer.sh
+RUN sh /uv-installer.sh && rm /uv-installer.sh
+
+ENV PATH="/root/.local/bin/:$PATH"
+ENV PORT=8002
+
+COPY . /app
+WORKDIR /app
+RUN uv sync --locked --no-dev
+
+EXPOSE 8002
+
+CMD ["sh", "-c", "uv run --no-sync uvicorn openai_wrapper_service.api:app --host 0.0.0.0 --port ${PORT} --app-dir src"]

services/openai-wrapper-service/Makefile

@@ -0,0 +1,31 @@
+IMAGE_NAME  := openai-wrapper-service
+OPENAPI_OUT := openai-wrapper-service.openapi.json
+PORT        ?= 8002
+
+.PHONY: prep build test lint start clean docker-build generate-openapi
+
+prep:
+	uv sync
+
+build:
+	@echo "No build step required for Python"
+
+test:
+	uv run pytest --cov=src --cov-report=xml --cov-report=term-missing
+
+lint:
+	uv run ruff check src/ scripts/ test/
+	uv run ruff format --check src/ scripts/ test/
+
+start:
+	uv run uvicorn openai_wrapper_service.api:app --reload --port $(PORT) --app-dir src
+
+clean:
+	rm -rf .coverage coverage.xml htmlcov/ .pytest_cache $(OPENAPI_OUT)
+	find . -type d -name __pycache__ -exec rm -rf {} +
+
+docker-build:
+	docker build -t $(IMAGE_NAME) .
+
+generate-openapi:
+	uv run python scripts/generate_openapi.py

services/openai-wrapper-service/README.md

@@ -0,0 +1,121 @@
+# OpenAI Wrapper Service
+
+HTTP and CLI wrapper around the official OpenAI Responses API.
+
+The service uses the OpenAI Python SDK through the adapter in `src/openai_wrapper_service/client.py`.
+
+- Text generation through the OpenAI Responses API
+- A CLI that mirrors the REST behavior
+- A generated OpenAPI specification
+
+## Code Layout
+
+```text
+src/openai_wrapper_service/api.py      # FastAPI app and routes
+src/openai_wrapper_service/client.py   # OpenAI SDK adapter
+src/openai_wrapper_service/cli.py      # Command line interface
+src/openai_wrapper_service/schemas.py  # Request and response models
+scripts/generate_openapi.py            # OpenAPI export utility
+```
+
+The service directory uses the repository's kebab-case convention (`openai-wrapper-service`). The Python package uses snake_case (`openai_wrapper_service`) because Python imports cannot contain hyphens.
+
+## Configuration
+
+Set an OpenAI API key before using the API or CLI:
+
+```sh
+export OPENAI_API_KEY=...
+```
+
+Optional environment variables:
+
+| Variable | Default | Description |
+| --- | --- | --- |
+| `OPENAI_BASE_URL` | OpenAI SDK default | OpenAI-compatible API base URL |
+| `OPENAI_ORG_ID` | unset | OpenAI organization id |
+| `OPENAI_PROJECT_ID` | unset | OpenAI project id |
+| `OPENAI_WRAPPER_MAX_RETRIES` | `2` | OpenAI SDK max retry count |
+| `OPENAI_WRAPPER_TIMEOUT_SECONDS` | `60` | OpenAI SDK request timeout |
+| `PORT` | `8002` | HTTP port used by `make start` and the Docker container |
+
+The model is provided per `/generate` request because available model ids depend on the configured OpenAI-compatible provider.
+
+## API
+
+Start the service:
+
+```sh
+make start
+```
+
+The API listens on port `8002` by default.
+
+OpenAPI docs:
+
+```text
+http://localhost:8002/docs
+```
+
+Endpoints:
+
+| Method | Path | Description |
+| --- | --- | --- |
+| `GET` | `/health` | Liveness probe |
+| `POST` | `/generate` | Generate text through the OpenAI Responses API |
+
+Example generation request:
+
+```json
+{
+  "model": "provider-model-id",
+  "input": "Summarize the purpose of ALADIN in one sentence.",
+  "instructions": "Answer concisely.",
+  "max_output_tokens": 120
+}
+```
+
+## CLI
+
+The CLI mirrors the API:
+
+```sh
+uv run openai-wrapper health
+uv run openai-wrapper generate "Write a short explanation of graph rewriting." --model provider-model-id
+uv run openai-wrapper generate "Write a short explanation of graph rewriting." --model provider-model-id --json
+```
+
+## Docker
+
+Build:
+
+```sh
+make docker-build
+```
+
+Run:
+
+```sh
+docker run --rm -p 8002:8002 -e OPENAI_API_KEY -e PORT=8002 openai-wrapper-service
+```
+
+## Hardware Requirements
+
+Minimal requirements for the wrapper itself:
+
+| Resource | Requirement |
+| --- | --- |
+| CPU | 1 vCPU |
+| Memory | 256 MB RAM |
+| Disk | < 200 MB image/runtime overhead, excluding Docker base layers |
+
+Generation latency, availability, and cost are governed by OpenAI API calls rather than local compute. Deployments should enforce request-size and rate limits appropriate for their API budget.
+
+## Development
+
+```sh
+make prep
+make lint
+make test
+make generate-openapi
+```