Skip to content

Contributing to DAO

Let's build

Thank you for your interest in contributing to DAO! This guide will help you get started.

Project Structure

dao-ai/
├── src/dao_ai/
│   ├── config.py          # Pydantic configuration models
│   ├── graph.py           # LangGraph workflow builder
│   ├── nodes.py           # Agent node factories
│   ├── state.py           # State management
│   ├── tools/             # Tool implementations
│   │   ├── genie.py       # Genie tool with caching
│   │   ├── mcp.py         # MCP integrations
│   │   ├── vector_search.py
│   │   └── ...
│   ├── middleware/        # Agent middleware
│   │   ├── assertions.py  # Assert, Suggest, Refine middleware
│   │   ├── summarization.py # Conversation summarization
│   │   ├── guardrails.py  # MLflow judge-based guardrails, content filtering, and safety
│   │   ├── memory_context.py # Auto-injection of long-term memories into prompts
│   │   └── ...
│   ├── orchestration/     # Multi-agent orchestration
│   │   ├── supervisor.py  # Supervisor pattern
│   │   ├── swarm.py       # Swarm pattern
│   │   └── ...
│   ├── genie/
│   │   └── cache/         # LRU and Context-Aware cache
│   ├── memory/            # Checkpointer, store, schemas, and extraction
│   └── hooks/             # Lifecycle hooks
├── config/
│   ├── examples/          # Example configurations
│   └── hardware_store/    # Reference implementation
├── tests/                 # Test suite
└── schemas/               # JSON schemas for validation

Development Setup

Prerequisites

  • Python 3.12 or newer
  • Git
  • Access to a Databricks workspace (for integration tests)

Installation

  1. Fork and clone the repository:
git clone https://github.com/your-username/dao-ai.git
cd dao-ai
  1. Create a virtual environment:
# Using uv (recommended)
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Or using standard Python
python3 -m venv .venv
source .venv/bin/activate
  1. Install development dependencies:
make install

Python 3.12+ required. On 3.11, uv can't install a recent transitive pyarrow (25.x) — its cp311 wheel trips a uv wheel-parsing bug (Metadata field Name not found / Invalid Wheel-Version) that upgrading uv doesn't fix; 3.12 uses a different, working wheel. A SyntaxError: source code string cannot contain null bytes (e.g. importing langgraph) means a dependency file is corrupted from a failed install — rebuild clean: rm -rf .venv && uv cache clean && uv venv && make install.

Contributing Guidelines

1. Fork the Repository

Create a fork of the repository on GitHub and clone it locally.

2. Create a Feature Branch

git checkout -b feature/your-feature-name

Use descriptive branch names: - feature/add-new-tool - bugfix/fix-cache-issue - docs/update-readme

3. Make Your Changes

  • Follow the existing code style
  • Add tests for new functionality
  • Update documentation as needed
  • Keep commits focused and atomic

4. Run Tests

# Run all tests
make test

# Run specific test file
pytest tests/test_config.py

# Run with coverage
pytest --cov=dao_ai tests/

5. Format Code

# Format code with black and isort
make format

# Check linting
make lint

6. Update Documentation

  • Update README.md if adding new features
  • Add docstrings to new functions/classes
  • Update configuration examples if needed
  • Add entries to CHANGELOG.md

7. Submit a Pull Request

  1. Push your branch to your fork
  2. Open a pull request against the main repository
  3. Describe your changes clearly
  4. Reference any related issues

Code Style

Python Style Guide

  • Follow PEP 8 guidelines
  • Use type hints for function parameters and return values
  • Write descriptive docstrings (Google style)
  • Keep functions focused and small

Example:

def create_agent_tool(
    config: AgentConfig,
    workspace_client: WorkspaceClient,
) -> BaseTool:
    """
    Create a tool that calls another agent endpoint.

    Args:
        config: Agent configuration
        workspace_client: Databricks workspace client

    Returns:
        Configured tool instance

    Raises:
        ValueError: If configuration is invalid
    """
    # Implementation
    pass

YAML Configuration Style

  • Use 2 spaces for indentation
  • Keep configurations readable and well-commented
  • Use anchors and references to avoid repetition

Example:

resources:
  models:
    default_llm: &default_llm
      name: databricks-gpt-5-4-mini
      temperature: 0.7

agents:
  my_agent:
    name: my_agent
    model: *default_llm  # Reference the anchor

Testing

Writing Tests

  • Place tests in the tests/ directory
  • Mirror the source structure (e.g., tests/dao_ai/test_config.py)
  • Use pytest fixtures for common setup
  • Mock external services (Databricks APIs, databases)

Example:

import pytest
from dao_ai.config import AppConfig

def test_load_config(tmp_path):
    """Test configuration loading from file."""
    config_file = tmp_path / "config.yaml"
    config_file.write_text("""
    app:
      name: test_agent
    """)

    config = AppConfig.from_file(str(config_file))
    assert config.app.name == "test_agent"

Running Tests

# Run all tests
pytest

# Run specific test
pytest tests/test_config.py::test_load_config

# Run with verbose output
pytest -v

# Run with coverage report
pytest --cov=dao_ai --cov-report=html tests/

Adding New Features

Adding a New Tool

  1. Create tool module in src/dao_ai/tools/
  2. Implement tool following LangChain patterns
  3. Add factory function if needed
  4. Add tests in tests/dao_ai/tools/
  5. Add example configuration in appropriate examples/ category
  6. Update documentation

Adding New Middleware

  1. Create middleware in src/dao_ai/middleware/
  2. Inherit from BaseMiddleware
  3. Implement required methods
  4. Add tests
  5. Add configuration example
  6. Document usage

Adding New Orchestration Pattern

  1. Create module in src/dao_ai/orchestration/
  2. Implement pattern using LangGraph
  3. Add configuration model in src/dao_ai/config.py
  4. Add tests
  5. Add example configuration
  6. Document pattern

Documentation

Updating Documentation

  • Main docs are in docs/ directory
  • Update relevant sections when adding features
  • Include code examples
  • Add diagrams if helpful (ASCII art or images)

Adding Examples

  1. Choose the appropriate category in examples/ based on primary feature demonstrated:
  2. 01_getting_started/ - Foundation concepts for beginners
  3. 02_tools/ - Tool integrations (Genie, AI Search, Slack, MCP, etc.)
  4. 04_genie/ - Performance optimization strategies
  5. 05_memory/ - State management and persistence
  6. 06_on_behalf_of_user/ - User-level authentication and access control
  7. 07_human_in_the_loop/ - Approval workflows
  8. 08_guardrails/ - Safety and validation
  9. 09_structured_output/ - Enforce JSON schemas
  10. 10_agent_integrations/ - External agent platforms
  11. 11_prompt_engineering/ - Prompt management and optimization
  12. 12_middleware/ - Validation, logging, monitoring
  13. 13_orchestration/ - Multi-agent coordination patterns
  14. 14_basic_tools/ - Simple tool patterns

  15. 99_complete_applications/ - Full-featured, production-ready applications

  16. Use descriptive file names: tool_name_variant.yaml (e.g., slack_with_threads.yaml)

  17. Create your example config in the chosen category directory

  18. Add entry to docs/examples.md in the appropriate category table

  19. Test the example thoroughly: 

    dao-ai validate -c examples/0X_category/your_example.yaml
dao-ai chat -c examples/0X_category/your_example.yaml

  20. Add inline comments explaining key concepts and design decisions

  21. Update the category README.md with prerequisites and usage notes

Release Process

Maintainers will handle releases, but here's the process:

  1. Update version in pyproject.toml
  2. Update CHANGELOG.md with changes
  3. Create git tag: git tag v0.x.0
  4. Push tag: git push origin v0.x.0
  5. GitHub Actions will build and publish

Getting Help

  • Questions: Open a GitHub Discussion
  • Bugs: Open a GitHub Issue
  • Features: Open a GitHub Issue with [Feature Request] prefix
  • Security: See SECURITY.md (if available) or email maintainers

Code of Conduct

  • Be respectful and inclusive
  • Welcome newcomers
  • Focus on constructive feedback
  • Help others learn and grow

License

By contributing, you agree that your contributions will be licensed under the MIT License.

Thank you for contributing to DAO! 🎉