Contributing Guidelines

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

Fork the Repository

Fork the NOMOS repository to your GitHub account

Clone Your Fork

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

Set Up Development Environment

# Install dependencies
poetry install

# Activate virtual environment
poetry shell

# Install pre-commit hooks
pre-commit install

Create a Branch

git checkout -b feature/your-feature-name

Types of Contributions

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

Python Code Style

Testing Requirements

Git Commit Messages

Pull Request Process

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

Development

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

Submit PR

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

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

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

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

import pytest
from nomos import Agent
from nomos.llms import OpenAI

@pytest.mark.integration
def test_openai_integration():
    """Test OpenAI LLM integration."""
    llm = OpenAI(model="gpt-3.5-turbo")
    agent = Agent(name="test", llm=llm)

    response = agent.run("Hello, world!")
    assert isinstance(response, str)
    assert len(response) > 0

from unittest.mock import Mock, patch
import pytest
from nomos.llms.openai import OpenAI

@patch('openai.ChatCompletion.create')
def test_openai_mock(mock_create):
    """Test OpenAI with mocked response."""
    mock_create.return_value = Mock(
        choices=[Mock(message=Mock(content="Test response"))]
    )

    llm = OpenAI(model="gpt-3.5-turbo")
    response = llm.generate("Test prompt")
    assert response == "Test response"

Documentation

Writing Documentation

MDX Format

Code Examples

API Documentation

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:

Search Existing Issues

Check if the bug has already been reported

Gather Information

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

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:

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

First-time Contributor

Regular Contributor

Core Contributor

Maintainer

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!

Community

Contributing

Support

Roadmap

​Getting Started

​Types of Contributions

​Bug Fixes

​New Features

​Performance Improvements

​Bug Fixes

​New Features

​Performance Improvements

​Content Improvements

​New Documentation

​Support & Engagement

​Content Creation

​Development Guidelines

​Code Standards

​Pull Request Process

​Project Structure

​Testing

​Running Tests

​Writing Tests

​Documentation

​Writing Documentation

​Building Documentation

​Issue Management

​Reporting Bugs

​Feature Requests

Problem Statement

Proposed Solution

​Community Guidelines

​Code of Conduct

​Communication Channels

GitHub Discussions

Discord Server

GitHub Issues

Email

​Recognition

​Contributor Levels

​Getting Help

Development Setup

Technical Questions

Contribution Ideas

Mentorship

​Thank You

Getting Started

Types of Contributions

Bug Fixes

New Features

Performance Improvements

Bug Fixes

New Features

Performance Improvements

Content Improvements

New Documentation

Support & Engagement

Content Creation

Development Guidelines

Code Standards

Pull Request Process

Project Structure

Testing

Running Tests

Writing Tests

Documentation

Writing Documentation

Building Documentation

Issue Management

Reporting Bugs

Feature Requests

Community Guidelines

Code of Conduct

Communication Channels

Recognition

Contributor Levels

Getting Help

Thank You