> ## Documentation Index
> Fetch the complete documentation index at: https://simplellmfunc.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# Contributing

> How to contribute to SimpleLLMFunc

# Contributing

## Development Setup

```bash theme={null}
git clone https://github.com/NiJingzhe/SimpleLLMFunc.git
cd SimpleLLMFunc
poetry install
```

## Running Tests

```bash theme={null}
# All tests
poetry run pytest

# Specific test file
poetry run pytest tests/test_base/test_react_core_scheduler.py

# With verbose output
poetry run pytest -v
```

## Project Structure

```
SimpleLLMFunc/
├── SimpleLLMFunc/          # Source code
│   ├── llm_decorator/     # L1: Decorator layer
│   ├── base/              # L2+L3: Compile boundary + ReAct runtime
│   ├── runtime/           # Runtime primitives + selfref
│   ├── builtin/           # PyRepl, FileToolset, SelfReference
│   ├── hooks/             # Events, stream, abort
│   ├── interface/         # LLM adapters
│   ├── tool/              # @tool decorator
│   └── utils/             # TUI, stdio
├── tests/                 # Mirror of source structure
├── examples/              # Runnable examples
├── mintlify_docs/         # This documentation
└── spec/                  # Architecture specs
```

## Development Workflow

1. Read relevant source and tests before making changes
2. Write or update tests first (TDD)
3. Make the smallest coherent change
4. Run targeted tests, then broader tests
5. Update docs if user-facing behavior changed

## Key Rules

* All decorated functions must be `async def`
* Runtime side effects must flow through the internal patch boundary (never mutate live messages directly)
* Runtime primitive docstrings must include `Best Practices`
* Tests mirror source structure: `SimpleLLMFunc/base/react_loop.py` → `tests/test_base/test_react_loop.py`

## Code Style

* Python 3.12+
* PEP 8 formatting
* Type annotations on public APIs
* snake\_case functions, PascalCase classes, UPPER\_SNAKE\_CASE constants

## Documentation

* English docs in `mintlify_docs/` (root)
* Chinese translation follows (separate PR)
* Keep examples runnable and imports current

## Pull Requests

1. Fork the repository
2. Create a feature branch from `dev`
3. Make your changes with tests
4. Open a PR against `dev`
5. Describe what changed and why

## Issues

* Use GitHub Issues for bugs and feature requests
* Include: what you expected, what happened, minimal reproduction
* Label appropriately: `bug`, `feature`, `docs`, `refactor`