Contributing to jaato

Welcome! This guide will help you start contributing to the jaato framework. Whether you're fixing bugs, adding features, or improving documentation, we're excited to have you.

What You'll Learn

This guide covers everything you need to contribute to jaato's core framework:

• Setting up your development environment
• Understanding the codebase architecture
• Running and writing tests
• Following code style guidelines
• Submitting pull requests

# Clone the repository
git clone https://github.com/Jaato-framework-and-examples/jaato.git
cd jaato

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install all packages in development mode
pip install -e jaato-sdk/. -e "jaato-server/.[all]" -e "jaato-tui/.[all]"

# Run tests
pytest

# All tests passing? You're ready!

Development Environment

Prerequisites

• Python 3.10+ - Check with python3 --version
• Git - For version control
• AI Provider Credentials - For integration testing (optional, any provider works)

Install Development Dependencies

The project uses pytest for testing. Install all three packages (SDK, server, TUI) in development mode with pip install -e jaato-sdk/. -e "jaato-server/.[all]" -e "jaato-tui/.[all]". Optional extras (vision/PNG support, AST search) are defined in pyproject.toml.

Verify Your Setup

Run the test suite to ensure everything is working correctly. All tests should pass on a fresh clone.

# Activate virtual environment
source .venv/bin/activate

# Run all tests
pytest

# Run tests with coverage
pytest --cov=shared --cov-report=html

# Run specific test file
pytest shared/plugins/cli/tests/test_cli.py

# Run tests matching pattern
pytest -k "test_plugin"

Understanding the Architecture

jaato is organized into several key components. Understanding this structure will help you navigate the codebase and identify where to make changes.

Package Structure

jaato consists of three packages:

• jaato-sdk/ - Lightweight SDK (events, types, IPC client)
• jaato-server/ - Server daemon with all runtime plugins
• jaato-tui/ - Terminal user interface client

Core Directories

• shared/ - Framework internals and plugin system
• server/ - Daemon, IPC, WebSocket, session management
• docs/ - Documentation and guides

Plugin Types

jaato has three distinct plugin systems:

• Tool Plugins - Provide tools for model function calling
• GC Plugins - Manage context window overflow
• Model Provider Plugins - Abstract AI provider SDKs

See the Architecture Deep Dive for detailed information about each component.

jaato/
├── jaato-sdk/                 # Lightweight SDK package
│   ├── jaato_sdk/
│   │   ├── events.py         # Event protocol types
│   │   ├── ipc_client.py     # IPC client
│   │   └── types.py          # Shared types
│   └── pyproject.toml
│
├── shared/                    # Core framework (server pkg)
│   ├── jaato_client.py       # Main client
│   ├── ai_tool_runner.py     # Tool executor
│   ├── token_accounting.py   # Token tracking
│   └── plugins/              # Plugin system
│       ├── cli/              # CLI tool plugin
│       ├── mcp/              # MCP integration
│       ├── gc*/              # GC strategies
│       └── model_provider/   # Provider abstraction
│
├── server/                    # Daemon and IPC/WS
│   ├── __main__.py           # Entry point
│   ├── core.py               # JaatoServer
│   ├── ipc.py                # Unix socket server
│   └── websocket.py          # WebSocket server
│
├── jaato-tui/                # TUI package
│   ├── rich_client.py        # Main TUI
│   └── pyproject.toml
│
└── docs/                     # Documentation
    └── architecture.md       # Architecture guide

Where to Contribute

There are many ways to contribute to jaato. Here are some common areas:

Core Framework

• Improve JaatoClient API and error handling
• Enhance plugin discovery and lifecycle management
• Optimize token accounting and retry logic
• Add support for new AI provider SDKs

Plugin System

• Build new built-in tool plugins
• Implement new GC (garbage collection) strategies
• Add model provider plugins (Anthropic, OpenAI, etc.)
• Improve plugin protocol and type safety

Testing & Quality

• Add test coverage for untested code
• Write integration tests for end-to-end workflows
• Improve error messages and debugging experience
• Add type hints and improve static analysis

Documentation

• Write guides and tutorials
• Add API documentation and examples
• Improve inline code comments
• Create video walkthroughs or demos

# Look for good first issues on GitHub
# These are beginner-friendly tasks

# Common patterns:
# - "good first issue" label
# - Documentation improvements
# - Test coverage additions
# - Small bug fixes

# Example contribution flow:
git checkout -b fix/issue-123
# ... make changes ...
pytest  # Ensure tests pass
git commit -m "fix: resolve issue #123"
git push origin fix/issue-123
# ... create PR on GitHub ...

## Bug Report
**Description:** JaatoClient.reset_session()
doesn't clear GC plugin state

**Steps to Reproduce:**
1. Create client with GC plugin
2. Send messages until GC triggers
3. Call reset_session()
4. GC state persists incorrectly

**Expected:** GC state should reset
**Actual:** State carries over

Code Style Guidelines

Python Style

• Follow PEP 8 conventions
• Use type hints for function signatures
• Write docstrings for public APIs
• Keep functions focused and under 50 lines when possible

Naming Conventions

• snake_case for functions and variables
• PascalCase for classes
• UPPER_CASE for constants
• Prefix private methods with _underscore

Documentation

• Add docstrings to all public classes and methods
• Include parameter types and return types
• Provide usage examples for complex functionality
• Update relevant documentation when changing behavior

See the Code Style Guide for detailed formatting rules and examples.

"""Example of good code style in jaato."""

from typing import Dict, List, Optional
from jaato import ToolSchema


class ExamplePlugin:
    """Example plugin demonstrating code style.

    This plugin shows proper formatting, type hints,
    and documentation practices.
    """

    def __init__(self, config: Optional[Dict] = None):
        """Initialize the plugin.

        Args:
            config: Optional configuration dictionary.
        """
        self._config = config or {}
        self._initialized = False

    @property
    def name(self) -> str:
        """Plugin name identifier."""
        return "example"

    def get_tool_schemas(self) -> List[ToolSchema]:
        """Return tool schemas for this plugin.

        Returns:
            List of ToolSchema objects.
        """
        return [
            ToolSchema(
                name="example_tool",
                description="An example tool",
                parameters={
                    "type": "object",
                    "properties": {
                        "message": {"type": "string"}
                    },
                    "required": ["message"]
                }
            )
        ]

    def _execute(self, args: Dict) -> Dict:
        """Private executor method.

        Args:
            args: Tool arguments from the model.

        Returns:
            Execution result dictionary.
        """
        return {"result": args.get("message", "")}

Submitting Pull Requests

Before You Submit

• Run tests - All tests must pass
• Add tests - New code needs test coverage
• Update docs - Document API changes
• Check style - Follow code conventions

Commit Messages

Use conventional commit format:

• feat: - New feature
• fix: - Bug fix
• docs: - Documentation only
• test: - Adding tests
• refactor: - Code refactoring
• chore: - Maintenance tasks

PR Description

Include in your PR description:

• What problem does this solve?
• What changes did you make?
• How can reviewers test it?
• Any breaking changes or migration notes?

See the Pull Request Guide for detailed submission guidelines.

# Create feature branch
git checkout -b feat/add-anthropic-provider

# Make changes and commit
git add shared/plugins/model_provider/anthropic/
git commit -m "feat: Add Anthropic provider plugin

- Implement ModelProviderPlugin protocol
- Add Claude API integration
- Include streaming support
- Add comprehensive tests

Closes #123"

# Push to your fork
git push origin feat/add-anthropic-provider

# Create PR on GitHub
# - Fill out PR template
# - Request review
# - Address feedback
# - Merge when approved!

feat: Add session auto-save on exit

Implement automatic session saving when the
client shuts down or the program exits. This
prevents data loss when users forget to
manually save.

Changes:
- Add atexit handler to JaatoClient
- Implement _auto_save() method
- Add AUTO_SAVE_ON_EXIT config option
- Update session plugin tests

Breaking: None
Migration: None (feature is opt-in)