​

Contributing

​

Development Setup

git clone https://github.com/NiJingzhe/SimpleLLMFunc.git
cd SimpleLLMFunc
poetry install

​

Running Tests

# 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