grandma 0.1.0__tar.gz

grandma-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,30 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install hatch
+        run: pip install hatch
+
+      - name: Lint
+        run: hatch run lint
+
+      - name: Test
+        run: hatch run test

grandma-0.1.0/.github/workflows/rotate-grandma.yml

@@ -0,0 +1,39 @@
+name: Rotate grandma mascot
+
+# Security: this workflow uses no external/untrusted input in run: blocks.
+# CHOSEN is derived only from local repo file listing (RANDOM % COUNT).
+
+on:
+  schedule:
+    - cron: "0 6 * * *"   # daily at 06:00 UTC
+  workflow_dispatch:        # allow manual trigger
+
+permissions:
+  contents: write
+
+jobs:
+  rotate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Pick a random grandma image
+        run: |
+          IMAGES=(assets/grandmas/grandma-*.png)
+          COUNT=${#IMAGES[@]}
+          IDX=$(( RANDOM % COUNT ))
+          CHOSEN="${IMAGES[$IDX]}"
+          cp "$CHOSEN" assets/grandma.png
+          echo "Chose: $CHOSEN (index $IDX of $COUNT)"
+
+      - name: Commit if changed
+        run: |
+          git config user.name  "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add assets/grandma.png
+          if git diff --cached --quiet; then
+            echo "Same image — nothing to commit"
+          else
+            git commit -m "chore: rotate grandma mascot [skip ci]"
+            git push
+          fi

grandma-0.1.0/.gitignore

@@ -0,0 +1,20 @@
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+.venv/
+venv/
+env/
+dist/
+build/
+*.egg-info/
+.eggs/
+*.egg
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+htmlcov/
+.coverage
+coverage.xml
+*.log
+.DS_Store

grandma-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yali Pollak
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

grandma-0.1.0/PKG-INFO

@@ -0,0 +1,278 @@
+Metadata-Version: 2.4
+Name: grandma
+Version: 0.1.0
+Summary: Explain it like you'd tell grandma.
+Project-URL: Homepage, https://github.com/ypollak2/grandma
+Project-URL: Repository, https://github.com/ypollak2/grandma
+Project-URL: Bug Tracker, https://github.com/ypollak2/grandma/issues
+Author-email: Yali Pollak <yali.pollak@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 Yali Pollak
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: ai,bottom-line,cli,extraction,llm,summary
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Requires-Dist: anthropic>=0.20.0
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: typer[all]>=0.9.0
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+<!-- Grandma rotates daily via .github/workflows/rotate-grandma.yml -->
+<img src="assets/grandma.png" alt="👵 grandma" width="320" />
+
+# 👵 grandma
+
+**Explain it like you'd tell grandma.**
+
+[![PyPI - Version](https://img.shields.io/pypi/v/grandma.svg)](https://pypi.org/project/grandma)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/grandma.svg)](https://pypi.org/project/grandma)
+[![License: MIT](https://img.shields.io/github/license/ypollak2/grandma.svg)](https://github.com/ypollak2/grandma/blob/main/LICENSE)
+[![CI](https://github.com/ypollak2/grandma/actions/workflows/ci.yml/badge.svg)](https://github.com/ypollak2/grandma/actions/workflows/ci.yml)
+
+</div>
+
+---
+
+You know her. She loves you, she read the whole thing, and she is **not** sitting through six paragraphs of agent confetti to find out whether the test passed.
+
+Grandma does not dumb it down. She keeps every fact that matters. She just refuses to waste your afternoon.
+
+`grandma` takes verbose LLM output and distils it to three lines: **what happened**, **the bottom line**, and **what to do next**.
+
+---
+
+## 💸 Token savings
+
+Every time you read a raw LLM response, you pay in attention — or in tokens if you pipe it into another model.
+
+| | Words | Reading tokens | Cost to re-read |
+|---|---|---|---|
+| Raw LLM response | ~400 | ~530 | 100% |
+| **grandma card** | **~40** | **~55** | **~10%** |
+| **Savings** | | | **~90% fewer tokens** |
+
+**Why this matters:**
+
+- In agent loops, every intermediate response fed back into context costs tokens. Grandma compresses the signal.
+- In multi-step workflows (plan → code → review → deploy), each step can save 400–500 tokens of context bloat.
+- Deep mode trades a bit more output for full structured data — still 70–80% smaller than the raw response.
+- Across a 20-turn session, grandma typically saves **8,000–12,000 context tokens**.
+
+---
+
+## Before / After
+
+**Raw LLM output (~90 words, ~120 tokens):**
+
+```text
+I inspected the repository and found that the authentication flow now routes through
+the new async session adapter. I updated three files, added one regression test, and
+confirmed that the login path still returns the expected token shape. There is one
+compatibility consideration: the adapter relies on Python 3.9+ typing behavior, so
+Python 3.8 users will need to upgrade or pin the old release. Overall, this should
+reduce request latency, but the deployment notes should mention the runtime floor.
+```
+
+**After grandma (default mode — ~30 words, ~40 tokens):**
+
+```
+👵 grandma
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📖 Second turn reviewing an auth refactor PR.
+
+What happened: Auth moved to the async session adapter.
+Bottom line:   Faster login path, but Python 3.8 is out.
+Do next:       Document Python ≥3.9 before shipping.
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+**After grandma (deep mode — full impact table):**
+
+```
+👵 grandma
+┌──────────────┬──────────────────────────────────────────────┐
+│ 📖 story arc │ Second turn reviewing an auth refactor PR.   │
+│ 👀 happened  │ Auth moved to async session adapter.         │
+│ 🧶 changed   │ 3 files, 1 regression test added.            │
+│ ✅ positive  │ Login latency reduced; token shape unchanged. │
+│ ⚠️  negative  │ Breaks Python 3.8 (asyncio.TaskGroup).       │
+│ ➖ neutral   │ API surface unchanged.                        │
+│ 💡 net gain  │ Win — ship it with a runtime floor note.     │
+│ 📋 actions   │ - Add Python ≥3.9 to pyproject.toml          │
+│              │ - Update deployment docs                      │
+└──────────────┴──────────────────────────────────────────────┘
+```
+
+---
+
+## Install
+
+```bash
+pip install grandma
+# or
+pipx install grandma
+# or from source
+pip install git+https://github.com/ypollak2/grandma.git
+```
+
+---
+
+## Usage
+
+**Pipe any text through grandma:**
+
+```bash
+echo "long agent output..." | grandma
+cat response.txt | grandma --mode deep
+cat response.txt | grandma --json        # raw JSON verdict
+cat response.txt | grandma --mode off    # passthrough
+```
+
+**Demo (no API key needed):**
+
+```bash
+grandma --demo
+grandma --demo --mode deep
+```
+
+**Environment variable for default mode:**
+
+```bash
+export GRANDMA_MODE=deep
+```
+
+---
+
+## The Modes
+
+| Mode | What you get | Model used | Best for |
+|---|---|---|---|
+| `default` | 3-line card: happened / bottom line / do next | Haiku | Most agent output |
+| `deep` | Full impact table with positive/negative/neutral | Sonnet | PRs, arch decisions, refactors |
+| `off` | Passthrough — original text unchanged | — | When you need the whole casserole |
+
+---
+
+## Works without an API key
+
+Grandma runs on your **Claude Code subscription** — no `ANTHROPIC_API_KEY` needed:
+
+```
+grandma → claude -p - (stdin pipe) → your Claude Code OAuth session
+```
+
+Set `ANTHROPIC_API_KEY` only if you want to use your own API credits instead.
+
+---
+
+## IDE & agent integrations
+
+Grandma works anywhere LLMs produce text. One-liner install for all detected tools:
+
+```bash
+./install.sh
+```
+
+| Tool | Integration type | What happens |
+|---|---|---|
+| **Claude Code** | Stop hook (native) | Auto-card after every long response |
+| **Codex CLI** | Stop hook (native) | Auto-card after every long response |
+| **Gemini CLI** | AfterAgent hook (native) | Auto-card after every agent turn |
+| **Cursor** | MCP + `.cursor/rules` | Agent calls `grandma_summarize` after long replies |
+| **Cline** | MCP + rules | Agent calls `grandma_summarize` after tasks |
+| **Continue** | MCP + `/grandma` slash command | On demand or automatic |
+| **Windsurf** | MCP + `.windsurfrules` | Agent calls `grandma_summarize` after long replies |
+| **Zed** | MCP (`context_servers`) | Tool available in Zed AI panel |
+| **Goose** | MCP extension | Tool available in Goose sessions |
+| **Aider** | `grandma-aider` wrapper | Pipe aider output through grandma |
+| **OpenHands** | `grandma-openhands` wrapper | Pipe headless output through grandma |
+
+**MCP server (for any MCP-capable IDE):**
+
+```bash
+grandma serve
+```
+
+Exposes two tools:
+- `grandma_summarize(text, mode, story_context)` → plain-text card
+- `grandma_summarize_json(text, mode, story_context)` → structured dict
+
+Add to any `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "grandma": { "command": "grandma", "args": ["serve"] }
+  }
+}
+```
+
+---
+
+## How the mascot rotates
+
+Each grandma portrait in this repo (`assets/grandmas/`) was generated with Gemini Image.  
+A [daily GitHub Action](.github/workflows/rotate-grandma.yml) picks one at random and replaces `assets/grandma.png`.  
+The README always shows the current winner. No JS. No CDN. No infrastructure.
+
+Want to add your own grandma? Drop a PNG into `assets/grandmas/` and open a PR.
+
+---
+
+## FAQ
+
+**Does grandma make it dumber?**  
+No dear. She keeps the facts. She removes the fog machine.
+
+**Does default mode include everything?**  
+It includes what you need first. Use `--mode deep` when you need the full table.
+
+**Why is there an off mode?**  
+Because sometimes you want the original, and grandma knows when to leave a person alone.
+
+**What's the `story_so_far` line?**  
+Grandma reads the last 3 turns of the conversation to understand where you are in the arc.  
+If you are on turn 8 of debugging the same auth bug, she will tell you. This is the dementia prevention feature.
+
+**Which models does it use?**  
+Default mode: `claude-haiku-4-5-20251001`. Deep mode: `claude-sonnet-4-6`.  
+Both run on your Claude Code subscription — no extra key needed.
+
+---
+
+<div align="center">
+<sub>Made with 💜 by <a href="https://github.com/ypollak2">Yali Pollak</a> · MIT License</sub>
+</div>

grandma-0.1.0/README.md

@@ -0,0 +1,228 @@
+<div align="center">
+
+<!-- Grandma rotates daily via .github/workflows/rotate-grandma.yml -->
+<img src="assets/grandma.png" alt="👵 grandma" width="320" />
+
+# 👵 grandma
+
+**Explain it like you'd tell grandma.**
+
+[![PyPI - Version](https://img.shields.io/pypi/v/grandma.svg)](https://pypi.org/project/grandma)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/grandma.svg)](https://pypi.org/project/grandma)
+[![License: MIT](https://img.shields.io/github/license/ypollak2/grandma.svg)](https://github.com/ypollak2/grandma/blob/main/LICENSE)
+[![CI](https://github.com/ypollak2/grandma/actions/workflows/ci.yml/badge.svg)](https://github.com/ypollak2/grandma/actions/workflows/ci.yml)
+
+</div>
+
+---
+
+You know her. She loves you, she read the whole thing, and she is **not** sitting through six paragraphs of agent confetti to find out whether the test passed.
+
+Grandma does not dumb it down. She keeps every fact that matters. She just refuses to waste your afternoon.
+
+`grandma` takes verbose LLM output and distils it to three lines: **what happened**, **the bottom line**, and **what to do next**.
+
+---
+
+## 💸 Token savings
+
+Every time you read a raw LLM response, you pay in attention — or in tokens if you pipe it into another model.
+
+| | Words | Reading tokens | Cost to re-read |
+|---|---|---|---|
+| Raw LLM response | ~400 | ~530 | 100% |
+| **grandma card** | **~40** | **~55** | **~10%** |
+| **Savings** | | | **~90% fewer tokens** |
+
+**Why this matters:**
+
+- In agent loops, every intermediate response fed back into context costs tokens. Grandma compresses the signal.
+- In multi-step workflows (plan → code → review → deploy), each step can save 400–500 tokens of context bloat.
+- Deep mode trades a bit more output for full structured data — still 70–80% smaller than the raw response.
+- Across a 20-turn session, grandma typically saves **8,000–12,000 context tokens**.
+
+---
+
+## Before / After
+
+**Raw LLM output (~90 words, ~120 tokens):**
+
+```text
+I inspected the repository and found that the authentication flow now routes through
+the new async session adapter. I updated three files, added one regression test, and
+confirmed that the login path still returns the expected token shape. There is one
+compatibility consideration: the adapter relies on Python 3.9+ typing behavior, so
+Python 3.8 users will need to upgrade or pin the old release. Overall, this should
+reduce request latency, but the deployment notes should mention the runtime floor.
+```
+
+**After grandma (default mode — ~30 words, ~40 tokens):**
+
+```
+👵 grandma
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📖 Second turn reviewing an auth refactor PR.
+
+What happened: Auth moved to the async session adapter.
+Bottom line:   Faster login path, but Python 3.8 is out.
+Do next:       Document Python ≥3.9 before shipping.
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+**After grandma (deep mode — full impact table):**
+
+```
+👵 grandma
+┌──────────────┬──────────────────────────────────────────────┐
+│ 📖 story arc │ Second turn reviewing an auth refactor PR.   │
+│ 👀 happened  │ Auth moved to async session adapter.         │
+│ 🧶 changed   │ 3 files, 1 regression test added.            │
+│ ✅ positive  │ Login latency reduced; token shape unchanged. │
+│ ⚠️  negative  │ Breaks Python 3.8 (asyncio.TaskGroup).       │
+│ ➖ neutral   │ API surface unchanged.                        │
+│ 💡 net gain  │ Win — ship it with a runtime floor note.     │
+│ 📋 actions   │ - Add Python ≥3.9 to pyproject.toml          │
+│              │ - Update deployment docs                      │
+└──────────────┴──────────────────────────────────────────────┘
+```
+
+---
+
+## Install
+
+```bash
+pip install grandma
+# or
+pipx install grandma
+# or from source
+pip install git+https://github.com/ypollak2/grandma.git
+```
+
+---
+
+## Usage
+
+**Pipe any text through grandma:**
+
+```bash
+echo "long agent output..." | grandma
+cat response.txt | grandma --mode deep
+cat response.txt | grandma --json        # raw JSON verdict
+cat response.txt | grandma --mode off    # passthrough
+```
+
+**Demo (no API key needed):**
+
+```bash
+grandma --demo
+grandma --demo --mode deep
+```
+
+**Environment variable for default mode:**
+
+```bash
+export GRANDMA_MODE=deep
+```
+
+---
+
+## The Modes
+
+| Mode | What you get | Model used | Best for |
+|---|---|---|---|
+| `default` | 3-line card: happened / bottom line / do next | Haiku | Most agent output |
+| `deep` | Full impact table with positive/negative/neutral | Sonnet | PRs, arch decisions, refactors |
+| `off` | Passthrough — original text unchanged | — | When you need the whole casserole |
+
+---
+
+## Works without an API key
+
+Grandma runs on your **Claude Code subscription** — no `ANTHROPIC_API_KEY` needed:
+
+```
+grandma → claude -p - (stdin pipe) → your Claude Code OAuth session
+```
+
+Set `ANTHROPIC_API_KEY` only if you want to use your own API credits instead.
+
+---
+
+## IDE & agent integrations
+
+Grandma works anywhere LLMs produce text. One-liner install for all detected tools:
+
+```bash
+./install.sh
+```
+
+| Tool | Integration type | What happens |
+|---|---|---|
+| **Claude Code** | Stop hook (native) | Auto-card after every long response |
+| **Codex CLI** | Stop hook (native) | Auto-card after every long response |
+| **Gemini CLI** | AfterAgent hook (native) | Auto-card after every agent turn |
+| **Cursor** | MCP + `.cursor/rules` | Agent calls `grandma_summarize` after long replies |
+| **Cline** | MCP + rules | Agent calls `grandma_summarize` after tasks |
+| **Continue** | MCP + `/grandma` slash command | On demand or automatic |
+| **Windsurf** | MCP + `.windsurfrules` | Agent calls `grandma_summarize` after long replies |
+| **Zed** | MCP (`context_servers`) | Tool available in Zed AI panel |
+| **Goose** | MCP extension | Tool available in Goose sessions |
+| **Aider** | `grandma-aider` wrapper | Pipe aider output through grandma |
+| **OpenHands** | `grandma-openhands` wrapper | Pipe headless output through grandma |
+
+**MCP server (for any MCP-capable IDE):**
+
+```bash
+grandma serve
+```
+
+Exposes two tools:
+- `grandma_summarize(text, mode, story_context)` → plain-text card
+- `grandma_summarize_json(text, mode, story_context)` → structured dict
+
+Add to any `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "grandma": { "command": "grandma", "args": ["serve"] }
+  }
+}
+```
+
+---
+
+## How the mascot rotates
+
+Each grandma portrait in this repo (`assets/grandmas/`) was generated with Gemini Image.  
+A [daily GitHub Action](.github/workflows/rotate-grandma.yml) picks one at random and replaces `assets/grandma.png`.  
+The README always shows the current winner. No JS. No CDN. No infrastructure.
+
+Want to add your own grandma? Drop a PNG into `assets/grandmas/` and open a PR.
+
+---
+
+## FAQ
+
+**Does grandma make it dumber?**  
+No dear. She keeps the facts. She removes the fog machine.
+
+**Does default mode include everything?**  
+It includes what you need first. Use `--mode deep` when you need the full table.
+
+**Why is there an off mode?**  
+Because sometimes you want the original, and grandma knows when to leave a person alone.
+
+**What's the `story_so_far` line?**  
+Grandma reads the last 3 turns of the conversation to understand where you are in the arc.  
+If you are on turn 8 of debugging the same auth bug, she will tell you. This is the dementia prevention feature.
+
+**Which models does it use?**  
+Default mode: `claude-haiku-4-5-20251001`. Deep mode: `claude-sonnet-4-6`.  
+Both run on your Claude Code subscription — no extra key needed.
+
+---
+
+<div align="center">
+<sub>Made with 💜 by <a href="https://github.com/ypollak2">Yali Pollak</a> · MIT License</sub>
+</div>