Metadata-Version: 2.4
Name: kahndor
Version: 0.0.1
Summary: Core agent system and cache orchestration for SBOT
Author: Maintainers
Author-email: solubrew@solutionsbrewer.com
License: MIT
Platform: Linux
Requires-Python: >=3.8
Requires-Dist: PyYAML>=6.0,<7.0
Requires-Dist: click>=8.0,<9.0
Requires-Dist: rich>=13.0,<14.0
Requires-Dist: ogma ; extra == "internal"
Requires-Dist: subtrix ; extra == "internal"
Requires-Dist: pytest>=8.0 ; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23 ; extra == "dev"
Requires-Dist: pytest-json-report>=1.5 ; extra == "dev"
Requires-Dist: pytest-cov>=4.1 ; extra == "dev"
Requires-Dist: ruff>=0.5 ; extra == "dev"
Provides-Extra: internal
Provides-Extra: dev
Description: # 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).
Description-Content-Type: text/markdown
