Skip to content

Contributing

hemlock-lab welcomes contributions for new pipeline integrations, test harness improvements, and documentation updates.

Development Setup

# Clone the repository
git clone https://github.com/professor-moody/hemlock-lab.git
cd hemlock-lab

# Install documentation dependencies (for writing docs)
pip install -r requirements-docs.txt

# Preview docs locally
mkdocs serve

Repository Structure

hemlock-lab/
├── docker/
│   ├── docker-compose.yml   # Container orchestration
│   ├── langchain-rag/       # Dockerfile + app.py
│   ├── llamaindex-rag/      # Dockerfile + app.py
│   ├── unstructured-rag/    # Dockerfile + app.py
│   ├── haystack-rag/        # Dockerfile + app.py
│   ├── colpali-rag/         # Dockerfile + app.py
│   └── harness/             # Dockerfile for test harness
├── docs/                    # MkDocs documentation (this site)
├── harness/                 # Test harness scripts (Python)
├── lab-scripts/             # Legacy Proxmox scripts
├── reports/                 # Test output (gitignored)
├── Makefile                 # Build targets
├── mkdocs.yml               # Documentation config
└── requirements-docs.txt    # Documentation dependencies

Contribution Workflow

  1. Fork the repository
  2. Create a feature branch: git checkout -b feature/new-pipeline
  3. Make your changes
  4. Test locally: docker compose up -d --build && docker compose --profile test run --rm harness
  5. Push and open a pull request

Code Style

Shell Scripts

  • Use set -euo pipefail at the top of every script
  • Quote all variables: "${VAR}" not $VAR

Python

  • Use FastAPI for pipeline endpoints
  • Follow the uniform API contract (4 endpoints)
  • Use the framework's native extraction logic — don't override it

Documentation (MkDocs)

  • YAML frontmatter on every page (title + description)
  • Use admonitions for callouts (!!! info, !!! warning, !!! danger)
  • Use mermaid for diagrams
  • Use tabbed content for framework comparisons
  • Cross-link between sections

Next Steps