Subtrix

    ## Project overview
    
    Subtrix is a substitution module for Python, providing powerful tools for text
    manipulation through substitutions. The main interface is the `Mechanism` class,
    which allows for standard substitution, term expansion, and variable
    substitution.
    
    Subtrix is part of the Solutions Brewer (SB) stack and is consumed by sibling
    projects such as **GoaLT** (report rendering) and **Condor** (prompt
    templating). It is designed to be:
    
    - **Deterministic** — given the same template and data, output is byte-stable.
    - **Composable** — the public API is a single class with a small surface.
    - **Safe** — built-in security validation (max size, max recursion, dangerous
      pattern deny-list).
    - **Lightweight** — minimal dependencies, no template precompilation step.
    
    See [ARCHITECTURE.md](ARCHITECTURE.md) for the full design and
    [CLI.md](CLI.md) for the command-line interface.
    
    ## Features
    
    - Provides a basic substitution mechanism
    - Supports variable substitution
    - Supports lists of variables to generate multiple documents from a single template
    - Supports term expansion by using term looping substitution all combinations of a list of terms can be generated
    - Provides Prefix and Suffix Support with controls for trailing suffix
    
    ## Installation
    
    You can install Subtrix via pip:
    
    ```bash
    pip install subtrix
    ```
    
    Alternatively, clone the repository and install from source:
    
    ```bash
    git clone https://github.com/solubrew/subtrix.git
    cd subtrix
    pip install -e .
    ```
    
    ### Requirements
    
    - Python 3.<MIN_VERSION> or higher
    - Dependencies: re, <EVAL_LIB> (automatically installed via pip where applicable)
    
    ## Quick Start
    
    Import the module and use the Mechanism class for substitutions:
    
    ## Standard Patterns
    
    ### Substitution:
    
        <[token]>: basic substitution
        <~[token]~>: optional token substituion (is removed if unused in template render)
        <[prefix.:token]>: token substitution with prefix
        <[token:.suffix]>: token substitution with suffix
    
    ### Variable Substitution:
    
        <(token)>: registerd variable lookup for things like TODAY, USER, etc.
        <(prefix.:token)>: optional variable token substituion
        <(token:.suffix)>: optional variable token substituion
    
    ### Looped Variable Substitution:
    
        token: ['point0', 'point1']
        <@[token]@>: [['point0'], ['point1'], ['point0', 'point1']
    
    ```python
    from subtrix import Mechanism
    
    # Initialize Mechanism
    template = 'Hello, <[name]>!'
    data = {'name': 'World'}
    mech = Mechanism(template, data)
    
    # Perform standard substitution
    result = mech.run()
    print(result)  # Output: Hello, World!
    ```
    
    ## Usage
    
    
    ### Variable Substitution
    
    Inject variables from various sources:
    
    
    ## Development
    
    To set up a development environment and run the test suite locally:
    
    ```bash
    # Clone and install in editable mode with dev extras
    git clone https://github.com/solubrew/subtrix.git
    cd subtrix
    python -m pip install --upgrade pip
    pip install -e ".[dev]"
    pip install pytest pytest-asyncio
    
    # Run the test suite
    pytest tests/ -v
    
    # Lint (matches CI)
    ruff check subtrix/
    
    # Confirm the package imports cleanly
    python -c "import subtrix; print('Import OK:', subtrix.__name__)"
    
    # Render a template from the CLI
    python -m subtrix.cli subtrix "Hello <[name]>!" '{"name": "World"}'
    ```
    
    Before opening a pull request, also run the compliance auditor to verify the
    project is in a releasable state:
    
    ```bash
    PYTHONPATH=...:$TASKAXN_PYTHONPATH python -m sasquatch.cli analyze \
        -p . --agent m3rl1n --skip-pii-secrets
    ```
    
    A score of **>= 90 %** is required to tag a release. See
    [CI_CD.md](CI_CD.md) for the full pipeline description.
    
    ## Contributing
    
    Contributions are welcome! Please follow these steps:
    
    1. Fork the repository.
    2. Create a feature branch (`git checkout -b feature/<FEATURE_NAME>`).
    3. Commit your changes (`git commit -am 'Add some feature'`).
    4. Push to the branch (`git push origin feature/<FEATURE_NAME>`).
    5. Open a Pull Request.
    
    See [CONTRIBUTING.md](CONTRIBUTING.md) for more details.
    
    ## License
    
    This project is licensed under the MIT License - see the [LICENSE](LICENSE.rst) file for details.
    
    ## Acknowledgments
    
    - Built with inspiration from open-source templating and substitution libraries.
    - Thanks to contributors of underlying libraries like re, and Python's built-in eval.