import byzerllm


@byzerllm.prompt()
def _ac_mod_files() -> str:
    """
    # AC Modules (.ac.mod.md) Complete Guide

    ## What is an AC Module?

    Any directory containing a `.ac.mod.md` file is considered an AC Module - a language-agnostic module that provides complete functionality and can be used as an API. These modules are self-contained units with well-defined interfaces and comprehensive documentation.

    AC Modules basically should not be larger than 60K tokens. You can use the `count_tokens` tool to get the token count of the module.

    ## AC Module Structure

    The `.ac.mod.md` file contains detailed information about:

    | Section | Description |
    |---------|-------------|
    | Module overview | One-sentence description of core functionality |
    | Directory structure | Complete file tree with functionality descriptions |
    | Quick start guide | Basic usage examples and code snippets |
    | Core components | Main classes, methods, and their responsibilities (keep it simple) |
    | Sequence diagrams | Visual flow showing component interactions and calling relationships |
    | Dependency graphs | Internal dependencies and relationships between components |
    | External dependencies | References to other AC modules it depends on |
    | Configuration management | Setup examples and configuration files |
    | Testing instructions | Executable commands and test examples |

    ## When to Use AC Modules

    1. **Avoid duplicate implementation**: Check if functionality already exists in project AC modules before implementing new features
    2. **Project understanding**: Review multiple AC modules to gain comprehensive knowledge of the entire project architecture
    3. **File modification context**: When modifying files in a directory, check if it's an AC module or contains AC modules to understand the full impact

    ## Tools Reference

    ### ac_mod_list

    **When to use:**
    - When you want to list all AC modules in the project
    - When you want to list all AC modules in a specific directory

    **Usage:**

    ```xml
    <ac_mod_list>
    </ac_mod_list>
    ```

    ### ac_mod_read

    **When to use:**
    - To retrieve comprehensive information about an AC module
    - The tool reads the `.ac.mod.md` file and provides structured information

    **Usage:**

    ```xml
    <ac_mod_read>
    <path>src/autocoder/agent</path>
    </ac_mod_read>
    ```

    ### ac_mod_write

    **When to use:**
    - When we edit files in an AC module, we should update the `.ac.mod.md` file to reflect the changes
    - When the user directly asks you to create or update an AC module

    **Usage:**

    ```xml
    <ac_mod_write>
    <path>src/autocoder/agent</path>
    <diff>
     search and replace blocks here
    </diff>
    </ac_mod_write>
    ```

    ## .ac.mod.md File Specification

    The content of the `.ac.mod.md` file should **strictly follow** the structure below.

    ### Complete Example

    ```markdown
    # User Authentication Management Module

    An AC module providing complete user authentication, authorization, and session management functionality with support for multiple authentication methods and fine-grained permission control.

    ## Directory Structure

    ```
    user_auth_module/
    ├── main.py                      # Main program entry, provides CLI interface
    ├── requirements.txt             # Python dependency list
    ...
    │   ├── examples/                # Usage examples
    ...
    │   │   └── integration_example.py # Integration example
    │   └── migration_guide.md       # Migration guide
    └── .ac.mod.md                   # This document
    ```

    ## Quick Start

    ### Basic Usage

    ```python
    # Import necessary modules
    from user_auth_module.auth import Authenticator
    ...

    # 1. Initialize configuration
    config = {
        'secret_key': 'your-secret-key',
    ...
        token = authenticator.generate_token(user)
        print(f"Authentication successful, token: {token}")
    ```

    ### Permission Management

    ```python
    from user_auth_module.permissions import RBACManager
    rbac = RBACManager(config)
    ...
    if rbac.user_has_permission(user, 'user:create'):
        print("User has create permission")
    ```

    ### Configuration Management

    Configuration file `config.yaml` example:

    ```yaml
    # Authentication configuration
    authentication:
    ...
    default_role: "user"
    ```

    ## Core Components

    ### 1. Authenticator Main Class

    **Core Features:**
    - **Multi-provider Authentication**: Support for local, OAuth, LDAP and other authentication methods
    ...

    **Main Methods:**
    - `authenticate(username, password)`: Username/password authentication
    ...

    ### 3. SessionManager Session Manager

    **Core Features:**
    - **Session Creation**: Create sessions for authenticated users
    ...

    **Main Methods:**
    - `create_session(user)`: Create user session
    ...

    ## Operation Sequence Diagram

    The following diagram shows the complete user authentication flow, from user login to permission verification:

    ```mermaid
    sequenceDiagram
        participant Client as Client
        ...
        Client->>Auth: Login request(username, password)
        Auth->>Auth: Validate input parameters
        ....
        Auth-->>Client: Logout successful
    ```

    ## Mermaid File Dependency Graph

    ```mermaid
    graph TB
        %% Main program entry
        Main[main.py<br/>CLI Interface Entry]

        %% Core authentication modules
        Auth[auth/authenticator.py<br/>Main Authenticator]
        ...
        class Crypto,Validators,Helpers utilClass
        class Config,Database dataClass
    ```

    ## Dependency Relationships

    Dependencies with other AC modules:

    - ../logging_module/.ac.mod.md  # Logging module
    ...
    - ../crypto_module/.ac.mod.md    # Encryption/decryption module

    ## Commands to Verify Module Functionality

    ### Basic Function Tests

    ```bash
    # Run all tests
    python -m pytest tests/ -v

    # Run specific tests
    python -m pytest tests/test_authenticator.py -v

    # Run integration tests
    python -m pytest tests/test_integration.py -v
    ```

    ### Command Line Tool Tests

    ```bash
    # Create test user
    python main.py create-user --username testuser --password testpass123
    ```

    ### Performance Tests

    ```bash
    python tests/performance/concurrent_auth_test.py --users 100 --duration 60
    ...
    python tests/performance/permission_performance_test.py --operations 5000
    ```

    ### Debugging Tips

    **Enable debug logging**:
    ```bash
    export AUTH_LOG_LEVEL=DEBUG
    python main.py --debug authenticate --username testuser
    ```
    ...
    **Database query debugging**:
    ```bash
    export AUTH_DB_ECHO=true
    python main.py list-users
    ```
    ```

    ## Writing Best Practices

    ### 1. Keep Module Size Manageable

    - AC Modules should not exceed 60K tokens
    - Use `count_tokens` tool to check size
    - When a new AC module is created, if the module is too large, split it into multiple modules
    - When converting an existing module to AC module, split if too large

    ### 2. Required Sections Checklist

    Every `.ac.mod.md` should include:

    - [ ] Module title and one-line description
    - [ ] Directory structure with file descriptions
    - [ ] Quick start with runnable code examples
    - [ ] Core components (classes/methods) overview
    - [ ] Sequence diagram for main workflows
    - [ ] Dependency graph (Mermaid)
    - [ ] External AC module dependencies
    - [ ] Verification commands (tests, CLI)

    ### 3. Keep Documentation in Sync

    - **Always update `.ac.mod.md` when editing module files** - use `ac_mod_write` tool
    - Document new files, classes, or methods added
    - Update dependency graphs when relationships change
    - Keep code examples working and up-to-date

    ### 4. Cross-Reference Dependencies

    - Use relative paths for referencing other AC modules: `../other_module/.ac.mod.md`
    - Document both internal and external dependencies
    - Keep dependency graphs accurate

    ## Guidelines

    1. **Check AC modules before coding** - Always run `ac_mod_list` first to see what already exists
    2. **Read before modify** - Use `ac_mod_read` before editing any file in an AC module directory
    3. **Update after changes** - Use `ac_mod_write` to keep `.ac.mod.md` in sync after code changes
    4. **Size matters** - Keep modules under 60K tokens, split if necessary
    5. **Follow the template** - Strictly follow the example structure for consistency
    6. **Include Mermaid diagrams** - Both sequence diagrams and dependency graphs are required
    """
