feat(scaffold): project skeleton with uv + pytest + forgejo CI

- pyproject.toml: runtime deps (FastAPI, SQLAlchemy async, Pydantic, PyMuPDF,
  python-magic, Pillow, dateutil), dev group (pytest, pytest-asyncio,
  pytest-httpx, ruff, mypy), optional `ocr` extra that pulls surya-ocr + torch
  (kept optional so CI without GPU can run the base package).
- pytest config: asyncio_mode=auto; `live` marker for tests that need a real
  Ollama/Surya (gated on IX_TEST_OLLAMA=1).
- Single smoke test (tests/unit/test_scaffolding.py) verifies the package
  imports and exposes __version__ — keeps CI green until the real test
  modules land in later chunks.
- .forgejo/workflows/ci.yml: runs ruff + pytest against a Postgres 16 service
  container. Explicit IX_TEST_MODE=fake keeps real-client tests out.
- .env.example: every IX_* var from spec §9 with on-prem-friendly defaults.
- uv.lock committed for reproducible builds.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

.env.example

@@ -0,0 +1,41 @@
+# InfoXtractor runtime configuration.
+# Every variable is optional; defaults are suitable for running against the
+# on-prem stack (Ollama on :11434, postgis on :5431). Copy to .env and fill in
+# the Postgres password.
+
+# --- Job store -----------------------------------------------------------
+IX_POSTGRES_URL=postgresql+asyncpg://infoxtractor:<password>@host.docker.internal:5431/infoxtractor
+
+# --- LLM backend ---------------------------------------------------------
+IX_OLLAMA_URL=http://host.docker.internal:11434
+IX_DEFAULT_MODEL=gpt-oss:20b
+
+# --- OCR -----------------------------------------------------------------
+IX_OCR_ENGINE=surya
+
+# --- Pipeline behavior ---------------------------------------------------
+IX_PIPELINE_WORKER_CONCURRENCY=1
+IX_PIPELINE_REQUEST_TIMEOUT_SECONDS=2700
+IX_GENAI_CALL_TIMEOUT_SECONDS=1500
+IX_RENDER_MAX_PIXELS_PER_PAGE=75000000
+
+# --- File fetching -------------------------------------------------------
+IX_TMP_DIR=/tmp/ix
+IX_FILE_MAX_BYTES=52428800
+IX_FILE_CONNECT_TIMEOUT_SECONDS=10
+IX_FILE_READ_TIMEOUT_SECONDS=30
+
+# --- Transport / callbacks ----------------------------------------------
+IX_CALLBACK_TIMEOUT_SECONDS=10
+
+# --- Observability -------------------------------------------------------
+IX_LOG_LEVEL=INFO
+
+# --- Test-only -----------------------------------------------------------
+# Set IX_TEST_MODE=fake to have the pipeline factory build FakeOCRClient /
+# FakeGenAIClient instead of real ones (used by integration tests).
+# IX_TEST_MODE=fake
+
+# Set IX_TEST_OLLAMA=1 on the Mac to enable tests that require a real
+# Ollama / Surya instance (tests/live/).
+# IX_TEST_OLLAMA=1

.forgejo/workflows/ci.yml

@@ -0,0 +1,48 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: docker
+    container:
+      image: python:3.12-slim
+    services:
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_USER: test
+          POSTGRES_PASSWORD: test
+          POSTGRES_DB: ix_test
+        options: >-
+          --health-cmd="pg_isready -U test"
+          --health-interval=5s
+          --health-timeout=3s
+          --health-retries=10
+
+    env:
+      IX_POSTGRES_URL: postgresql+asyncpg://test:test@postgres:5432/ix_test
+      IX_TEST_MODE: fake
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install system deps for python-magic / PyMuPDF
+        run: |
+          apt-get update && apt-get install -y --no-install-recommends \
+            libmagic1 libgl1 libglib2.0-0
+
+      - name: Install uv
+        run: pip install --no-cache-dir uv
+
+      - name: Install project
+        run: uv sync --extra dev
+
+      - name: Lint
+        run: uv run ruff check src tests
+
+      - name: Unit + integration tests (no GPU, no live Ollama)
+        run: uv run pytest tests/unit tests/integration -v

.gitignore

@@ -15,3 +15,6 @@ dist/
 build/
 *.log
 /tmp/
+# uv
+# uv.lock is committed intentionally for reproducible builds.
+

.python-version

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

pyproject.toml

@@ -0,0 +1,73 @@
+[project]
+name = "infoxtractor"
+version = "0.1.0"
+description = "Async on-prem LLM-powered structured information extraction microservice"
+readme = "README.md"
+requires-python = ">=3.12"
+license = { text = "MIT" }
+authors = [{ name = "goldstein" }]
+
+dependencies = [
+    # Web / async
+    "fastapi>=0.115",
+    "uvicorn[standard]>=0.32",
+    "httpx>=0.27",
+
+    # Data
+    "pydantic>=2.9",
+    "pydantic-settings>=2.6",
+
+    # Database
+    "sqlalchemy[asyncio]>=2.0.36",
+    "asyncpg>=0.30",
+    "alembic>=1.14",
+
+    # Document processing
+    "pymupdf>=1.25",
+    "pillow>=10.2,<11.0",
+    "python-magic>=0.4.27",
+    "python-dateutil>=2.9",
+]
+
+[project.optional-dependencies]
+ocr = [
+    # Real OCR engine — pulls torch + CUDA wheels. Kept optional so CI
+    # (no GPU) can install the base package without the model deps.
+    "surya-ocr>=0.9",
+    "torch>=2.4",
+]
+dev = [
+    "pytest>=8.3",
+    "pytest-asyncio>=0.24",
+    "pytest-httpx>=0.32",
+    "ruff>=0.8",
+    "mypy>=1.13",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ix"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+addopts = "-ra --strict-markers"
+markers = [
+    "live: requires live Ollama/Surya (IX_TEST_OLLAMA=1 to enable)",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B", "SIM", "RUF"]
+ignore = ["E501"]  # line length handled by formatter
+
+[tool.mypy]
+python_version = "3.12"
+strict = true
+plugins = ["pydantic.mypy"]

src/ix/__init__.py

@@ -0,0 +1,3 @@
+"""InfoXtractor — async on-prem structured information extraction service."""
+
+__version__ = "0.1.0"

tests/conftest.py

@@ -0,0 +1,15 @@
+"""Shared pytest fixtures.
+
+Unit-test fixtures live here. Integration-test fixtures (real Postgres, etc.)
+will be added in Chunk 3 once the store module lands.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+
+@pytest.fixture
+def anyio_backend() -> str:
+    """Force asyncio for anyio-based tests (pytest-asyncio uses this)."""
+    return "asyncio"

tests/unit/test_scaffolding.py

@@ -0,0 +1,13 @@
+"""Smoke test: confirms the package is importable and pyproject is well-formed.
+
+Acts as the minimum-viable test that the project is set up correctly. Gets
+replaced with real tests as the chunks land.
+"""
+
+from __future__ import annotations
+
+
+def test_package_importable() -> None:
+    import ix
+
+    assert ix.__version__ == "0.1.0"