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

Code Quality Tools

Linting with Ruff

# Check for issues
ruff check ontokit/

# Auto-fix issues
ruff check --fix .

# Format code
ruff format ontokit/

Type Checking with mypy

mypy ontokit/

Running All Checks

# Run linting, formatting check, and type checking
ruff check ontokit/
ruff format --check ontokit/
mypy ontokit/

Running Tests

All Tests

pytest

With Coverage

pytest --cov=ontokit --cov-report=term-missing

Specific Test File

pytest tests/test_projects.py

Specific Test Function

pytest tests/test_projects.py::test_create_project

Verbose Output

pytest -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
├── alembic.ini
├── compose.yaml               # Docker Compose (full stack)
├── compose.prod.yaml          # Docker Compose (infrastructure only)
└── 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: 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
pip install -U -e ".[dev]"

# Update specific package
pip install -U fastapi

Next Steps

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