Skip to content

Latest commit

 

History

History
133 lines (105 loc) · 4.28 KB

DEVELOPMENT.md

File metadata and controls

133 lines (105 loc) · 4.28 KB

Contributing to pgai

Welcome to the pgai project! This guide will help you get started with contributing to pgai, a project that brings embedding and generation AI models closer to your PostgreSQL database.

Project overview

pgai is organized as a monorepo containing two main components:

  1. PostgreSQL extension: Located in projects/extension

    • Implements the core functionality for AI operations within your database
    • Written in Python and PL/PgSQL
    • Development guidelines are available in the extension directory

  2. Python Library: Located in projects/pgai

    • Available on PyPI
    • Provides a high-level interface for interacting with the vectorizer worker, and additionally integrations such as the SQLAlchemy one.
    • Written in Python
    • Development guidelines are available in the pgai directory

Development prerequisites

Before you begin, ensure you have the following installed:

  1. Just - Our task runner for project commands

    • Available in most package managers
    • See installation instructions in the Just documentation

  2. UV - Fast Python package installer and resolver

    • Required for Python dependency management
    • Faster and more reliable than pip
    • See installation instructions in the UV documentation

Contribution guidelines

Commit standards

We follow the Conventional Commits specification for all commits. This standardization helps us:

  • Automate release processes
  • Generate changelogs
  • Maintain clear commit history
  • Enforce consistent messaging

Examples of valid commit messages:

feat: add vector similarity search
fix: resolve null pointer in embedding generation
docs: update installation instructions
test: add integration tests for OpenAI embedder

Setting up commit hooks

To ensure your commits meet our standards before pushing:

  1. Install the local commit hook:

    just install-commit-hook

  2. The hook will automatically check your commit messages

    • Prevents non-compliant commits locally
    • Saves time waiting for CI feedback
    • Provides immediate validation

Pull Request process

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Ensure commits follow conventional commit format
  5. Submit PR with clear description of changes
  6. Wait for CI validation and review

The CI pipeline will check:

  • Commit message format
  • Code style
  • Tests
  • Build process

Getting help

  • Check existing documentation in docs directory
  • Open an issue for bugs, feature requests, or any other questions
  • Join our community discussions in our Discord server
  • Review closed PRs for examples

Remember to always pull the latest changes before starting new work.

Testing features

If there is a feature in main that isn't released yet you can create a docker-compose.yml that looks like this:

name: pgai
services:
  db:
    build:
      context: projects/extension
      dockerfile: Dockerfile
      target: pgai-test-db
    environment:
      POSTGRES_PASSWORD: postgres
    ports:
      - "5432:5432"
    volumes:
      - data:/home/postgres/pgdata/data
    command: [ "-c", "ai.ollama_host=http://ollama:11434" ]
  vectorizer-worker:
    build:
      context: projects/pgai
      dockerfile: Dockerfile
    environment:
      PGAI_VECTORIZER_WORKER_DB_URL: postgres://postgres:postgres@db:5432/postgres
      OLLAMA_HOST: http://ollama:11434
    command: [ "--poll-interval", "5s", "--log-level", "DEBUG" ]
  ollama:
    image: ollama/ollama
volumes:
  data:

This will build the vectorizer-worker and a database image with pgai installed from your repository state. You can then play around with the latest and greatest changes.