Skip to main content
Thank you for your interest in contributing to NOMOS! We welcome contributions from developers of all skill levels. This guide will help you get started and understand our development process.

​
Getting Started

1

Fork the Repository

Fork the NOMOS repository to your GitHub account
2

Clone Your Fork

git clone https://github.com/yourusername/nomos.git
cd nomos
3

Set Up Development Environment

# Install dependencies
poetry install

# Activate virtual environment
poetry shell

# Install pre-commit hooks
pre-commit install
4

Create a Branch

git checkout -b feature/your-feature-name

​
Types of Contributions

  • Code Contributions
  • Documentation
  • Community

​
Bug Fixes

  • Fix reported issues and bugs
  • Add test cases for edge cases
  • Improve error handling and validation

​
New Features

  • Implement new LLM provider integrations
  • Add new agent capabilities
  • Enhance the playground
  • Improve CLI functionality

​
Performance Improvements

  • Optimize agent execution speed
  • Reduce memory usage
  • Improve concurrency handling

​
Development Guidelines

​
Code Standards

  • Follow PEP 8 style guidelines
  • Use Black for code formatting
  • Use type hints for all functions
  • Write docstrings for all public functions and classes
  • Maximum line length: 88 characters
  • Write unit tests for all new functions
  • Maintain test coverage above 80%
  • Use pytest for testing framework
  • Include integration tests for new features
  • Test edge cases and error conditions
type(scope): brief description

Longer description if needed explaining what
changed and why.

Fixes #123
Types: feat, fix, docs, style, refactor, test, chore

​
Pull Request Process

1

Before You Start

  • Check existing issues and PRs to avoid duplicates
  • Discuss major changes in GitHub discussions first
  • Make sure your fork is up to date with main branch
2

Development

  • Write clean, well-documented code
  • Add or update tests as needed
  • Update documentation if required
  • Run all tests locally before submitting
3

Submit PR

  • Use the PR template provided
  • Link to related issues
  • Add clear description of changes
  • Request review from maintainers
4

Review Process

  • Address feedback promptly
  • Keep discussions constructive
  • Update your branch if conflicts arise
  • Ensure CI passes before merge

​
Project Structure

Understanding the codebase structure helps with effective contributions: 
nomos/
├── nomos/              # Core framework code
│   ├── api/           # REST API and web interface
│   ├── llms/          # LLM provider integrations
│   ├── memory/        # Memory and context management
│   ├── models/        # Data models and schemas
│   ├── testing/       # Testing utilities
│   └── utils/         # Utility functions
├── tests/             # Test suite
├── docs/              # Documentation source
├── cookbook/          # Examples and tutorials
├── support/           # Supporting tools and SDKs
└── pyproject.toml     # Project configuration

​
Testing

​
Running Tests

# Run complete test suite
pytest

# Run with coverage
pytest --cov=nomos --cov-report=html

# Run specific test file
pytest tests/test_core.py

# Run tests with output
pytest -v -s

​
Writing Tests

  • Unit Tests
  • Integration Tests
  • Mock Testing
import pytest
from nomos.core import Agent
from nomos.llms.base import BaseLLM

def test_agent_initialization():
    """Test that agent initializes correctly."""
    agent = Agent(name="test-agent")
    assert agent.name == "test-agent"
    assert agent.state is not None

def test_agent_with_llm():
    """Test agent with LLM configuration."""
    llm = BaseLLM()
    agent = Agent(name="test", llm=llm)
    assert agent.llm == llm

​
Documentation

​
Writing Documentation

  • Use MDX format for all documentation
  • Include frontmatter with title and description
  • Use Mintlify components (Cards, Tabs, CodeGroups)
  • Add code examples for all features
  • Include working, tested code examples
  • Show both basic and advanced usage
  • Use meaningful variable names
  • Add comments explaining complex parts
  • Document all public functions and classes
  • Include parameter types and descriptions
  • Show example usage and return values
  • Note any exceptions that may be raised

​
Building Documentation

# Install Mintlify CLI
npm install -g @mintlify/cli

# Preview documentation
cd docs
mintlify dev

# Check for broken links
mintlify broken-links

​
Issue Management

​
Reporting Bugs

Use our bug report template:
1

Search Existing Issues

Check if the bug has already been reported
2

Gather Information

  • NOMOS version
  • Python version
  • Operating system
  • LLM provider being used
  • Minimal reproduction case
3

Create Detailed Report

  • Clear, descriptive title
  • Steps to reproduce
  • Expected vs actual behavior
  • Error messages and stack traces

​
Feature Requests

Use our feature request template:

Problem Statement

Clearly describe the problem you’re trying to solve

Proposed Solution

Explain your ideal solution and any alternatives considered

​
Community Guidelines

​
Code of Conduct

We are committed to providing a welcoming and inclusive environment:
  • Our Pledge
  • Unacceptable Behavior
  • Enforcement
  • Use welcoming and inclusive language
  • Respect differing viewpoints and experiences
  • Accept constructive criticism gracefully
  • Focus on what’s best for the community
  • Show empathy towards other community members

​
Communication Channels

GitHub Discussions

General questions, ideas, and community chat

Discord Server

Real-time chat with developers and maintainers

GitHub Issues

Bug reports and feature requests

Email

Private communication with maintainers

​
Recognition

We believe in recognizing our contributors:

​
Contributor Levels

  • Welcome package and mentorship
  • Help with setting up development environment
  • Guidance on good first issues
  • Recognition in release notes
  • Access to contributor-only Discord channels
  • Early access to new features
  • Commit access to specific areas
  • Participation in technical discussions
  • Input on roadmap and feature planning
  • Full repository access
  • Release management responsibilities
  • Community leadership role

​
Getting Help

Development Setup

Having trouble with your dev environment? Ask in Discord or GitHub discussions

Technical Questions

Need help understanding the codebase? We’re here to help!

Contribution Ideas

Not sure what to work on? Check our “good first issue” label

Mentorship

New to open source? We offer mentorship for first-time contributors

​
Thank You

Every contribution, no matter how small, helps make NOMOS better for everyone. Thank you for being part of our community!
Ready to contribute? Check out our good first issues or join our Discord to get started!
⌘I