Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/SanMuzZzZz/LuaN1aoAgent/llms.txt

Use this file to discover all available pages before exploring further.

Contributions of all kinds are welcome — bug reports, feature suggestions, code, documentation, and experience sharing.

​
Ways to contribute

Report a bug

Open an issue on GitHub with a description, reproduction steps, and environment info.

Suggest a feature

Open an issue describing the feature, its motivation, and how it fits the project’s scope.

Submit code

Fork the repository, create a branch, and open a Pull Request.

Share experience

Share usage tips, attack patterns, and deployment learnings in GitHub Discussions.

​
Reporting bugs

Before opening a new issue:
  1. Search existing issues to confirm the bug has not already been reported.
  2. Verify the problem exists on the latest version.
  3. Collect logs from logs/TASK-NAME/TIMESTAMP/run_log.json.
Use this template when opening an issue: 
**Problem description**
Brief description of the issue.

**Steps to reproduce**
1. Run command '...'
2. Set configuration '...'
3. Observe error '...'

**Expected behavior**
What you expected to happen.

**Actual behavior**
What actually happened.

**Environment**
- OS: [e.g. Ubuntu 22.04]
- Python version: [e.g. 3.11.4]
- LuaN1ao version: [e.g. v0.6.0]
- LLM provider: [e.g. DeepSeek V3.2]

**Logs**
(Paste relevant log output here)

**Additional context**
Any other information that helps diagnose the issue.

​
Development setup

1

Fork and clone

Fork the repository on GitHub, then clone your fork:
git clone https://github.com/your-username/LuaN1aoAgent.git
cd LuaN1aoAgent
2

Create a virtual environment

python -m venv venv
source venv/bin/activate   # Linux / macOS
# venv\Scripts\activate    # Windows
3

Install dependencies

pip install -r requirements.txt
Install pre-commit hooks (recommended):
pip install pre-commit
pre-commit install
4

Create a feature branch

Use a descriptive branch name:
# New feature
git checkout -b feature/amazing-feature

# Bug fix
git checkout -b fix/bug-description
5

Make your changes

Follow the code standards below. Write or update tests where applicable.
6

Commit and push

git add .
git commit -m "feat(planner): add branch replanning capability"
git push origin feature/amazing-feature
7

Open a Pull Request

Open a PR against the main branch. Fill in the PR template (see below) and link any related issues.

​
Code standards

The project uses ruff for linting and black for formatting, configured in pyproject.toml.
  • Linter: ruff with rules from pycodestyle, Pyflakes, isort, pep8-naming, flake8-bugbear, and others.
  • Formatter: black
  • Line length: 120 characters
  • Python version: 3.10+
  • Max cyclomatic complexity: 15
Run the linter:
ruff check .
Run the formatter:
black .

# Classes: PascalCase
class GraphManager:
    pass

# Functions and variables: snake_case
def process_graph_commands():
    node_id = "task_1"

# Constants: UPPER_SNAKE_CASE
MAX_RETRY_COUNT = 3

# Private members: _leading_underscore
def _internal_method():
    pass

# Standard library
import os
import sys

# Third-party
import httpx
from rich.console import Console

# Local modules
from core.graph_manager import GraphManager
from llm.llm_client import LLMClient
First-party packages: core, llm, rag, conf, tools.
from typing import Any, Dict, List, Optional

def function_name(param1: str, param2: int) -> str:
    """
    One-line summary.

    Longer description if needed.

    Args:
        param1: Description of param1.
        param2: Description of param2.

    Returns:
        str: Description of the return value.

    Raises:
        ValueError: When this occurs.
    """
    pass
  • Keep individual functions under 50 lines where possible. Split larger functions into helpers.
  • Each module should have a single, clear responsibility. Avoid circular imports.

​
Commit message format

Use Conventional Commits: 
<type>(<scope>): <short description>

[optional body]

[optional footer]
TypeWhen to use
featNew feature
fixBug fix
docsDocumentation only
styleFormatting, no logic change
refactorCode restructuring
testTests
choreBuild / tooling
Examples: 
git commit -m "feat(planner): add branch replanning functionality"
git commit -m "fix(executor): resolve tool call timeout issue"
git commit -m "docs: update installation instructions in README"

​
Pull Request process

Use this template when opening a PR: 
**Change type**
- [ ] Bug fix
- [ ] New feature
- [ ] Documentation update
- [ ] Performance improvement
- [ ] Refactoring

**Description**
Brief summary of what this PR does.

**Related issue**
Fixes #(issue number)

**Testing**
Describe how you tested these changes.

**Checklist**
- [ ] Code follows project standards
- [ ] Necessary comments added
- [ ] Related documentation updated
- [ ] All tests pass
- [ ] No new warnings introduced
PRs are reviewed for code quality, functional correctness, test coverage, documentation completeness, and backward compatibility.
Smaller PRs are easier to review and faster to merge. Start with a focused change rather than a large refactor.

​
Testing

# Run all tests
pytest

# Run a specific test file
pytest tests/test_planner.py

# Run with coverage
pytest --cov=core tests/
When writing tests, follow the Arrange-Act-Assert pattern: 
import pytest
from core.planner import Planner

class TestPlanner:
    def setup_method(self):
        self.planner = Planner(mock_llm_client)

    def test_plan_generation(self):
        # Arrange
        goal = "test target"

        # Act
        result = self.planner.plan(goal)

        # Assert
        assert result is not None
        assert len(result) > 0

    @pytest.mark.asyncio
    async def test_async_plan(self):
        result = await self.planner.async_plan("target")
        assert result is not None

​
Documentation contributions

If your change affects user-facing behavior:
  1. Update README.md if the change affects setup or usage.
  2. Update CHANGELOG.md under [Unreleased].
  3. Add usage examples where helpful.

​
Current development priorities

If you’re looking for high-impact areas:
  1. Core functionality — Improving Planner strategy generation, Executor parallel processing, and Reflector analysis depth.
  2. Tool ecosystem — Additional security tool integrations and MCP tool development templates.
  3. Performance — Reducing LLM call count, improving graph manager efficiency, and reducing memory footprint.
  4. User experience — Web UI improvements, additional configuration options, and clearer error messages.

​
License

This project is licensed under Apache 2.0. By submitting a contribution, you agree that your work will be distributed under the same license.

​
Getting help

Build docs developers (and LLMs) love

Get started for freeTalk to us