Skip to content

developer-guide.mdx

Latest commit

 

History

History
160 lines (105 loc) · 5.2 KB

developer-guide.mdx

File metadata and controls

160 lines (105 loc) · 5.2 KB
Raw
title Developer Guide

This guide is for developers who want to build, extend, or contribute to Flock itself.

Flock CI builds against DuckDB **v1.5.4**. User-facing docs require DuckDB **1.5.0+**.

Local Development Setup

  • Clone the repository:
git clone --recursive https://github.com/dais-polymtl/flock.git
cd flock
  • Initialize submodules (if you forgot --recursive):
git submodule update --init --recursive
  • Build and run via helper script:
./scripts/build_and_run.sh

The interactive script will:

  • Check for required tools (CMake, compiler, Ninja/Make, etc.).
  • Configure dependencies via vcpkg.
  • Build Flock (Debug/Release).
  • Launch DuckDB with the Flock extension preloaded.

See the root README.md for a concise overview of these steps.

For a CLion-specific walkthrough (open the DuckDB CMake project, vcpkg, and run configs), see docs/development/clion.md in the repository. That guide is not part of this docs site.

Building the Extension Manually

While ./scripts/build_and_run.sh is the recommended path, you can also build manually:

mkdir -p build
cd build
cmake .. -G Ninja
ninja

The resulting Flock extension library can then be loaded from DuckDB using LOAD with the appropriate path.

WASM builds

Flock CI produces DuckDB-WASM extension artifacts via extension-ci-tools (see .github/workflows/MainDistributionPipeline.yml). To build locally:

  1. Clone with submodules and follow the steps above.
  2. Use the extension distribution toolchain with WASM_EXTENSIONS=1 and an Emscripten target, following the patterns in extension-ci-tools/.github/workflows/_extension_distribution.yml.

Published WASM binaries ship through DuckDB's extension repository when released to the community catalog. For install commands and browser limitations, see Installation.

Running Tests

Flock comes with both unit and integration tests:

  • C++ unit tests live under test/unit/.
  • Integration tests (Python + DuckDB) live under test/integration/.

Example pattern (from the repo root):

python -m pytest test/integration

Check the repository’s CI configuration for the exact commands used in automation.

Coding Conventions

When contributing code:

  • Follow the surrounding C++ style (namespaces, includes, brace style).
  • Avoid introducing new dependencies without a clear reason.
  • Prefer small, focused pull requests with clear descriptions.

If in doubt, mirror patterns used in existing functions such as llm_complete or the metrics manager.

Working on Providers & Models

  • Provider-specific adapters live under src/model_manager/providers/adapters/.
  • HTTP and batching logic is centralized in provider handlers under src/include/flock/model_manager/providers/handlers/.
  • New providers should:
    • Integrate with the existing metrics API.
    • Respect the context_columns abstraction.
    • Provide clear, actionable error messages when a feature is unsupported.

For examples, see the existing OpenAI, Azure, Ollama, and Anthropic adapters.

Docs & Developer Experience

The Mintlify docs live in docs/. Install the CLI once:

npm i -g mint

There are two local preview workflows. Use both at different times — they are not interchangeable.

mint dev — fast editing

Best for writing and layout while you iterate on MDX, nav, and components.

cd docs
mint dev

Open http://localhost:3000.

  • Hot reload on save
  • Mintlify dev server (root URL, no /flock prefix)
  • Mintlify cloud search when the CLI is authenticated (optional)
  • Does not run the GitHub Pages export, path rewrites, or Pagefind index

build-and-serve.sh — production parity

Best before merging doc changes, when testing search, or when verifying links and assets under the GitHub Pages base path.

From the repo root:

./docs/scripts/build-and-serve.sh

Open http://localhost:3000/flock/ (the /flock/ prefix matters).

This script:

  1. mint export → static HTML
  2. prepare-github-pages.mjs → rewrites paths for /flock and injects the Pagefind search bridge
  3. pagefind → builds the client-side search index
  4. Serves the result with the same layout as GitHub Pages

Optional environment variables: PORT (default 3000), GITHUB_PAGES_BASE_PATH (default /flock), SITE_DIR, SITE_ZIP, DOCS_TMPDIR. If mint export fails with ENOSPC, set DOCS_TMPDIR=/tmp.

Cmd+K search on the static export uses Pagefind, not Mintlify cloud search. If search shows “Search is unavailable offline”, you are likely on `mint dev` or skipped the Pagefind step — use `build-and-serve.sh` instead.

When adding new Flock features, update

  • The home page (index.mdx) for high-level positioning
  • The relevant function or feature page (e.g. llm-complete.mdx modalities, llm-metrics.mdx)
  • static/llms.txt so entry points stay current
  • docs.json navigation if you add or regroup pages
  • This Developer Guide for build, testing, or contribution-related changes