{"id":48749075,"url":"https://github.com/smart-ai-memory/attune-help","last_synced_at":"2026-05-01T13:00:49.836Z","repository":{"id":350868419,"uuid":"1206136855","full_name":"Smart-AI-Memory/attune-help","owner":"Smart-AI-Memory","description":"Lightweight .help/ runtime reader with progressive depth. Python package for the attune-docs help platform.","archived":false,"fork":false,"pushed_at":"2026-05-01T11:04:02.000Z","size":941,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-01T12:05:31.173Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Smart-AI-Memory.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-09T16:01:34.000Z","updated_at":"2026-05-01T11:04:05.000Z","dependencies_parsed_at":null,"dependency_job_id":"21afa293-74f6-4aa8-8afe-b3e1b153f6e4","html_url":"https://github.com/Smart-AI-Memory/attune-help","commit_stats":null,"previous_names":["smart-ai-memory/attune-help"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/Smart-AI-Memory/attune-help","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Smart-AI-Memory%2Fattune-help","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Smart-AI-Memory%2Fattune-help/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Smart-AI-Memory%2Fattune-help/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Smart-AI-Memory%2Fattune-help/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Smart-AI-Memory","download_url":"https://codeload.github.com/Smart-AI-Memory/attune-help/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Smart-AI-Memory%2Fattune-help/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32497815,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-30T13:12:12.517Z","status":"online","status_checked_at":"2026-05-01T02:00:05.856Z","response_time":64,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-12T15:30:48.869Z","updated_at":"2026-05-01T13:00:49.803Z","avatar_url":"https://github.com/Smart-AI-Memory.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# attune-help\n\nLightweight help runtime with progressive depth and\naudience adaptation. Read project help templates\ngenerated by [attune-ai](https://pypi.org/project/attune-ai/).\n\n## Install\n\n```bash\npip install attune-help\n```\n\n## Quick Start\n\n```python\nfrom attune_help import HelpEngine\n\nengine = HelpEngine(template_dir=\".help/templates\")\n\n# Progressive depth: concept -\u003e task -\u003e reference\nprint(engine.lookup(\"security-audit\"))   # concept\nprint(engine.lookup(\"security-audit\"))   # task\nprint(engine.lookup(\"security-audit\"))   # reference\n```\n\n## How It Works\n\nEach topic has three depth levels:\n\n| Level | Type | What you get |\n|-------|------|-------------|\n| 0 | Concept | What is it? When to use it? |\n| 1 | Task | Step-by-step how-to |\n| 2 | Reference | Full detail, edge cases |\n\nRepeated lookups on the same topic auto-advance.\nA new topic resets to concept.\n\n## Renderers\n\n```python\n# Plain text (default)\nengine = HelpEngine(renderer=\"plain\")\n\n# Rich terminal output (requires `pip install attune-help[rich]`)\nengine = HelpEngine(renderer=\"cli\")\n\n# Claude Code inline format\nengine = HelpEngine(renderer=\"claude_code\")\n\n# Structured JSON (for apps, web, tests)\nengine = HelpEngine(renderer=\"json\")\n\n# Auto-detect environment (CLAUDE_CODE → claude_code,\n# interactive TTY + rich → cli, otherwise → plain)\nengine = HelpEngine(renderer=\"auto\")\n\n# Switch renderer at runtime\nengine.set_renderer(\"cli\")\n```\n\nPassing an unknown renderer name raises `ValueError`.\n\n## Template Directory\n\nTemplates are markdown files with YAML frontmatter:\n\n```\n.help/templates/\n  security/\n    concept.md\n    task.md\n    reference.md\n  api/\n    concept.md\n    task.md\n    reference.md\n```\n\nGenerate templates with\n[attune-ai](https://pypi.org/project/attune-ai/):\n\n```bash\npip install attune-ai\n# Then in Claude Code:\n/coach init\n```\n\nOr create them manually — any markdown file with\n`feature`, `depth`, and `source_hash` frontmatter\nfields works.\n\n## Demo Templates\n\nThe package includes a demo feature showing the\nprogressive depth format:\n\n```python\nfrom attune_help import get_demo_path\n\n# Copy to your project\nimport shutil\nshutil.copytree(\n    get_demo_path() / \"security-audit\",\n    \".help/templates/security-audit\",\n)\n```\n\nThe `security-audit/` demo contains `concept.md`,\n`task.md`, and `reference.md` — the three depth\nlevels that `/coach init` generates for each feature.\n\n## Discovery\n\n```python\nengine.list_topics()                  # all slugs\nengine.list_topics(type_filter=\"concepts\")  # filter by type\nengine.search(\"security\")             # [(slug, score), ...]\nengine.suggest(\"secrity-audit\")       # ranked slugs\n```\n\nMiss handling:\n\n```python\n# Returns None by default\nengine.lookup(\"typoed-slug\")\n\n# Returns \"No help for 'typoed-slug'. Did you mean: ...\"\nengine.lookup(\"typoed-slug\", suggest_on_miss=True)\n```\n\n## Progressive Depth Controls\n\n```python\nengine.lookup(\"security-audit\")    # concept\nengine.lookup(\"security-audit\")    # task\nengine.lookup(\"security-audit\")    # reference (depth 2)\n\nengine.simpler(\"security-audit\")   # step back to task\nengine.simpler(\"security-audit\")   # step back to concept\n\nengine.reset(\"security-audit\")     # clear one topic\nengine.reset()                     # clear all topics\n```\n\nTopics are tracked independently — interleaving\n`lookup(\"a\")` / `lookup(\"b\")` / `lookup(\"a\")` does **not**\nreset `a`'s depth. An LRU cap of 32 topics keeps session\nstate bounded.\n\n## MCP Server\n\nInstall with the plugin extra and use as an MCP server:\n\n```bash\npip install attune-help[plugin]\nattune-help-mcp   # stdio transport\n```\n\nExposed tools (all prefixed `lookup_` for namespace\nhygiene against other plugins):\n\n| Tool | Purpose |\n|------|---------|\n| `lookup_topic` | Progressive depth lookup |\n| `lookup_simpler` | Step a topic one level back |\n| `lookup_reset` | Clear a single topic or full session |\n| `lookup_status` | Read session state (topics + LRU order) |\n| `lookup_list` | Category-grouped topic enumeration |\n| `lookup_list_topics` | Flat slug enumeration (optionally by type) |\n| `lookup_search` | Fuzzy slug search with scores |\n| `lookup_suggest` | \"Did you mean\" slug suggestions |\n| `lookup_warn` | File-context warnings for a path |\n| `lookup_preamble` | \"Use X when...\" one-liner for a feature |\n\nAll tools that render help content accept the same\nrenderer set as the Python API: `plain`, `claude_code`,\n`cli`, `marketplace`, `json` (the `auto` sentinel is\nexcluded because auto-detection is meaningless over a\nprotocol boundary).\n\n## API\n\n### `HelpEngine`\n\n```python\nHelpEngine(\n    template_dir=None,    # Override template path\n    storage=None,         # Session storage backend\n    renderer=\"plain\",     # Output renderer\n    user_id=\"default\",    # Session tracking ID\n)\n```\n\n**Methods:**\n\n- `lookup(topic, *, suggest_on_miss=False)` — Progressive\n  depth lookup with optional \"did you mean\" on miss\n- `simpler(topic)` — Step back one depth level\n- `reset(topic=None)` — Clear depth history for one topic\n  or all\n- `list_topics(type=None, limit=None)` — Enumerate slugs\n- `search(query, limit=10)` — Fuzzy-search slugs\n- `suggest(topic, limit=5)` — Ranked slug suggestions\n- `get(template_id)` — Direct template access\n- `lookup_raw(topic)` — Returns `PopulatedTemplate`\n  dataclass\n- `get_summary(skill)` — One-line skill summary (falls\n  back to bundled when an override lacks it)\n- `precursor_warnings(file_path)` — File-aware warnings\n  (supports Python, JS/TS, Rust, Go, Ruby, Java, …)\n- `set_renderer(name)` — Change renderer at runtime\n\n### `SessionStorage` Protocol\n\nImplement custom storage backends:\n\n```python\nfrom attune_help import SessionStorage\n\nclass RedisStorage(SessionStorage):\n    def load(self, user_id: str) -\u003e dict: ...\n    def save(self, user_id: str, state: dict) -\u003e None: ...\n```\n\n## Staleness Detection\n\n`attune-help` tracks whether your help templates are up to date with\nyour source code using SHA-256 hashes stored in template frontmatter.\n\n### Basic usage\n\n```python\nfrom attune_help import load_manifest, check_staleness\n\nmanifest = load_manifest(\".help\")\nreport = check_staleness(manifest, help_dir=\".help\", project_root=\".\")\n\nfor entry in report.stale_features:\n    print(f\"{entry} is stale — regenerate with attune-ai\")\n```\n\n### Semantic hashing (v0.10+)\n\nFor pure-Python features, `compute_source_hash` automatically uses\n**semantic hashing**: only public-symbol *contracts* (parameters, return\ntypes, decorators, base classes) contribute to the hash. Docstring\nedits, body rewrites, and formatter passes (`black`, `ruff`) are\nignored. This eliminates spurious template regenerations when nothing\nmeaningful changed.\n\n```python\nfrom attune_help import compute_source_hash, compute_semantic_hash\nfrom attune_help.manifest import Feature\n\nfeat = Feature(name=\"auth\", description=\"\", files=[\"src/auth/**\"])\n\n# compute_source_hash uses semantic hashing automatically for .py-only features\nhash1, files = compute_source_hash(feat, project_root=\".\")\n\n# Call compute_semantic_hash directly when you need the semantic hash\n# regardless of file mix (e.g. for reporting)\nhash2, files = compute_semantic_hash(feat, project_root=\".\")\n```\n\nMixed-content features (Python + Jinja, YAML, etc.) and features with\nsyntax errors in their source files fall back to byte-level SHA\nautomatically — no configuration required.\n\n### Corpus validation\n\nA 3-sweep validation harness ships in `scripts/validate_against_corpus.py`:\n\n```bash\n# Validate against any repo with a .help/features.yaml\npython scripts/validate_against_corpus.py --repo /path/to/your/repo\n```\n\nSweeps: (1) parse integrity — all `.py` files parse cleanly; (2)\ndeterminism — identical hashes on two consecutive calls; (3) HEAD vs\nHEAD^ — classifies symbol changes as signature drift / body-only /\nadd / remove.\n\n## Template aliases\n\nTemplates can declare `aliases:` in their frontmatter to cover\nretrieval gaps — synonyms and alternate phrasings that keyword search\nwould otherwise miss:\n\n```yaml\n---\ntype: concept\nfeature: tool-planning\naliases:\n  - how to plan tools\n  - tool design principles\n  - when to use tools\n---\n```\n\n`aliases` is a YAML list of strings. The retrieval engine scores alias\nhits the same as title hits, so a query that uses a synonym routes to\nthe right template even when the canonical slug has no token overlap.\n\n## License\n\nApache 2.0\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmart-ai-memory%2Fattune-help","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsmart-ai-memory%2Fattune-help","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmart-ai-memory%2Fattune-help/lists"}