cli-dev-tip 0.1.0__tar.gz

cli_dev_tip-0.1.0/.gitignore

@@ -0,0 +1,58 @@
+# Claude Code
+.claude
+
+# VS Code
+.vscode/
+*.code-workspace
+
+# ChatGPT / OpenAI
+.chatgpt/
+.openai/
+
+# GitHub Copilot
+.copilot/
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# Environment & secrets
+.env
+.env.*
+!.env.example
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+*.egg
+.venv/
+venv/
+.python-version
+
+# Node
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# IDE / Editor
+*.swp
+*.swo
+*~
+.idea/
+*.iml
+
+# Logs
+*.log
+
+# Coverage & testing
+.coverage
+htmlcov/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/

cli_dev_tip-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 My-CD-ROM
+
+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.

cli_dev_tip-0.1.0/PKG-INFO

@@ -0,0 +1,223 @@
+Metadata-Version: 2.4
+Name: cli-dev-tip
+Version: 0.1.0
+Summary: Bite-sized developer tips in your terminal
+Project-URL: Homepage, https://github.com/My-CD-ROM/cli-dev-tip
+Project-URL: Repository, https://github.com/My-CD-ROM/cli-dev-tip
+Project-URL: Issues, https://github.com/My-CD-ROM/cli-dev-tip/issues
+Author: My-CD-ROM
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cli,developer,learning,terminal,tips
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT 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 :: Software Development
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: pyyaml
+Requires-Dist: rich
+Requires-Dist: typer
+Description-Content-Type: text/markdown
+
+# dev-tip
+
+A terminal tool that helps developers learn continuously by showing bite-sized technical tips — right in the terminal, between commands.
+
+## What it does
+
+- Shows tips periodically during your shell session (every N commands or M minutes)
+- First tip appears immediately when you open a terminal
+- Covers general IT topics by default — Python, Git, Docker, Linux, Kubernetes, and more
+- Filters by topic or difficulty level
+- Remembers what you've seen so you don't get repeats
+- Optional AI-powered tip generation via Gemini or OpenRouter (free, no extra packages needed)
+- Zero prompt latency — all periodic logic runs as pure shell code, Python only invoked when showing a tip
+- Pause/resume tips without removing the hook
+
+## Installation
+
+```bash
+uv tool install cli-dev-tip
+```
+
+This makes `dev-tip` available globally from any terminal. No extra packages needed.
+
+## Quick start
+
+The recommended setup — AI-generated tips covering general IT topics, appearing every 15 commands or 30 minutes:
+
+```bash
+dev-tip enable --provider gemini --key YOUR_GEMINI_API_KEY
+```
+
+Get a free Gemini API key at https://aistudio.google.com or a free OpenRouter key at https://openrouter.ai/keys.
+
+More examples:
+
+```bash
+# Static tips only (125 built in, works offline)
+dev-tip enable
+
+# AI tips, focused on Python, advanced level
+dev-tip enable --provider gemini --key YOUR_KEY --topic python --level advanced
+
+# Show tips more frequently — every 5 commands or every 10 minutes
+dev-tip enable --provider gemini --key YOUR_KEY --every-commands 5 --every-minutes 10
+
+# Quiet mode — body only, no header/emoji
+dev-tip enable --quiet
+
+# Disable
+dev-tip disable
+```
+
+### `enable` options
+
+| Option | Short | Description | Default |
+|---|---|---|---|
+| `--provider` | `-p` | AI provider (gemini, openrouter) | None (static tips) |
+| `--key` | `-k` | API key for the AI provider | Config or env var |
+| `--topic` | `-t` | Filter tips by topic | General IT topics |
+| `--level` | `-l` | Filter tips by difficulty | All levels |
+| `--every-commands` | | Show a tip every N commands | 15 |
+| `--every-minutes` | | Show a tip every N minutes | 30 |
+| `--quiet` | `-q` | Show tip body only, no header | false |
+
+Tips appear when either threshold is reached — whichever comes first. The first tip always shows immediately on shell startup.
+
+## Usage
+
+One-off tips from the command line:
+
+```bash
+# Show a random tip (general IT topics, all levels)
+dev-tip
+
+# Filter by topic
+dev-tip --topic python
+dev-tip -t git
+
+# Filter by difficulty level
+dev-tip --level beginner
+dev-tip -l advanced
+
+# Combine filters
+dev-tip --topic docker --level intermediate
+
+# Quiet mode — body only, no header
+dev-tip --quiet
+
+# Use AI provider for a one-off tip
+dev-tip --provider gemini --key YOUR_KEY
+```
+
+### One-off options
+
+| Option | Short | Description | Default |
+|---|---|---|---|
+| `--topic` | `-t` | Filter tips by topic | General IT topics |
+| `--level` | `-l` | Filter tips by difficulty | All levels |
+| `--provider` | `-p` | AI provider (gemini, openrouter) | None |
+| `--key` | `-k` | API key for the AI provider | Config or env var |
+| `--quiet` | `-q` | Show tip body only, no header | false |
+
+Unknown topics produce a warning when using static tips (AI can handle any topic). Unknown levels always warn.
+
+### Available topics
+
+| Topic | Count |
+|---|---|
+| `python` | 15 |
+| `git` | 15 |
+| `docker` | 15 |
+| `sql` | 15 |
+| `linux` | 15 |
+| `kubernetes` | 10 |
+| `vim` | 10 |
+| `javascript` | 10 |
+| `terraform` | 10 |
+| `rust` | 10 |
+
+125 tips built in. With AI enabled, any topic works and tips are generated fresh.
+
+### Difficulty levels
+
+| Level | Description |
+|---|---|
+| `beginner` | Fundamentals and common patterns |
+| `intermediate` | Deeper concepts and useful tricks |
+| `advanced` | Expert techniques and edge cases |
+
+## Commands
+
+### `dev-tip pause` / `dev-tip resume`
+
+Temporarily stop tips without removing the hook:
+
+```bash
+dev-tip pause    # stops tips, hook stays installed
+dev-tip resume   # starts tips again
+```
+
+This creates/removes a `.paused` file in `~/.dev-tip/`. The shell hook checks for it with a fast `[ -f ]` test — no Python invoked when paused.
+
+### `dev-tip status`
+
+Show current configuration and diagnostics:
+
+```bash
+dev-tip status
+```
+
+Displays hook state, pause status, config values, AI provider info, cache stats, and tip history count.
+
+### `dev-tip clear-cache`
+
+Clear cached AI tips to force fresh generation:
+
+```bash
+dev-tip clear-cache
+```
+
+## AI-powered tips
+
+Generate fresh tips dynamically instead of using the built-in collection. Both providers are free.
+
+| Provider | Default model | Free key |
+|---|---|---|
+| `gemini` | `gemini-2.0-flash` | https://aistudio.google.com |
+| `openrouter` | `google/gemini-2.0-flash-exp:free` | https://openrouter.ai/keys |
+
+### How it works
+
+- Generates 10 tips per API call and caches them locally (`~/.dev-tip/ai_cache.json`)
+- Cache never expires — use `dev-tip clear-cache` to force refresh
+- Cache is keyed by topic+level combination
+- Falls back to static tips silently on any error (bad key, network failure, rate limit)
+
+## Configuration
+
+Settings are stored in `~/.dev-tip/config.toml`:
+
+```toml
+# topic = "python"
+# level = "beginner"
+# ai_provider = "gemini"
+# ai_model = "gemini-2.0-flash"
+# every_commands = 15
+# every_minutes = 30
+# quiet = false
+```
+
+Values passed via `dev-tip enable` flags are saved here automatically. Comments in the config file are preserved when values are updated.
+
+## Status
+
+Early development — not yet published to PyPI.

cli_dev_tip-0.1.0/README.md

@@ -0,0 +1,195 @@
+# dev-tip
+
+A terminal tool that helps developers learn continuously by showing bite-sized technical tips — right in the terminal, between commands.
+
+## What it does
+
+- Shows tips periodically during your shell session (every N commands or M minutes)
+- First tip appears immediately when you open a terminal
+- Covers general IT topics by default — Python, Git, Docker, Linux, Kubernetes, and more
+- Filters by topic or difficulty level
+- Remembers what you've seen so you don't get repeats
+- Optional AI-powered tip generation via Gemini or OpenRouter (free, no extra packages needed)
+- Zero prompt latency — all periodic logic runs as pure shell code, Python only invoked when showing a tip
+- Pause/resume tips without removing the hook
+
+## Installation
+
+```bash
+uv tool install cli-dev-tip
+```
+
+This makes `dev-tip` available globally from any terminal. No extra packages needed.
+
+## Quick start
+
+The recommended setup — AI-generated tips covering general IT topics, appearing every 15 commands or 30 minutes:
+
+```bash
+dev-tip enable --provider gemini --key YOUR_GEMINI_API_KEY
+```
+
+Get a free Gemini API key at https://aistudio.google.com or a free OpenRouter key at https://openrouter.ai/keys.
+
+More examples:
+
+```bash
+# Static tips only (125 built in, works offline)
+dev-tip enable
+
+# AI tips, focused on Python, advanced level
+dev-tip enable --provider gemini --key YOUR_KEY --topic python --level advanced
+
+# Show tips more frequently — every 5 commands or every 10 minutes
+dev-tip enable --provider gemini --key YOUR_KEY --every-commands 5 --every-minutes 10
+
+# Quiet mode — body only, no header/emoji
+dev-tip enable --quiet
+
+# Disable
+dev-tip disable
+```
+
+### `enable` options
+
+| Option | Short | Description | Default |
+|---|---|---|---|
+| `--provider` | `-p` | AI provider (gemini, openrouter) | None (static tips) |
+| `--key` | `-k` | API key for the AI provider | Config or env var |
+| `--topic` | `-t` | Filter tips by topic | General IT topics |
+| `--level` | `-l` | Filter tips by difficulty | All levels |
+| `--every-commands` | | Show a tip every N commands | 15 |
+| `--every-minutes` | | Show a tip every N minutes | 30 |
+| `--quiet` | `-q` | Show tip body only, no header | false |
+
+Tips appear when either threshold is reached — whichever comes first. The first tip always shows immediately on shell startup.
+
+## Usage
+
+One-off tips from the command line:
+
+```bash
+# Show a random tip (general IT topics, all levels)
+dev-tip
+
+# Filter by topic
+dev-tip --topic python
+dev-tip -t git
+
+# Filter by difficulty level
+dev-tip --level beginner
+dev-tip -l advanced
+
+# Combine filters
+dev-tip --topic docker --level intermediate
+
+# Quiet mode — body only, no header
+dev-tip --quiet
+
+# Use AI provider for a one-off tip
+dev-tip --provider gemini --key YOUR_KEY
+```
+
+### One-off options
+
+| Option | Short | Description | Default |
+|---|---|---|---|
+| `--topic` | `-t` | Filter tips by topic | General IT topics |
+| `--level` | `-l` | Filter tips by difficulty | All levels |
+| `--provider` | `-p` | AI provider (gemini, openrouter) | None |
+| `--key` | `-k` | API key for the AI provider | Config or env var |
+| `--quiet` | `-q` | Show tip body only, no header | false |
+
+Unknown topics produce a warning when using static tips (AI can handle any topic). Unknown levels always warn.
+
+### Available topics
+
+| Topic | Count |
+|---|---|
+| `python` | 15 |
+| `git` | 15 |
+| `docker` | 15 |
+| `sql` | 15 |
+| `linux` | 15 |
+| `kubernetes` | 10 |
+| `vim` | 10 |
+| `javascript` | 10 |
+| `terraform` | 10 |
+| `rust` | 10 |
+
+125 tips built in. With AI enabled, any topic works and tips are generated fresh.
+
+### Difficulty levels
+
+| Level | Description |
+|---|---|
+| `beginner` | Fundamentals and common patterns |
+| `intermediate` | Deeper concepts and useful tricks |
+| `advanced` | Expert techniques and edge cases |
+
+## Commands
+
+### `dev-tip pause` / `dev-tip resume`
+
+Temporarily stop tips without removing the hook:
+
+```bash
+dev-tip pause    # stops tips, hook stays installed
+dev-tip resume   # starts tips again
+```
+
+This creates/removes a `.paused` file in `~/.dev-tip/`. The shell hook checks for it with a fast `[ -f ]` test — no Python invoked when paused.
+
+### `dev-tip status`
+
+Show current configuration and diagnostics:
+
+```bash
+dev-tip status
+```
+
+Displays hook state, pause status, config values, AI provider info, cache stats, and tip history count.
+
+### `dev-tip clear-cache`
+
+Clear cached AI tips to force fresh generation:
+
+```bash
+dev-tip clear-cache
+```
+
+## AI-powered tips
+
+Generate fresh tips dynamically instead of using the built-in collection. Both providers are free.
+
+| Provider | Default model | Free key |
+|---|---|---|
+| `gemini` | `gemini-2.0-flash` | https://aistudio.google.com |
+| `openrouter` | `google/gemini-2.0-flash-exp:free` | https://openrouter.ai/keys |
+
+### How it works
+
+- Generates 10 tips per API call and caches them locally (`~/.dev-tip/ai_cache.json`)
+- Cache never expires — use `dev-tip clear-cache` to force refresh
+- Cache is keyed by topic+level combination
+- Falls back to static tips silently on any error (bad key, network failure, rate limit)
+
+## Configuration
+
+Settings are stored in `~/.dev-tip/config.toml`:
+
+```toml
+# topic = "python"
+# level = "beginner"
+# ai_provider = "gemini"
+# ai_model = "gemini-2.0-flash"
+# every_commands = 15
+# every_minutes = 30
+# quiet = false
+```
+
+Values passed via `dev-tip enable` flags are saved here automatically. Comments in the config file are preserved when values are updated.
+
+## Status
+
+Early development — not yet published to PyPI.

cli_dev_tip-0.1.0/dev_tip/ai/__init__.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+import os
+import random
+
+from dev_tip.ai.cache import is_on_cooldown, load_cache, mark_failure, save_cache
+from dev_tip.ai.provider import create_provider
+from dev_tip.history import get_unseen
+
+_ENV_KEYS = {
+    "gemini": "GEMINI_API_KEY",
+    "openrouter": "OPENROUTER_API_KEY",
+}
+
+BATCH_SIZE = 10
+
+
+def get_ai_tip(
+    topic: str | None, level: str | None, config: dict
+) -> tuple[dict | None, int]:
+    """Return (tip, unseen_count) or (None, 0) on any failure."""
+    try:
+        provider_name = config.get("ai_provider")
+        if not provider_name:
+            return None, 0
+
+        api_key = config.get("ai_key")
+        if not api_key:
+            env_var = _ENV_KEYS.get(provider_name)
+            if env_var:
+                api_key = os.environ.get(env_var)
+        if not api_key:
+            return None, 0
+
+        # Try cache first
+        tips = load_cache(topic, level)
+
+        if not tips:
+            if is_on_cooldown():
+                return None, 0
+            try:
+                provider = create_provider(
+                    provider_name, api_key, model=config.get("ai_model")
+                )
+                tips = provider.generate_tips(topic, level, BATCH_SIZE)
+                save_cache(tips, topic, level)
+            except Exception:
+                mark_failure()
+                return None, 0
+
+        unseen = get_unseen(tips)
+        return random.choice(unseen), len(unseen)
+
+    except Exception:
+        return None, 0

cli_dev_tip-0.1.0/dev_tip/ai/cache.py

@@ -0,0 +1,114 @@
+from __future__ import annotations
+
+import json
+import time
+from pathlib import Path
+
+CACHE_DIR = Path.home() / ".dev-tip"
+CACHE_FILE = CACHE_DIR / "ai_cache.json"
+COOLDOWN_SECONDS = 5 * 60  # 5 min backoff after API failure
+
+
+def _cache_key(topic: str | None, level: str | None) -> str:
+    """Build a cache key like 'python:beginner' or 'None:None'."""
+    return f"{topic}:{level}"
+
+
+def _load_all() -> dict:
+    """Load full cache, auto-migrating v1 single-key format to v2."""
+    if not CACHE_FILE.exists():
+        return {"version": 2, "keys": {}}
+
+    data = json.loads(CACHE_FILE.read_text())
+
+    # v1 migration: old format had top-level topic/level/tips/generated_at
+    if "version" not in data and "tips" in data:
+        key = _cache_key(data.get("topic"), data.get("level"))
+        migrated = {
+            "version": 2,
+            "keys": {
+                key: {
+                    "generated_at": data.get("generated_at", 0.0),
+                    "tips": data.get("tips", []),
+                }
+            },
+        }
+        _save_all(migrated)
+        return migrated
+
+    return data
+
+
+def _save_all(data: dict) -> None:
+    """Write full cache to disk."""
+    CACHE_DIR.mkdir(parents=True, exist_ok=True)
+    CACHE_FILE.write_text(json.dumps(data, indent=2))
+
+
+def load_cache(topic: str | None, level: str | None) -> list[dict]:
+    """Return all cached tips for a topic+level combo (never expires)."""
+    data = _load_all()
+    key = _cache_key(topic, level)
+    entry = data.get("keys", {}).get(key)
+    if not entry:
+        return []
+    return entry.get("tips", [])
+
+
+def save_cache(tips: list[dict], topic: str | None, level: str | None) -> None:
+    """Merge tips into the multi-key cache structure."""
+    data = _load_all()
+    key = _cache_key(topic, level)
+    existing = data.get("keys", {}).get(key, {}).get("tips", [])
+
+    # Deduplicate by tip id
+    seen_ids = {t["id"] for t in existing}
+    merged = existing + [t for t in tips if t["id"] not in seen_ids]
+
+    data.setdefault("keys", {})[key] = {
+        "generated_at": time.time(),
+        "tips": merged,
+    }
+    data["version"] = 2
+    _save_all(data)
+
+
+def cache_needs_refill(topic: str | None, level: str | None, unseen_count: int) -> bool:
+    """Return True when unseen tips are running low and cache entry exists."""
+    if unseen_count > 3:
+        return False
+    data = _load_all()
+    key = _cache_key(topic, level)
+    return key in data.get("keys", {})
+
+
+def is_on_cooldown() -> bool:
+    """Return True if a recent API failure means we should skip retrying."""
+    data = _load_all()
+    failed_at = data.get("last_failure", 0)
+    return time.time() - failed_at < COOLDOWN_SECONDS
+
+
+def mark_failure() -> None:
+    """Record an API failure timestamp for cooldown backoff."""
+    data = _load_all()
+    data["last_failure"] = time.time()
+    _save_all(data)
+
+
+def clear_cache() -> None:
+    """Delete the AI cache file."""
+    if CACHE_FILE.exists():
+        CACHE_FILE.unlink()
+
+
+def get_cache_stats() -> dict:
+    """Return cache statistics for the status command."""
+    data = _load_all()
+    keys = data.get("keys", {})
+    total_tips = sum(len(entry.get("tips", [])) for entry in keys.values())
+    return {
+        "keys": len(keys),
+        "total_tips": total_tips,
+        "cooldown_active": is_on_cooldown(),
+    }

cli_dev_tip-0.1.0/dev_tip/ai/gemini.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+import json
+import urllib.request
+
+from dev_tip.ai.prompt import build_prompt, parse_response
+from dev_tip.ai.provider import AIProvider
+
+DEFAULT_MODEL = "gemini-2.0-flash"
+_ENDPOINT = "https://generativelanguage.googleapis.com/v1beta/models/{model}:generateContent?key={api_key}"
+
+
+class GeminiProvider(AIProvider):
+    def __init__(self, api_key: str, model: str | None = None) -> None:
+        self._api_key = api_key
+        self._model = model or DEFAULT_MODEL
+
+    def generate_tips(self, topic: str | None, level: str | None, count: int) -> list[dict]:
+        prompt = build_prompt(topic, level, count)
+        url = _ENDPOINT.format(model=self._model, api_key=self._api_key)
+        body = json.dumps({
+            "contents": [{"parts": [{"text": prompt}]}],
+        }).encode()
+        req = urllib.request.Request(url, data=body, headers={"Content-Type": "application/json"})
+        with urllib.request.urlopen(req, timeout=30) as resp:
+            data = json.loads(resp.read())
+        text = data["candidates"][0]["content"]["parts"][0]["text"]
+        return parse_response(text)