Thank you for your interest in contributing to the Self-Service Agent Blueprint! This document provides guidelines for contributing to the project.
- Code of Conduct
- How Can I Contribute?
- Development Setup
- Development Commands
- Submitting Changes
- Coding Standards
- Documentation
- Questions
By participating in this project, you agree to maintain a respectful and collaborative environment for all contributors.
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
We welcome suggestions for:
- New features or use cases
- Improvements to existing functionality
- Documentation improvements
- Evaluation metrics
- MCP server integrations
We appreciate contributions including:
- Bug fixes
- New features
- Documentation updates
- Test improvements
- New agent configurations
- MCP server implementations
- Knowledge base content
- Evaluation metrics
Ensure you have the required tools installed:
- Python 3.12+
- uv (Python package manager)
- Podman
- OpenShift CLI (oc)
- kubectl
- Helm
- Git
- Make
-
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
-
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 installdeploys to a cluster (Helm); useINSTALL_MODE=test|demo|prod(default: test).make uninstallremoves the deployment and namespace;make helm-uninstallremoves the deployment only (keeps namespace). -
Run tests:
make test-all
For local Kubernetes development without OpenShift, you can run a local Kind cluster with a container registry:
-
Create Kind cluster with registry:
sh ./scripts/ci/kind-with-registry.sh
-
Build and push images to local registry:
export REGISTRY=localhost:5001 make build-all-images make push-all-images -
Deploy to Kind cluster:
export NAMESPACE=dev make helm-install-test NAMESPACE=$NAMESPACE
-
Clean up when done:
kind delete cluster
Note: Images will be cached on the registry container and survive cluster deletion.
To see all available make commands with descriptions:
make helpThis displays all available targets including deployment modes, testing commands, and build options.
Formatting:
make format # Run Black formatting on entire codebaseLinting:
make lint # Run flake8 linting on entire codebaseAlways run these before committing your changes.
Run all tests:
make test-all # Run tests for all projectsRun 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 MCPNote: 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).
Build all images:
make build-all-images # Build all container imagesBuild 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 imageBuild 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-imagesBuild with specific version:
export VERSION=1.0.0
make build-all-imagesTroubleshooting 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=trueThis 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.
Push all images:
make push-all-images # Push all images to registryPush 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 imagemake helm-depend # Update Helm dependencies
make helm-list-models # List available models
make helm-status # Check deployment status-
Fork the repository and create a feature branch:
git checkout -b feature/your-feature-name
-
Make your changes following our coding standards
-
Test your changes:
make lint make format make test-all
-
Build container images:
export REGISTRY=quay.io/youruser make build-all-images -
Push images to registry:
make push-all-images
-
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=$NAMESPACEWait for all pods to be running:
oc get pods -n $NAMESPACE -
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.
-
Clean up test deployment:
make helm-uninstall NAMESPACE=$NAMESPACE -
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 featuresfix:- Bug fixesdocs:- Documentation changestest:- Test additions or fixeschore:- Maintenance tasks
-
Push to your fork:
git push origin feature/your-feature-name
-
Create a Pull Request with:
- Clear title and description
- Reference to related issues
- Description of changes made
- Testing performed
- Screenshots (if UI changes)
- 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
-
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
- 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
- Update relevant documentation when making changes
- Include code examples where helpful
- Update API documentation if endpoints change
- Add evaluation examples for new use cases
- 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
- Use clear, concise language
- Include code examples
- Add "Expected outcome" sections for procedures
- Use proper markdown formatting
- Link to related documentation
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
questionlabel
- README.md - Quickstart guide and system overview
- CLAUDE.md - Development guidance for Claude Code
- GUIDELINES.md - Code practices and project structure guidelines
- API_REFERENCE.md - Complete API documentation
- ARCHITECTURE_DIAGRAMS.md - System architecture diagrams
- INTEGRATION_GUIDE.md - Integration patterns and guides
- AUTHENTICATION_GUIDE.md - Authentication setup
- Component READMEs in each service directory
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!