---
title: Contributing
description: How to contribute to Mirascope
---

# Contributing

Thank you for your interest in contributing to Mirascope! We welcome contributions from the community and are excited to have you join us.

Mirascope is a monorepo with two main areas for contribution: the **Python SDK** and the **Website**. See [STRUCTURE.md](https://github.com/Mirascope/mirascope/blob/main/STRUCTURE.md) for a detailed breakdown of the codebase organization.

## Development Workflow

### 1. Find or Create an Issue

Search [GitHub Issues](https://github.com/Mirascope/mirascope/issues) for existing work or create a new issue to discuss your idea.

- Look for `good first issue` labels if you're new
- Create an issue before starting significant work

### 2. Fork and Clone

```bash
git clone https://github.com/<your-username>/mirascope.git
cd mirascope
git remote add upstream https://github.com/Mirascope/mirascope.git
```

### 3. Create a Branch

```bash
git checkout main
git pull upstream main
git checkout -b feat/my-feature-name
```

### 4. Make Your Changes

- **Keep changes focused**: One logical change per PR
- **Follow existing patterns**: Look at similar code in the codebase
- **Add tests**: All new code requires tests
- **Update documentation**: If your change affects user-facing behavior

### 5. Commit with Conventional Commits

```bash
git commit -m "feat(llm): add Document content type tests"
git commit -m "fix(website): resolve layout issue"
git commit -m "docs: update contributing guide"
```

### 6. Submit a Pull Request

```bash
git push origin feat/my-feature-name
```

When opening your PR:

- Use a title following [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/)
- Describe what your PR does and why
- Link the related issue
- Check the box to allow maintainer edits

---

## Python SDK

### Prerequisites

- Python 3.10+
- [uv](https://docs.astral.sh/uv/) package manager

### Install uv

<TabbedSection>
<Tab value="macOS/Linux">
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```
</Tab>
<Tab value="Windows">
```powershell
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
```
</Tab>
</TabbedSection>

### Setup

```bash
cd python

# Create virtual environment and install dependencies
uv sync --all-extras --dev

# Install pre-commit hooks
uv run pre-commit install --install-hooks

# Verify setup
uv run pytest tests/ -x
```

### Running Tests

```bash
uv run pytest tests/                              # Run all tests
uv run pytest tests/llm/content/test_thought.py   # Run specific file
uv run pytest tests/ --cov=mirascope --cov-report=html  # With coverage
```

### Formatting and Linting

```bash
uv run ruff format .    # Format code
uv run ruff check .     # Lint code
uv run pyright .        # Type check
```

### PR Checklist

- [ ] Tests pass: `uv run pytest tests/`
- [ ] 100% coverage for new code
- [ ] Type check passes: `uv run pyright .`
- [ ] Linting passes: `uv run ruff check .`
- [ ] Code formatted: `uv run ruff format .`
- [ ] Conventional commit messages

---

## Website

The website is a React application using TanStack Router and Cloudflare Workers, serving the documentation, blog, and landing page.

### Prerequisites

- Node.js 18+
- [Bun](https://bun.sh/) runtime

### Install Bun

<TabbedSection>
<Tab value="macOS/Linux">
```bash
curl -fsSL https://bun.sh/install | bash
```
</Tab>
<Tab value="Windows">
```powershell
powershell -c "irm bun.sh/install.ps1 | iex"
```
</Tab>
</TabbedSection>

### Setup

```bash
cd website

# Install dependencies
bun install

# Start dev server
bun run dev
```

### Running Tests

<Warning>
Always use `bun run test` (not `bun test`) to run tests through vitest with proper configuration.
</Warning>

```bash
bun run test                    # Run all tests
bun run test:coverage           # With coverage
```

### Type Checking and Linting

```bash
bun run typecheck      # TypeScript type checking
bun run lint:oxlint    # oxlint
```

### PR Checklist

- [ ] Tests pass: `bun run test`
- [ ] Type check passes: `bun run typecheck`
- [ ] Linting passes: `bun run lint:oxlint`
- [ ] Conventional commit messages

---

## Code Quality

### Coverage

Both the Python SDK and Cloud application require **100% test coverage** for new code.

### Type Safety

We place high value on type safety:

- All public functions must have complete type annotations
- Avoid `# type: ignore` or `// @ts-ignore` unless absolutely necessary
- Prefer specific types over `Any` or `unknown`

### Docstrings (Python)

Use Google-style docstrings:

```python
def create_tool(fn: Callable[..., T], *, strict: bool = False) -> Tool[T]:
    """Creates a tool from a function.

    Args:
        fn: The function to convert to a tool.
        strict: Whether to use strict mode for tool calling.

    Returns:
        A Tool instance wrapping the function.
    """
```

---

## Getting Help

- **Questions**: Open a [GitHub Discussion](https://github.com/Mirascope/mirascope/discussions)
- **Bugs**: File a [GitHub Issue](https://github.com/Mirascope/mirascope/issues)
- **Chat**: Join our community on [Discord](https://mirascope.com/discord-invite)

Thank you for contributing to Mirascope!
