drupaltools-tip-generator 0.1.0__tar.gz

drupaltools_tip_generator-0.1.0/.env.example

@@ -0,0 +1,22 @@
+# Copy this file to .env and fill in your API keys
+# The tip generator will automatically load these values
+# All variables use TIPGEN_ prefix to avoid overriding global environment variables
+
+# Anthropic API (for claude models). See models at https://docs.anthropic.com/en/docs/about-claude/models/overview
+TIPGEN_ANTHROPIC_API_KEY=your_anthropic_key_here
+TIPGEN_ANTHROPIC_MODEL=claude-haiku-4-5
+# Optional: Custom API URL for Anthropic-compatible endpoints (e.g., local LLM servers)
+# TIPGEN_ANTHROPIC_API_URL=https://api.anthropic.com
+
+# OpenAI API (for gpt models). See models at https://platform.openai.com/docs/models
+TIPGEN_OPENAI_API_KEY=your_openai_key_here
+TIPGEN_OPENAI_MODEL=gpt-5.4-mini
+# Optional: Custom API URL for OpenAI-compatible endpoints (e.g., local LLM servers, Ollama, vLLM)
+# TIPGEN_OPENAI_API_URL=https://api.openai.com/v1
+
+# OpenRouter API (access to many models). See https://openrouter.ai/models
+TIPGEN_OPENROUTER_API_KEY=your_openrouter_key_here
+TIPGEN_OPENROUTER_MODEL=openai/gpt-5.1-codex-mini
+
+# Optional: Custom tips directory (default: tips/ folder in package)
+# TIPGEN_TIPS_DIR=/path/to/custom/tips

drupaltools_tip_generator-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,29 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install build dependencies
+        run: pip install --upgrade build twine
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+        run: twine upload dist/*

drupaltools_tip_generator-0.1.0/.gitignore

@@ -0,0 +1,30 @@
+# Environment variables (contains API keys)
+.env
+
+# Error log
+errors.json
+
+# Generated tips (can be regenerated)
+tips/
+
+# Cached remote data (URL fetches)
+cache-data/
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+.venv/
+venv/
+ENV/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Build artifacts
+dist/
+build/
+*.egg-info/

drupaltools_tip_generator-0.1.0/LICENSE

@@ -0,0 +1,20 @@
+GNU GENERAL PUBLIC LICENSE
+Version 2, June 1991
+
+Copyright (C) 2026 Drupal Tools
+
+This program is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 2 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License along
+with this program; if not, write to the Free Software Foundation, Inc.,
+51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
+Full license text: https://www.gnu.org/licenses/old-licenses/gpl-2.0.html

drupaltools_tip_generator-0.1.0/PKG-INFO

@@ -0,0 +1,253 @@
+Metadata-Version: 2.4
+Name: drupaltools-tip-generator
+Version: 0.1.0
+Summary: Generate static MD tip files for Drupal development tips using various LLM providers
+Author-email: Drupal Tools Team <info@drupaltools.com>
+License-Expression: GPL-2.0-or-later
+Project-URL: Homepage, https://github.com/drupaltools/tip-generator
+Project-URL: Repository, https://github.com/drupaltools/tip-generator.git
+Project-URL: Issues, https://github.com/drupaltools/tip-generator/issues
+Keywords: drupal,tips,llm,generator,ai,cli
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: anthropic>=0.18.0
+Requires-Dist: openai>=1.0.0
+Dynamic: license-file
+
+# Drupal Tip Generator
+
+Generate static MD tip files for the `drupal-tip` skill using various LLM providers.
+
+## Setup
+
+### 1. Create Virtual Environment
+
+```bash
+cd ~/.claude/skills/drupal-tip
+python3 -m venv .venv
+source .venv/bin/activate
+pip install openai anthropic
+```
+
+### 2. Configure API Keys
+
+Copy the example environment file and add your keys:
+
+```bash
+cp .env.example .env
+```
+
+Edit `.env` with your API keys (use `TIPGEN_` prefix):
+
+```env
+TIPGEN_ANTHROPIC_API_KEY=sk-ant-...
+TIPGEN_OPENAI_API_KEY=sk-...
+TIPGEN_OPENROUTER_API_KEY=sk-or-...
+```
+
+## Usage
+
+### Get a Random Existing Tip (FAST!)
+
+Get a tip from the pre-generated database instantly — no API call needed:
+
+```bash
+.venv/bin/python tip_generator.py --random-tip
+.venv/bin/python tip_generator.py --random-tip --tip-category core-service
+.venv/bin/python tip_generator.py --list-existing
+```
+
+### List Available Categories
+
+```bash
+.venv/bin/python tip_generator.py --list-categories
+```
+
+### Generate Tips
+
+**Using Anthropic:**
+```bash
+.venv/bin/python tip_generator.py -c 35 -n 5 -p anthropic
+```
+
+**Using OpenAI (batch mode - 50% cheaper):**
+```bash
+.venv/bin/python tip_generator.py -c 35 -n 5 -p openai
+```
+
+**Using OpenRouter:**
+```bash
+.venv/bin/python tip_generator.py -c 35 -n 5 -p openrouter
+```
+
+### Arguments
+
+| Argument | Description |
+|----------|-------------|
+| `-c, --category` | Category number(s) or `all` |
+| `-n, --count` | Number of tips per category (default: 5) |
+| `-p, --provider` | LLM provider: `anthropic`, `openai`, `openrouter` |
+| `-m, --model` | Override default model |
+| `-u, --api-url` | Custom API URL for OpenAI/Anthropic-compatible endpoints |
+| `-t, --max-tokens` | Maximum tokens for response (default: 4096) |
+| `--tips-dir` | Custom tips directory (or set `TIPGEN_TIPS_DIR` env var or `tips_dir` in config.json) |
+| `--save-truncated` | Save tips even if truncated (use with caution) |
+| `--no-wait` | Don't wait for batch completion |
+| `--dry-run` | Show what would be done without calling API |
+| `--list-categories` | List all available categories |
+| `--random-tip` | Get a random existing tip (fast, no API) |
+| `--list-existing` | List categories with existing tips |
+| `--tip-category` | Filter random tip by category name |
+| `--validate` | Enable validation mode |
+| `--validate-file` | Validate a specific tip file |
+| `--validate-category` | Validate all tips in a category |
+| `--validate-all` | Validate all tips across all categories |
+
+### Examples
+
+```bash
+# Generate 3 tips for category 35 (core-service)
+.venv/bin/python tip_generator.py -c 35 -n 3 -p openrouter
+
+# Generate 5 tips for multiple categories
+.venv/bin/python tip_generator.py -c 35,36,37 -n 5 -p openrouter
+
+# Generate 1 tip for ALL categories
+.venv/bin/python tip_generator.py -c all -n 1 -p openrouter
+
+# Use a specific model
+.venv/bin/python tip_generator.py -c 35 -n 5 -p openrouter -m anthropic/claude-opus-4
+
+# Use a custom API URL (e.g., Together.xyz, local LLM server)
+.venv/bin/python tip_generator.py -c 35 -n 5 -p openai -u https://api.together.xyz/v1
+
+# Increase max tokens for longer responses (avoid truncation)
+.venv/bin/python tip_generator.py -c 60 -n 20 -p openai --max-tokens 8192
+
+# Save tips even if truncated (use with caution)
+.venv/bin/python tip_generator.py -c 35 -n 5 -p openai --save-truncated
+```
+
+## Batch API Notes
+
+| Provider | Batch Support | Discount | Notes |
+|----------|---------------|----------|-------|
+| Anthropic | Yes | 50% | Uses `message-batches-2024-09-24` beta |
+| OpenAI | Yes | 50% | Results within 24h |
+| OpenRouter | ⚠️ Sync only | - | Batch API not supported |
+
+## Check Batch Status
+
+If you ran batch mode with `--no-wait`:
+
+```bash
+.venv/bin/python tip_generator.py --check-batch BATCH_ID -p anthropic
+.venv/bin/python tip_generator.py --check-batch BATCH_ID -p openai --save-results
+```
+
+## Output
+
+Tips are saved to `tips/{category-name}/{uuid}.md` with 8-character random IDs:
+
+```
+tips/
+├── core-service/
+│   ├── a1b2c3d4.md
+│   └── e5f6g7h8.md
+└── rare-drush-command/
+    └── 9i0j1k2l.md
+```
+
+Each file has frontmatter:
+
+```markdown
+---
+category: core-service
+title: [Generated title]
+---
+
+[Tip content]
+```
+
+## Configuration
+
+Categories and the prompt template are defined in `config.json`:
+
+```json
+{
+  "prompt_template": "Generate a Drupal tip for category #{cat_id}: {cat_desc}...",
+  "code_language": "php",
+  "tips_dir": "/path/to/custom/tips",
+  "categories": {
+    "1": {"name": "proposed-new-module", "desc": "Proposed new module"},
+    "35": {"name": "core-service", "desc": "Lesser-known core service"}
+  }
+}
+```
+
+### Tips Directory Configuration
+
+The tips directory can be configured via (in priority order):
+
+1. **CLI argument**: `--tips-dir /path/to/tips`
+2. **Environment variable**: `TIPGEN_TIPS_DIR=/path/to/tips`
+3. **Config file**: `"tips_dir": "/path/to/tips"` in `config.json`
+4. **Default**: `tips/` folder in the package directory
+
+To add or modify categories, edit `config.json` directly - no code changes needed.
+
+## Development
+
+### Running Tests
+
+```bash
+# Dry run to verify configuration
+.venv/bin/python tip_generator.py -c 35 -n 1 -p openrouter --dry-run
+```
+
+## Validation
+
+Validate generated tips for formatting issues, truncation, and quality:
+
+```bash
+# Validate a single file
+.venv/bin/python tip_generator.py --validate --validate-file tips/core-service/a1b2c3d4.md
+
+# Validate all tips in a category
+.venv/bin/python tip_generator.py --validate --validate-category core-service
+
+# Validate ALL tips across all categories
+.venv/bin/python tip_generator.py --validate --validate-all
+```
+
+### Validation Checks
+
+- **Formatting**: Frontmatter structure, code block balance, line counts
+- **Completeness**: Truncation patterns (trailing `...`, `[TODO]`, incomplete code blocks)
+- **Quality**: Generic openings, placeholder text, excessive code ratio
+- **Fake Content**: Non-existent Drupal APIs, hallucinated functions, wrong service names
+
+## Web Viewer
+
+A simple web UI to browse tips:
+
+```bash
+pip install flask
+python tip_viewer.py                    # http://localhost:5000
+python tip_viewer.py --port 8080        # Custom port
+python tip_viewer.py --host 0.0.0.0     # Public access
+python tip_viewer.py --debug            # Debug mode
+```
+
+Features:
+- Filter tips by category
+- Get random tip with one click
+- View all tips or browse by category

drupaltools_tip_generator-0.1.0/PUBLISH.md

@@ -0,0 +1,105 @@
+# Publishing tip-generator to PyPI
+
+## Prerequisites
+
+- Python 3.11+
+- PyPI account with API token
+- Git repository with push access
+
+## Setup
+
+### 1. Install build tools
+
+```bash
+pip install --upgrade build twine
+```
+
+### 2. Configure PyPI credentials
+
+Create `~/.pypirc`:
+
+```ini
+[pypi]
+username = __token__
+password = pypi-...
+```
+
+Or use environment variable:
+
+```bash
+export TWINE_USERNAME=__token__
+export TWINE_PASSWORD=pypi-...
+```
+
+## Build
+
+```bash
+# Clean previous builds
+rm -rf dist/ build/ src/*.egg-info
+
+# Build package
+python -m build
+```
+
+Output:
+- `dist/tip_generator-X.X.X-py3-none-any.whl`
+- `dist/tip_generator-X.X.X.tar.gz`
+
+## Publish
+
+### Manual publish
+
+```bash
+# Check package before upload
+twine check dist/*
+
+# Upload to PyPI
+twine upload dist/*
+```
+
+### Automated publish via GitHub Actions
+
+The workflow `.github/workflows/publish.yml` automatically publishes on tag push:
+
+```bash
+# Update version in pyproject.toml first
+# Then create and push tag
+git tag v0.1.0
+git push origin v0.1.0
+```
+
+## Version Bumping
+
+1. Update `version` in `pyproject.toml`
+2. Update `__version__` in `src/tip_generator/__init__.py`
+3. Commit changes
+4. Create tag matching version
+
+```bash
+# Example: bump to 0.2.0
+sed -i 's/version = "0.1.0"/version = "0.2.0"/' pyproject.toml
+sed -i 's/__version__ = "0.1.0"/__version__ = "0.2.0"/' src/tip_generator/__init__.py
+git commit -am "Bump version to 0.2.0"
+git tag v0.2.0
+git push origin master --tags
+```
+
+## Test Publishing (TestPyPI)
+
+```bash
+# Build
+python -m build
+
+# Upload to TestPyPI first
+twine upload --repository testpypi dist/*
+
+# Test install
+pip install --index-url https://test.pypi.org/simple/ tip-generator
+```
+
+## Verify Installation
+
+```bash
+pip install tip-generator
+drupal-tip-generator --help
+```

drupaltools_tip_generator-0.1.0/README.md

@@ -0,0 +1,229 @@
+# Drupal Tip Generator
+
+Generate static MD tip files for the `drupal-tip` skill using various LLM providers.
+
+## Setup
+
+### 1. Create Virtual Environment
+
+```bash
+cd ~/.claude/skills/drupal-tip
+python3 -m venv .venv
+source .venv/bin/activate
+pip install openai anthropic
+```
+
+### 2. Configure API Keys
+
+Copy the example environment file and add your keys:
+
+```bash
+cp .env.example .env
+```
+
+Edit `.env` with your API keys (use `TIPGEN_` prefix):
+
+```env
+TIPGEN_ANTHROPIC_API_KEY=sk-ant-...
+TIPGEN_OPENAI_API_KEY=sk-...
+TIPGEN_OPENROUTER_API_KEY=sk-or-...
+```
+
+## Usage
+
+### Get a Random Existing Tip (FAST!)
+
+Get a tip from the pre-generated database instantly — no API call needed:
+
+```bash
+.venv/bin/python tip_generator.py --random-tip
+.venv/bin/python tip_generator.py --random-tip --tip-category core-service
+.venv/bin/python tip_generator.py --list-existing
+```
+
+### List Available Categories
+
+```bash
+.venv/bin/python tip_generator.py --list-categories
+```
+
+### Generate Tips
+
+**Using Anthropic:**
+```bash
+.venv/bin/python tip_generator.py -c 35 -n 5 -p anthropic
+```
+
+**Using OpenAI (batch mode - 50% cheaper):**
+```bash
+.venv/bin/python tip_generator.py -c 35 -n 5 -p openai
+```
+
+**Using OpenRouter:**
+```bash
+.venv/bin/python tip_generator.py -c 35 -n 5 -p openrouter
+```
+
+### Arguments
+
+| Argument | Description |
+|----------|-------------|
+| `-c, --category` | Category number(s) or `all` |
+| `-n, --count` | Number of tips per category (default: 5) |
+| `-p, --provider` | LLM provider: `anthropic`, `openai`, `openrouter` |
+| `-m, --model` | Override default model |
+| `-u, --api-url` | Custom API URL for OpenAI/Anthropic-compatible endpoints |
+| `-t, --max-tokens` | Maximum tokens for response (default: 4096) |
+| `--tips-dir` | Custom tips directory (or set `TIPGEN_TIPS_DIR` env var or `tips_dir` in config.json) |
+| `--save-truncated` | Save tips even if truncated (use with caution) |
+| `--no-wait` | Don't wait for batch completion |
+| `--dry-run` | Show what would be done without calling API |
+| `--list-categories` | List all available categories |
+| `--random-tip` | Get a random existing tip (fast, no API) |
+| `--list-existing` | List categories with existing tips |
+| `--tip-category` | Filter random tip by category name |
+| `--validate` | Enable validation mode |
+| `--validate-file` | Validate a specific tip file |
+| `--validate-category` | Validate all tips in a category |
+| `--validate-all` | Validate all tips across all categories |
+
+### Examples
+
+```bash
+# Generate 3 tips for category 35 (core-service)
+.venv/bin/python tip_generator.py -c 35 -n 3 -p openrouter
+
+# Generate 5 tips for multiple categories
+.venv/bin/python tip_generator.py -c 35,36,37 -n 5 -p openrouter
+
+# Generate 1 tip for ALL categories
+.venv/bin/python tip_generator.py -c all -n 1 -p openrouter
+
+# Use a specific model
+.venv/bin/python tip_generator.py -c 35 -n 5 -p openrouter -m anthropic/claude-opus-4
+
+# Use a custom API URL (e.g., Together.xyz, local LLM server)
+.venv/bin/python tip_generator.py -c 35 -n 5 -p openai -u https://api.together.xyz/v1
+
+# Increase max tokens for longer responses (avoid truncation)
+.venv/bin/python tip_generator.py -c 60 -n 20 -p openai --max-tokens 8192
+
+# Save tips even if truncated (use with caution)
+.venv/bin/python tip_generator.py -c 35 -n 5 -p openai --save-truncated
+```
+
+## Batch API Notes
+
+| Provider | Batch Support | Discount | Notes |
+|----------|---------------|----------|-------|
+| Anthropic | Yes | 50% | Uses `message-batches-2024-09-24` beta |
+| OpenAI | Yes | 50% | Results within 24h |
+| OpenRouter | ⚠️ Sync only | - | Batch API not supported |
+
+## Check Batch Status
+
+If you ran batch mode with `--no-wait`:
+
+```bash
+.venv/bin/python tip_generator.py --check-batch BATCH_ID -p anthropic
+.venv/bin/python tip_generator.py --check-batch BATCH_ID -p openai --save-results
+```
+
+## Output
+
+Tips are saved to `tips/{category-name}/{uuid}.md` with 8-character random IDs:
+
+```
+tips/
+├── core-service/
+│   ├── a1b2c3d4.md
+│   └── e5f6g7h8.md
+└── rare-drush-command/
+    └── 9i0j1k2l.md
+```
+
+Each file has frontmatter:
+
+```markdown
+---
+category: core-service
+title: [Generated title]
+---
+
+[Tip content]
+```
+
+## Configuration
+
+Categories and the prompt template are defined in `config.json`:
+
+```json
+{
+  "prompt_template": "Generate a Drupal tip for category #{cat_id}: {cat_desc}...",
+  "code_language": "php",
+  "tips_dir": "/path/to/custom/tips",
+  "categories": {
+    "1": {"name": "proposed-new-module", "desc": "Proposed new module"},
+    "35": {"name": "core-service", "desc": "Lesser-known core service"}
+  }
+}
+```
+
+### Tips Directory Configuration
+
+The tips directory can be configured via (in priority order):
+
+1. **CLI argument**: `--tips-dir /path/to/tips`
+2. **Environment variable**: `TIPGEN_TIPS_DIR=/path/to/tips`
+3. **Config file**: `"tips_dir": "/path/to/tips"` in `config.json`
+4. **Default**: `tips/` folder in the package directory
+
+To add or modify categories, edit `config.json` directly - no code changes needed.
+
+## Development
+
+### Running Tests
+
+```bash
+# Dry run to verify configuration
+.venv/bin/python tip_generator.py -c 35 -n 1 -p openrouter --dry-run
+```
+
+## Validation
+
+Validate generated tips for formatting issues, truncation, and quality:
+
+```bash
+# Validate a single file
+.venv/bin/python tip_generator.py --validate --validate-file tips/core-service/a1b2c3d4.md
+
+# Validate all tips in a category
+.venv/bin/python tip_generator.py --validate --validate-category core-service
+
+# Validate ALL tips across all categories
+.venv/bin/python tip_generator.py --validate --validate-all
+```
+
+### Validation Checks
+
+- **Formatting**: Frontmatter structure, code block balance, line counts
+- **Completeness**: Truncation patterns (trailing `...`, `[TODO]`, incomplete code blocks)
+- **Quality**: Generic openings, placeholder text, excessive code ratio
+- **Fake Content**: Non-existent Drupal APIs, hallucinated functions, wrong service names
+
+## Web Viewer
+
+A simple web UI to browse tips:
+
+```bash
+pip install flask
+python tip_viewer.py                    # http://localhost:5000
+python tip_viewer.py --port 8080        # Custom port
+python tip_viewer.py --host 0.0.0.0     # Public access
+python tip_viewer.py --debug            # Debug mode
+```
+
+Features:
+- Filter tips by category
+- Get random tip with one click
+- View all tips or browse by category