Development

Development

This guide covers the development workflow for the OntoKit API.

Running the Development Server

Basic Start

# Activate virtual environment
source .venv/bin/activate

# Start with auto-reload
uvicorn ontokit.main:app --reload

The server will automatically restart when you modify Python files.

With Custom Host/Port

uvicorn ontokit.main:app --reload --host 0.0.0.0 --port 8000

With Debug Logging

# Set DEBUG=true in .env, or:
DEBUG=true uvicorn ontokit.main:app --reload

First-Time Setup

OntoKit uses uv as its package manager and includes a Makefile for common tasks.

# Install dependencies and set up pre-commit hooks
make setup

This runs uv sync --extra dev and installs pre-commit hooks (ruff + mypy) that run automatically on each commit.

Code Quality Tools

Using the Makefile

The recommended way to run code quality tools:

make lint        # Run ruff with auto-fix on ontokit/ and tests/
make format      # Format code with ruff
make typecheck   # Run mypy in strict mode
make test        # Run pytest with coverage

Manual Commands

# Linting
uv run ruff check ontokit/ tests/ --fix

# Format code
uv run ruff format ontokit/ tests/

# Type checking
uv run mypy ontokit/

Pre-commit Hooks

Pre-commit hooks are configured in .pre-commit-config.yaml and run automatically on git commit:

• ruff — linting with auto-fix
• ruff-format — code formatting
• mypy — strict type checking (Python 3.11 target)

To manually run all hooks on all files:

uv run pre-commit run --all-files

Running Tests

All Tests

make test
# or manually:
uv run pytest tests/ -v --cov=ontokit

With Coverage Report

uv run pytest tests/ --cov=ontokit --cov-report=term-missing

Specific Test File

uv run pytest tests/unit/test_health.py -v

Tests Matching a Pattern

uv run pytest tests/ -k "test_name" -v

Project Structure

ontokit-api/
├── ontokit/                   # Application source code
│   ├── __init__.py
│   ├── main.py                # FastAPI application entry point
│   ├── runner.py              # CLI entry point
│   ├── version.py             # Version management
│   ├── worker.py              # ARQ background job queue
│   ├── api/routes/            # API routes
│   │   ├── auth.py            # Authentication endpoints
│   │   ├── projects.py        # Project management
│   │   ├── ontologies.py      # Ontology CRUD
│   │   ├── classes.py         # OWL class operations
│   │   └── ...
│   ├── core/                  # Core functionality
│   │   ├── config.py          # Settings (Pydantic)
│   │   ├── database.py        # Database connection
│   │   └── auth.py            # JWT validation
│   ├── models/                # SQLAlchemy models
│   ├── schemas/               # Pydantic schemas
│   ├── services/              # Business logic
│   ├── git/                   # Git repository management (pygit2)
│   └── collab/                # WebSocket collaboration
├── alembic/                   # Database migrations
├── tests/
├── scripts/
│   └── setup-zitadel.sh       # Zitadel setup script
├── .env                       # Environment variables (not in git)
├── .env.example
├── .pre-commit-config.yaml    # Pre-commit hooks (ruff, mypy)
├── alembic.ini
├── compose.yaml               # Docker Compose (full stack)
├── compose.prod.yaml          # Docker Compose (infrastructure only)
├── Makefile                   # Common dev tasks (setup, lint, test)
└── pyproject.toml             # Project configuration

Making Changes

Adding a New Endpoint

1. Create/update the schema in ontokit/schemas/
2. Create/update the service in ontokit/services/
3. Create/update the router in ontokit/api/routes/
4. Register the router in ontokit/api/routes/__init__.py

Adding a New Model

1. Create the model in ontokit/models/
2. Export it in ontokit/models/__init__.py
3. Create a migration (see Database)
4. Create corresponding schemas in ontokit/schemas/

Example: Adding a New Entity

# 1. ontokit/models/comment.py
from sqlalchemy.orm import Mapped, mapped_column
from ontokit.core.database import Base

class Comment(Base):
    __tablename__ = "comments"

    id: Mapped[int] = mapped_column(primary_key=True)
    content: Mapped[str]
    # ...

# 2. ontokit/models/__init__.py
from ontokit.models.comment import Comment
__all__ = [..., "Comment"]

# 3. Generate migration
# alembic revision --autogenerate -m "Add comments table"

# 4. ontokit/schemas/comment.py
from pydantic import BaseModel

class CommentCreate(BaseModel):
    content: str

class CommentResponse(CommentCreate):
    id: int

    class Config:
        from_attributes = True

API Documentation

The API documentation is automatically generated:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc
• OpenAPI JSON: http://localhost:8000/openapi.json

Debugging

Using Print Statements

import logging
logger = logging.getLogger(__name__)

logger.info("Debug message: %s", variable)
logger.debug("Detailed debug info")

Using debugpy (VS Code)

1. Install debugpy: uv pip install debugpy
2. Add to your VS Code launch.json:

{
    "name": "FastAPI",
    "type": "python",
    "request": "launch",
    "module": "uvicorn",
    "args": ["app.main:app", "--reload"],
    "jinja": true
}

Interactive Shell

# Start Python with app context
python
>>> from ontokit.core.database import async_session_maker
>>> from ontokit.models import Project
>>> import asyncio
>>> # ... interactive debugging

Common Development Tasks

Restart Infrastructure

docker compose restart

View Container Logs

# All services
docker compose logs -f

# Specific service
docker compose logs -f postgres

Reset Database

# Stop services and remove volumes
docker compose down -v

# Restart
docker compose up -d

# Re-run migrations
alembic upgrade head

Update Dependencies

# Update all dependencies
uv sync --extra dev

# Update specific package
uv add fastapi --upgrade

Next Steps

• Database - Learn about migrations
• API Reference - See available endpoints
• Project Structure - Understand the codebase organization