Metadata-Version: 2.4
Name: attune-help
Version: 0.3.1
Summary: Lightweight help runtime with progressive depth and audience adaptation.
Author-email: Patrick Roebuck <admin@smartaimemory.com>
License:                                  Apache License
                                   Version 2.0, January 2004
                                http://www.apache.org/licenses/
        
           TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
        
           Copyright 2026 Smart AI Memory
        
           Licensed under the Apache License, Version 2.0 (the "License");
           you may not use this file except in compliance with the License.
           You may obtain a copy of the License at
        
               http://www.apache.org/licenses/LICENSE-2.0
        
           Unless required by applicable law or agreed to in writing, software
           distributed under the License is distributed on an "AS IS" BASIS,
           WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
           See the License for the specific language governing permissions and
           limitations under the License.
        
Project-URL: Homepage, https://github.com/Smart-AI-Memory/attune-ai
Project-URL: Repository, https://github.com/Smart-AI-Memory/attune-ai
Keywords: help,documentation,progressive-depth,templates
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Documentation
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: python-frontmatter>=1.0.0
Provides-Extra: rich
Requires-Dist: rich>=13.0.0; extra == "rich"
Provides-Extra: plugin
Requires-Dist: mcp>=0.9.0; extra == "plugin"
Dynamic: license-file

# attune-help

Lightweight help runtime with progressive depth and
audience adaptation. Read project help templates
generated by [attune-ai](https://pypi.org/project/attune-ai/).

## Install

```bash
pip install attune-help
```

## Quick Start

```python
from attune_help import HelpEngine

engine = HelpEngine(template_dir=".help/templates")

# Progressive depth: concept -> task -> reference
print(engine.lookup("security-audit"))   # concept
print(engine.lookup("security-audit"))   # task
print(engine.lookup("security-audit"))   # reference
```

## How It Works

Each topic has three depth levels:

| Level | Type | What you get |
|-------|------|-------------|
| 0 | Concept | What is it? When to use it? |
| 1 | Task | Step-by-step how-to |
| 2 | Reference | Full detail, edge cases |

Repeated lookups on the same topic auto-advance.
A new topic resets to concept.

## Renderers

```python
# Plain text (default)
engine = HelpEngine(renderer="plain")

# Rich terminal output (requires `pip install attune-help[rich]`)
engine = HelpEngine(renderer="cli")

# Claude Code inline format
engine = HelpEngine(renderer="claude_code")

# Auto-detect environment
engine = HelpEngine(renderer="auto")
```

## Template Directory

Templates are markdown files with YAML frontmatter:

```
.help/templates/
  security/
    concept.md
    task.md
    reference.md
  api/
    concept.md
    task.md
    reference.md
```

Generate templates with
[attune-ai](https://pypi.org/project/attune-ai/):

```bash
pip install attune-ai
# Then in Claude Code:
/coach init
```

Or create them manually — any markdown file with
`feature`, `depth`, and `source_hash` frontmatter
fields works.

## Demo Templates

The package includes a demo feature showing the
progressive depth format:

```python
from attune_help import get_demo_path

# Copy to your project
import shutil
shutil.copytree(
    get_demo_path() / "security-audit",
    ".help/templates/security-audit",
)
```

The `security-audit/` demo contains `concept.md`,
`task.md`, and `reference.md` — the three depth
levels that `/coach init` generates for each feature.

## API

### `HelpEngine`

```python
HelpEngine(
    template_dir=None,    # Override template path
    storage=None,         # Session storage backend
    renderer="plain",     # Output renderer
    user_id="default",    # Session tracking ID
)
```

**Methods:**

- `lookup(topic)` — Progressive depth lookup
- `get(template_id)` — Direct template access
- `lookup_raw(topic)` — Returns `PopulatedTemplate`
  dataclass
- `get_summary(skill)` — One-line skill summary
- `precursor_warnings(file_path)` — File-aware
  warnings

### `SessionStorage` Protocol

Implement custom storage backends:

```python
from attune_help import SessionStorage

class RedisStorage(SessionStorage):
    def load(self, user_id: str) -> dict: ...
    def save(self, user_id: str, state: dict) -> None: ...
```

## License

Apache 2.0
