officeconvert/README.md

officeconvert

officeconvert is a multimodule conversion toolkit for turning presentation files into typed SlideDeck artifacts with rendered slide images and notes. The repository is organized around Protocol Buffer schemas with ConnectRPC code generation for both server and client compatibility.

Modules

• proto/ contains protobuf schemas and RPC definitions.
• gen/python and gen/go contain generated protocol and Connect code.
• python/packages/officeconvert is the core conversion library (PPTX -> PDF -> images + notes).
• python/packages/server is the ConnectRPC Python server with MinIO orchestration.
• clients/go is the first client library with layered orchestration helpers.
• deploy/ contains production-ish and dev Docker Compose files.

Supported Document Types

MVP currently supports PPTX only and produces a SlideDeck result containing:

• ordered slide image URLs
• plain-text notes per slide

Quick Commands

Use the root Makefile:

• make buf-lint to lint protobufs
• make buf-generate to regenerate Go and Python types
• make py-sync to sync Python workspace dependencies with uv
• make go-test to run Go client tests
• make compose-up to run server + MinIO
• make compose-up-dev to run MinIO only
• make run-server to start host uvicorn with .env (if present) plus defaults

Development Server Workflow

This is the recommended local workflow for iterating on the Python server and conversion library while keeping MinIO in Docker.

1) Prerequisites

• buf on your PATH
• uv on your PATH
• Docker + Docker Compose
• Local tools if running server on host (not in container):
  • LibreOffice (soffice)
  • Poppler (pdftoppm)

2) Generate typed API code

From repo root:

make buf-lint
make buf-generate

3) Sync Python workspace dependencies

From repo root:

make py-sync

4) Start MinIO dependency stack (dev compose)

From repo root:

make compose-up-dev

MinIO endpoints:

• API: http://localhost:9000
• Console: http://localhost:9001
• Default creds: minioadmin / minioadmin

5) Start Connect server (host process)

In a separate terminal, from repo root:

make run-server

make run-server behavior:

• loads .env automatically if present
• applies reasonable defaults when values are not set
• defaults MinIO endpoint to localhost:9000 for host-based development
• supports optional UVICORN_HOST and UVICORN_PORT overrides

If you copy from .env.example, set MINIO_ENDPOINT=localhost:9000 for host mode.

Server endpoint base URL:

• http://localhost:8080

6) Quick smoke test

Create a conversion request:

curl \
  --header "Content-Type: application/json" \
  --data '{"sourceFilename":"example.pptx"}' \
  http://localhost:8080/officeconvertapi.v1.ConversionService/CreateConversion

Then:

1. Upload the PPTX to the returned uploadUrl using HTTP PUT.
2. Call StartConversion with the returned conversionId.
3. Poll GetConversionStatus until CONVERSION_STATUS_SUCCEEDED.
4. Call GetSlideDeck and download each imageUrl.
5. Optionally call DeleteConversion for early cleanup.

7) Full container workflow (optional)

If you want to run both server and MinIO in Docker:

make compose-up

Use .env.example as your baseline env configuration.