kahndor

    ## Project overview
    
    kahndor is the shared configuration and logging utility layer for the
    Solutions Brewer stack. It loads YAML and related configuration formats,
    resolves includes/overrides and templated values, caches results, and
    provides the `Logma` logging facade used across the ecosystem. kahndor
    is intentionally lightweight and dependency-minimal — every other
    SB-stack package depends on it.
    
    ## Features
    
    - **Cascade config loading** — load, merge, and override YAML files
      with the special `<(INCL)>` token for file inclusion.
    - **Memoization cache** — LRU-bounded in-memory cache with optional
      on-disk persistence, exposed via `kahndor.cache.Cache`.
    - **Logma logging** — structured, agent-aware logging facade via
      `kahndor.logma.Logma`.
    - **CLI** — `kahndor status`, `kahndor cache --stats/--clear`, plus
      utility and logging commands.
    - **Zero-config defaults** — sensible defaults baked in; overrides
      via `<project>/_data_/*.yaml`.
    
    ## Installation
    
    ```bash
    pip install kahndor
    ```
    
    From source:
    
    ```bash
    git clone https://github.com/solubrew/kahndor.git
    cd kahndor
    pip install -e ".[dev]"
    ```
    
    Runtime dependencies: `PyYAML`. Development: `pytest`, `pytest-asyncio`,
    `pytest-json-report`, `pytest-cov`, `ruff`.
    
    ## Quick start
    
    Load and merge a YAML configuration:
    
    ```python
    import kahndor
    
    cfg = kahndor.Instruct("config.yaml").select("ConfigA").override("config_b.yaml")
    print(cfg.dikt)
    ```
    
    Include another YAML file inline using the `<(INCL)>` token:
    
    ```yaml
    # config.yaml
    database:
        host: localhost
        port: 5432
        settings: <(INCL) settings.yaml>
    ```
    
    ```yaml
    # settings.yaml
    timeout: 30
    retry: 3
    ```
    
    Result:
    
    ```python
    {'database': {'host': 'localhost', 'port': 5432,
                  'settings': {'timeout': 30, 'retry': 3}}}
    ```
    
    Use the cache:
    
    ```python
    from kahndor.cache import Cache
    
    cache = Cache(max_memory_items=100)
    cache.set("user", "alice", {"name": "Alice", "role": "admin"})
    print(cache.get("user", "alice"))
    ```
    
    Use the logger:
    
    ```python
    from kahndor.logma import Logma
    
    logma = Logma(__name__)
    logma.info("kahndor ready")
    logma.error("something went wrong", extra={"agent": "arthr"})
    ```
    
    Use the CLI:
    
    ```bash
    kahndor status
    kahndor cache --stats
    kahndor --agent arthr cache --clear
    ```
    
    ## Usage
    
    ### Config cascade with `<(INCL)>`
    
    kahndor treats `<(INCL)>` specially during YAML load. The token is
    replaced with the contents of the referenced file (or kahndor
    attribute path, prefixed with `<(INCL)>`), enabling nested configs
    that read like prose:
    
    ```yaml
    paths:
        data: <(INCL) paths/data.yaml
        logs: <(INCL) paths/logs.yaml
    ```
    
    ### Selection and override
    
    ```python
    import kahndor
    
    # Load config.yaml, select the "production" section, override
    # values from prod-overrides.yaml.
    cfg = kahndor.Instruct("config.yaml") \
            .select("production") \
            .override("prod-overrides.yaml")
    ```
    
    ### Agent-aware logging
    
    ```python
    import os
    os.environ["KAHNDOR_AGENT"] = "arthr"
    
    from kahndor.logma import Logma
    logma = Logma(__name__)
    logma.info("started", extra={"component": "cli"})
    ```
    
    ## 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/kahndor.git
    cd kahndor
    python -m pip install --upgrade pip
    pip install -e ".[dev]"
    pip install pytest pytest-asyncio pytest-json-report pytest-cov
    
    # Run the test suite
    pytest tests/ -v
    
    # Lint (matches CI)
    ruff check kahndor/
    
    # Confirm the package imports cleanly
    python -c "import kahndor; print(kahndor.__version__)"
    
    # Run the CLI
    kahndor status
    
    # Run the compliance audit
    python -m sasquatch.cli analyze -p . --skip-pii-secrets
    ```
    
    Before opening a pull request:
    
    ```bash
    pytest tests/ -v              # all tests pass
    ruff check kahndor/           # no lint errors
    sasquatch analyze -p . --skip-pii-secrets    # audit score >= 90%
    ```
    
    ## License
    
    kahndor is licensed under the MIT License. See the [LICENSE](LICENSE) file
    for more details.
    
    ## Contact
    
    For questions or suggestions, contact
    [solubrew@solutionsbrewer.com](mailto:solubrew@solutionsbrewer.com).