Skip to content

Latest commit

 

History

History
440 lines (333 loc) · 11.7 KB

CONTRIBUTING.md

File metadata and controls

440 lines (333 loc) · 11.7 KB

Contributing to Self-Service Agent Blueprint

Thank you for your interest in contributing to the Self-Service Agent Blueprint! This document provides guidelines for contributing to the project.

Table of Contents

Code of Conduct

By participating in this project, you agree to maintain a respectful and collaborative environment for all contributors.

How Can I Contribute?

Reporting Bugs

If you find a bug, please create an issue with:

  • Clear description of the problem
  • Steps to reproduce
  • Expected vs actual behavior
  • Environment details (OpenShift version, LLM model, deployment mode)
  • Relevant logs or error messages

Suggesting Enhancements

We welcome suggestions for:

  • New features or use cases
  • Improvements to existing functionality
  • Documentation improvements
  • Evaluation metrics
  • MCP server integrations

Contributing Code

We appreciate contributions including:

  • Bug fixes
  • New features
  • Documentation updates
  • Test improvements
  • New agent configurations
  • MCP server implementations
  • Knowledge base content
  • Evaluation metrics

Development Setup

Prerequisites

Ensure you have the required tools installed:

  • Python 3.12+
  • uv (Python package manager)
  • Podman
  • OpenShift CLI (oc)
  • kubectl
  • Helm
  • Git
  • Make

Local Setup

  1. Clone the repository:

    Get the repository URL by clicking the green Code button at the top of the repository page, then:

    git clone <repository-url>
    cd <repository-directory>  # The directory name matches the repository name
  2. Install dependencies (local dev):

    make deps-all

    Or install specific components:

    make deps                       # Self-service agent dependencies (root)
    make deps-request-manager       # Request manager dependencies
    make deps-agent-service         # Agent service dependencies
    make deps-integration-dispatcher # Integration dispatcher dependencies
    make deps-mcp-snow              # ServiceNow MCP dependencies
    make deps-mcp-zammad            # Zammad MCP dependencies

    Note: make install deploys to a cluster (Helm); use INSTALL_MODE=test|demo|prod (default: test). make uninstall removes the deployment and namespace; make helm-uninstall removes the deployment only (keeps namespace).

  3. Run tests:

    make test-all

Local Development with Kind Cluster

For local Kubernetes development without OpenShift, you can run a local Kind cluster with a container registry:

  1. Create Kind cluster with registry:

    sh ./scripts/ci/kind-with-registry.sh
  2. Build and push images to local registry:

    export REGISTRY=localhost:5001
    make build-all-images
    make push-all-images
  3. Deploy to Kind cluster:

    export NAMESPACE=dev
    make helm-install-test NAMESPACE=$NAMESPACE
  4. Clean up when done:

    kind delete cluster

    Note: Images will be cached on the registry container and survive cluster deletion.

Development Commands

Quick Reference

To see all available make commands with descriptions:

make help

This displays all available targets including deployment modes, testing commands, and build options.

Code Quality

Formatting:

make format                     # Run Black formatting on entire codebase

Linting:

make lint                       # Run flake8 linting on entire codebase

Always run these before committing your changes.

Testing

Run all tests:

make test-all                   # Run tests for all projects

Run component-specific tests:

make test                       # Run tests for self-service agent
make test-request-manager       # Run tests for request manager
make test-agent-service         # Run tests for agent service
make test-integration-dispatcher # Run tests for integration dispatcher
make test-mcp-snow             # Run tests for ServiceNow MCP

Container Operations

Note: Container images do not include HEALTHCHECK instructions as health monitoring is handled by Kubernetes liveness and readiness probes in the Helm deployment.

Default Registry:

By default, container images are built for quay.io/rh-ai-quickstart. You can override this by setting the REGISTRY environment variable (see examples below).

Building Container Images

Build all images:

make build-all-images           # Build all container images

Build individual images:

make build-request-mgr-image    # Build request manager image
make build-agent-service-image  # Build agent service image
make build-integration-dispatcher-image  # Build integration dispatcher image
make build-mcp-snow-image       # Build ServiceNow MCP image

Build for ARM architecture:

make build-all-images REGISTRY=quay.io/<user> ARCH="linux/arm64"

Use custom registry:

export REGISTRY=your-registry.com/your-org
make build-all-images

Build with specific version:

export VERSION=1.0.0
make build-all-images

Troubleshooting QEMU issues on Mac M1/M2/M3: If you encounter QEMU segmentation faults when building Linux AMD64 containers on Apple Silicon, use the USE_PIP_INSTALL workaround:

# Use pip install method instead of uv sync (workaround for QEMU issues)
make build-all-images USE_PIP_INSTALL=true

This workaround uses pip install from requirements.txt instead of uv sync, which can avoid QEMU emulation issues when cross-compiling for Linux on Apple Silicon. The default uv sync method is faster and more reliable on native Linux/CI environments.

Pushing Container Images

Push all images:

make push-all-images            # Push all images to registry

Push individual images:

make push-request-mgr-image     # Push request manager image
make push-agent-service-image   # Push agent service image
make push-integration-dispatcher-image  # Push integration dispatcher image
make push-mcp-snow-image        # Push ServiceNow MCP image

Helm Operations

make helm-depend                # Update Helm dependencies
make helm-list-models           # List available models
make helm-status                # Check deployment status

Submitting Changes

Pull Request Process

  1. Fork the repository and create a feature branch:

    git checkout -b feature/your-feature-name
  2. Make your changes following our coding standards

  3. Test your changes:

    make lint
    make format
    make test-all
  4. Build container images:

    export REGISTRY=quay.io/youruser
    make build-all-images
  5. Push images to registry:

    make push-all-images
  6. Deploy to OpenShift test environment:

    Set required environment variables:

    export NAMESPACE=dev-test
    export LLM=llama-3-3-70b-instruct-w8a8
    export LLM_ID=llama-3-3-70b-instruct-w8a8
    export LLM_API_TOKEN=your-api-token
    export LLM_URL=https://your-llm-endpoint
    export HF_TOKEN=1234

    Deploy with Helm:

    make helm-install-test NAMESPACE=$NAMESPACE

    Wait for all pods to be running:

    oc get pods -n $NAMESPACE
  7. Run evaluations to ensure quality:

    make test-short-resp-integration-request-mgr

    Important: All evaluations must pass before submitting your PR. This validates that your changes maintain agent quality and don't introduce regressions.

  8. Clean up test deployment:

    make helm-uninstall NAMESPACE=$NAMESPACE
  9. Commit your changes with clear, descriptive messages:

    git add .
    git commit -m "feat: add new MCP server for HR system"

    Use conventional commit messages:

    • feat: - New features
    • fix: - Bug fixes
    • docs: - Documentation changes
    • test: - Test additions or fixes
    • chore: - Maintenance tasks
  10. Push to your fork:

    git push origin feature/your-feature-name
  11. Create a Pull Request with:

  • Clear title and description
  • Reference to related issues
  • Description of changes made
  • Testing performed
  • Screenshots (if UI changes)

Review Process

  • All submissions require review before merging
  • Reviewers may request changes or improvements
  • Address feedback and update your PR
  • Once approved, maintainers will merge your contribution

Coding Standards

Python Code

  • Format code with Black:

    make format
  • Use type hints:

    def process_request(request: Request) -> Response:
        pass
  • Add docstrings for functions and classes:

    def create_agent(config: AgentConfig) -> Agent:
        """Create and register a new agent with LlamaStack.
    
        Args:
            config: Agent configuration including instructions and tools
    
        Returns:
            Registered agent instance
        """
        pass
  • Follow PEP 8 style guidelines

  • Run linting before committing:

    make lint

Configuration Files

  • Agent configs: Use YAML format in agent-service/config/agents/
  • Knowledge bases: Place text files in agent-service/config/knowledge_bases/
  • Helm values: Follow existing structure in helm/values.yaml

Documentation

  • Update relevant documentation when making changes
  • Include code examples where helpful
  • Update API documentation if endpoints change
  • Add evaluation examples for new use cases

Documentation

What to Document

  • New features: Update relevant README files
  • API changes: Update API_REFERENCE.md
  • Architecture changes: Update ARCHITECTURE_DIAGRAMS.md
  • New integrations: Create guide in docs/ or component README
  • Configuration changes: Update quickstart and setup guides

Documentation Style

  • Use clear, concise language
  • Include code examples
  • Add "Expected outcome" sections for procedures
  • Use proper markdown formatting
  • Link to related documentation

Questions?

If you have questions about contributing:

  • Review the Quickstart Guide for system overview and architecture
  • Check existing documentation in docs/
  • Review component-specific README files
  • Check existing issues for similar questions
  • Open a new issue with the question label

Helpful Documentation


License

By contributing to this project, you agree that your contributions will be licensed under the Apache License 2.0.


Thank you for contributing to the Self-Service Agent Blueprint!