digest-generator 0.1.0__tar.gz

digest_generator-0.1.0/.env.example

@@ -0,0 +1,131 @@
+# =============================================================================
+# Digest Generator Environment Configuration
+# =============================================================================
+# Copy this file to .env and fill in the required values.
+# Only HF_TOKEN is required. Everything else has a sensible default.
+# See digest_generator/shared/settings.py for the full list of values.
+# Sampling knobs and CLI flags are documented in docs/usage.md.
+# =============================================================================
+
+# -- Required --
+HF_TOKEN=                                   # HuggingFace API token (used by the BART-MNLI classifier)
+
+# =============================================================================
+# Foundational / shared infrastructure
+# =============================================================================
+
+# -- Device --
+# DEVICE=cpu                                # cpu, cuda, or mps (used by the classifier)
+
+# -- Ollama (shared by the summarizer and every digest stage) --
+# OLLAMA_HOST=http://localhost:11434        # Local Ollama URL
+# OLLAMA_API_KEY=                           # Set to use cloud Ollama (auto-detected)
+# OLLAMA_CONCURRENCY=3                      # Global cap on in-flight Ollama calls
+# OLLAMA_READ_TIMEOUT_S=300                 # Read timeout per call (seconds)
+
+# =============================================================================
+# Pipeline stages (in execution order)
+# =============================================================================
+
+# -- Feeds source (RSS feed discovery) --
+# Feeds are defined in a feeds.yaml (see feeds.example.yaml). When neither is
+# set, the loader searches ./digest-generator/feeds.yaml then
+# ~/.config/digest-generator/feeds.yaml.
+# FEEDS_FILE=                               # Explicit path to a feeds.yaml file
+# DIGEST_CONFIG=                            # Config directory holding feeds.yaml (+ prompts/)
+# PROMPTS_DIR=                              # Directory of prompt-template overrides (<name>.md)
+
+# -- Fetcher --
+# FETCH_TIMEOUT=10                          # HTTP request timeout (seconds)
+# FETCH_RATE_LIMIT=0.4                      # Delay between article fetches (seconds)
+# FETCH_CONCURRENCY=10                      # Max concurrent feed fetches
+# MIN_CONTENT_LENGTH=200                    # Min chars for the article quality check
+# MAX_BOILERPLATE_RATIO=0.05                # Max boilerplate fraction before rejection
+
+# -- Summarizer (per-article fact extraction) --
+# Per-article LLM call producing a fact-dense 2-4 sentence summary.
+# Concurrency is capped by SUMMARIZER_CONCURRENCY.
+# SUMMARIZER_MODEL=gemma4:31b-cloud
+# SUMMARIZER_TEMPERATURE=0.2
+# SUMMARIZER_TOP_P=                         # unset uses the Ollama default
+# SUMMARIZER_REPETITION_PENALTY=
+# SUMMARIZER_SEED=
+# SUMMARIZER_CONCURRENCY=8                  # Max concurrent per-article LLM calls
+# CONTENT_HEAD_MAX_CHARS=2000               # Max chars of raw article text passed to the digest writer
+
+# -- Topic classifier (BART-MNLI zero-shot) --
+# TOPIC_MODEL=facebook/bart-large-mnli
+# TOPIC_REVISION=d7645e127eaf1aefc7862fd59a17a5aa8558b8ce
+# TOPIC_THRESHOLD=0.5                       # Min probability to accept a label
+# TOPIC_MAX_LENGTH=512                      # Max input length in tokens
+
+# -- Digest stage models --
+# Writer drafts each section; Editorial cleans up the prose; Framer generates
+# the title and intro; Watcher produces the cross-section watch list.
+# Framer and Watcher fall back to WRITER_MODEL when unset.
+# WRITER_MODEL=gemma4:31b-cloud
+# EDITORIAL_MODEL=gpt-oss:120b-cloud
+# FRAMER_MODEL=                             # unset, falls back to WRITER_MODEL
+# WATCHER_MODEL=                            # unset, falls back to WRITER_MODEL
+# CLUSTERER_MODEL=gpt-oss:120b-cloud        # groups related articles into stories
+
+# -- Digest stage temperatures --
+# WRITER_TEMPERATURE=0.4
+# EDITORIAL_TEMPERATURE=0.4
+# FRAMER_TEMPERATURE=0.4
+# WATCHER_TEMPERATURE=0.4
+# CLUSTERER_TEMPERATURE=0.4
+
+# -- Digest stage sampling knobs (all unset by default, so Ollama defaults apply) --
+# Each stage exposes top_p (nucleus cutoff), repetition_penalty, and seed
+# (for reproducible output). The `digest` subcommand exposes matching CLI
+# flags (--writer-seed N, and so on) plus a global --seed N shortcut.
+# WRITER_TOP_P=
+# WRITER_REPETITION_PENALTY=
+# WRITER_SEED=
+# EDITORIAL_TOP_P=
+# EDITORIAL_REPETITION_PENALTY=
+# EDITORIAL_SEED=
+# FRAMER_TOP_P=
+# FRAMER_REPETITION_PENALTY=
+# FRAMER_SEED=
+# WATCHER_TOP_P=
+# WATCHER_REPETITION_PENALTY=
+# WATCHER_SEED=
+# CLUSTERER_TOP_P=
+# CLUSTERER_REPETITION_PENALTY=
+# CLUSTERER_SEED=
+
+# -- Writer extras --
+# WRITER_SECTION_BATCH_SIZE=30              # Max articles per writer batch
+
+# -- Audio (opt-in TTS narration via Piper + ffmpeg) --
+# Off by default. Enable per invocation with --audio on `digest-generator run`
+# or `digest-generator digest`, or with the standalone `digest-generator audio`.
+# AUDIO_ENABLED=false                       # Enable the audio renderer
+# AUDIO_VOICE_MODEL=en_US-amy-medium        # Piper voice id from rhasspy/piper-voices
+# AUDIO_VOICE_REVISION=375a0fe641dea077c2a47b4e9a056d6da521eed3
+                                            # Pinned voice-repo revision
+# AUDIO_BITRATE_KBPS=24                     # Opus encode bitrate (mono spoken word)
+# AUDIO_SAMPLE_RATE=22050                   # Piper sample rate (voice-dependent)
+# AUDIO_VOICE_CACHE=~/.cache/digest_generator/piper-voices
+                                            # Cache for downloaded Piper voice files
+# AUDIO_FFMPEG_PATH=ffmpeg                  # Override the ffmpeg binary path
+# AUDIO_SENTENCE_SILENCE_S=0.4              # Pause length between sentences (seconds)
+
+# =============================================================================
+# Pipeline-level
+# =============================================================================
+
+# DAYS_BACK=7                               # How many days back to fetch articles
+# OUTPUT_DIR=output                         # Root output directory
+
+# =============================================================================
+# Logging
+# =============================================================================
+
+# LOG_LEVEL_CONSOLE=INFO                    # Console log level
+# LOG_LEVEL_FILE=DEBUG                      # File log level (logs/digest_generator.log + run.log)
+# LOG_DIR=logs                              # Global log file directory
+# LOG_ROTATION=20 MB                        # Size-based rotation for the global log
+# LOG_RETENTION=5                           # Number of rotated files to keep

digest_generator-0.1.0/.github/CODEOWNERS

@@ -0,0 +1 @@
+* @laplacef

digest_generator-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,39 @@
+---
+name: Bug report
+about: Report something that isn't working as expected
+title: ''
+labels: bug
+assignees: ''
+---
+
+## Description
+
+<!-- A clear and concise description of the bug. -->
+
+## Steps to reproduce
+
+1.
+2.
+3.
+
+## Expected behavior
+
+<!-- What you expected to happen. -->
+
+## Actual behavior
+
+<!-- What actually happened. Include error messages or logs if available. -->
+
+## Minimal reproduction
+
+<!-- The smallest command, input, or code snippet that triggers the bug. -->
+
+## Environment
+
+- OS:
+- Python version:
+- Project version / commit:
+
+## Additional context
+
+<!-- Anything else that might help diagnose the problem. -->

digest_generator-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,6 @@
+# Require contributors to use a template instead of opening a blank issue.
+blank_issues_enabled: false
+contact_links:
+  - name: Security vulnerability
+    url: https://github.com/laplacef/digest-generator/security/advisories/new
+    about: Report security issues privately. Do not open a public issue.

digest_generator-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,23 @@
+---
+name: Feature request
+about: Suggest an idea or improvement
+title: ''
+labels: enhancement
+assignees: ''
+---
+
+## Problem
+
+<!-- What problem does this solve? What are you trying to do that you can't today? -->
+
+## Proposed solution
+
+<!-- The change you'd like to see. -->
+
+## Alternatives considered
+
+<!-- Other approaches you thought about, and why you prefer the one above. -->
+
+## Additional context
+
+<!-- Mockups, links, prior art, or anything else that clarifies the request. -->

digest_generator-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,24 @@
+<!-- Thanks for contributing! Complete the sections below so reviewers have what they need. -->
+
+## Summary
+
+<!-- What does this PR do, and why? Link the issue it addresses. -->
+
+Closes #<issue-number>
+
+## Type of change
+
+- [ ] Feature
+- [ ] Bug fix
+- [ ] Documentation
+- [ ] Refactor
+- [ ] Other
+
+## Checklist
+
+- [ ] My change follows the project's coding standards (see [CONTRIBUTING.md](../CONTRIBUTING.md)).
+- [ ] Commits follow Conventional Commits.
+- [ ] I ran `uv run pre-commit run --all-files` and `uv run pytest` locally.
+- [ ] I added or updated tests for my change.
+- [ ] I updated documentation where relevant.
+- [ ] No secrets or credentials are committed (`.env` stays local).

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

@@ -0,0 +1,38 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  pre-commit:
+    name: Pre-commit (lint, format, types, security, secrets)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+      - run: uv sync --frozen --extra dev
+      - uses: actions/cache@v4
+        with:
+          path: ~/.cache/pre-commit
+          key: pre-commit-${{ hashFiles('.pre-commit-config.yaml') }}
+      - run: uv run --no-sync pre-commit run --all-files --show-diff-on-failure
+
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+      - run: uv sync --frozen --extra dev
+      - run: uv run --no-sync pytest tests/ -v --cov=digest_generator --cov-report=term-missing

digest_generator-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,103 @@
+name: Release
+
+# Tagging vX.Y.Z builds the distributions, publishes them to PyPI via OIDC
+# trusted publishing, and cuts a GitHub Release with the changelog entry.
+#
+# Trusted publishing setup (one-time, no API token needed):
+#   1. On PyPI, add a trusted publisher for project "digest-generator":
+#      owner=laplacef, repo=digest-generator, workflow=release.yml,
+#      environment=pypi.
+#   2. On GitHub, create an environment named "pypi" (optionally with
+#      required reviewers) so the publish step is gated.
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+
+      - name: Verify tag matches package version
+        run: |
+          tag="${GITHUB_REF_NAME#v}"
+          version=$(grep -m1 '^version = ' pyproject.toml | sed -E 's/version = "(.*)"/\1/')
+          if [ "$tag" != "$version" ]; then
+            echo "Tag $GITHUB_REF_NAME ($tag) does not match pyproject version $version" >&2
+            exit 1
+          fi
+
+      - name: Build sdist and wheel
+        run: uv build
+
+      - name: Validate distributions
+        run: uvx twine check dist/*
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  pypi-publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write # OIDC token for trusted publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    name: Create GitHub Release
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    # Pass the tag through the environment (never interpolate ${{ }} into a
+    # run: script body — a tag may legally contain shell metacharacters).
+    env:
+      TAG: ${{ github.ref_name }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Extract changelog entry
+        run: |
+          version="${TAG#v}"
+          awk -v ver="$version" '
+            /^## \[/ {
+              if (found) exit
+              if (index($0, "[" ver "]")) found=1
+              next
+            }
+            found { print }
+          ' CHANGELOG.md > release_notes.md
+
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh release create "$TAG" \
+            --title "$TAG" \
+            --notes-file release_notes.md \
+            dist/*

digest_generator-0.1.0/.gitignore

@@ -0,0 +1,63 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual Environment
+.venv/
+venv/
+ENV/
+env/
+
+# Environment Variables
+.env
+.env.*
+!.env.example
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Ruff
+.ruff_cache/
+
+# MyPy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pytest / Coverage
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Run output
+output/
+
+# Logs
+logs/
+*.log
+
+# OS
+.DS_Store
+Thumbs.db

digest_generator-0.1.0/.gitleaks.toml

@@ -0,0 +1,23 @@
+# gitleaks configuration.
+#
+# `useDefault` keeps every built-in rule active; the allowlist below only
+# suppresses known false positives so the scanner stays strict everywhere else.
+[extend]
+useDefault = true
+
+[allowlist]
+description = "Repo-specific false-positive allowlist"
+
+# detect-secrets stores accepted findings as SHA1 hashes; gitleaks would
+# otherwise flag those hashes as generic high-entropy secrets.
+paths = [
+  '''\.secrets\.baseline''',
+]
+
+# Pinned, public model/voice revision identifiers (40-char git SHAs), not
+# secrets: the HuggingFace topic-model revision and the Piper voice-repo
+# revision. Update these if the pins in settings.py / .env.example change.
+regexes = [
+  '''d7645e127eaf1aefc7862fd59a17a5aa8558b8ce''',
+  '''375a0fe641dea077c2a47b4e9a056d6da521eed3''',
+]

digest_generator-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,81 @@
+default_language_version:
+  python: python3.13
+
+default_stages: [pre-commit]
+
+fail_fast: false
+
+repos:
+  # Basic file checks
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: trailing-whitespace
+        name: Trim trailing whitespace
+      - id: end-of-file-fixer
+        name: Fix end of files
+      - id: check-yaml
+        name: Check YAML syntax
+      - id: check-toml
+        name: Check TOML syntax
+      - id: check-added-large-files
+        name: Check for large files
+        args: ['--maxkb=1000']
+      - id: check-case-conflict
+        name: Check for case conflicts
+      - id: check-merge-conflict
+        name: Check for merge conflicts
+      - id: detect-private-key
+        name: Detect private keys
+
+  # Project tools run via `uv run` as local hooks so pre-commit and CI use the
+  # same tool version (the uv-locked one) and the same project-aware config in
+  # pyproject.toml. No drift between hook `rev` pins and the lockfile, and no
+  # weaker isolated mypy environment.
+  #
+  # `--no-sync` runs each tool from the already-synced dev venv without
+  # re-syncing. A bare `uv run <tool>` would drop the `dev` extra mid-run.
+  # Requires `uv sync --extra dev` first (see CONTRIBUTING.md and CI).
+  - repo: local
+    hooks:
+      - id: ruff
+        name: Ruff linter
+        entry: uv run --no-sync ruff check --fix
+        language: system
+        types_or: [python, pyi]
+        require_serial: true
+      - id: ruff-format
+        name: Ruff formatter
+        entry: uv run --no-sync ruff format
+        language: system
+        types_or: [python, pyi]
+        require_serial: true
+      - id: mypy
+        name: Type checking with mypy
+        entry: uv run --no-sync mypy digest_generator/
+        language: system
+        types: [python]
+        pass_filenames: false
+      - id: bandit
+        name: Security checks with Bandit
+        entry: uv run --no-sync bandit -c pyproject.toml -r digest_generator/
+        language: system
+        types: [python]
+        pass_filenames: false
+
+  # Secret detection with Yelp/detect-secrets (entropy and regex scanner).
+  - repo: https://github.com/Yelp/detect-secrets
+    rev: v1.5.0
+    hooks:
+      - id: detect-secrets
+        name: Secret detection (detect-secrets)
+        args: ["--baseline", ".secrets.baseline"]
+        exclude: ^(\.secrets\.baseline|\.gitleaks\.toml|uv\.lock)
+
+  # Secret detection with gitleaks, a regex scanner with broader default
+  # rule coverage than detect-secrets.
+  - repo: https://github.com/gitleaks/gitleaks
+    rev: v8.30.1
+    hooks:
+      - id: gitleaks
+        name: Secret detection (gitleaks)

digest_generator-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13

digest_generator-0.1.0/.secrets.baseline

@@ -0,0 +1,133 @@
+{
+  "version": "1.5.0",
+  "plugins_used": [
+    {
+      "name": "ArtifactoryDetector"
+    },
+    {
+      "name": "AWSKeyDetector"
+    },
+    {
+      "name": "AzureStorageKeyDetector"
+    },
+    {
+      "name": "Base64HighEntropyString",
+      "limit": 4.5
+    },
+    {
+      "name": "BasicAuthDetector"
+    },
+    {
+      "name": "CloudantDetector"
+    },
+    {
+      "name": "DiscordBotTokenDetector"
+    },
+    {
+      "name": "GitHubTokenDetector"
+    },
+    {
+      "name": "GitLabTokenDetector"
+    },
+    {
+      "name": "HexHighEntropyString",
+      "limit": 3.0
+    },
+    {
+      "name": "IbmCloudIamDetector"
+    },
+    {
+      "name": "IbmCosHmacDetector"
+    },
+    {
+      "name": "IPPublicDetector"
+    },
+    {
+      "name": "JwtTokenDetector"
+    },
+    {
+      "name": "KeywordDetector",
+      "keyword_exclude": ""
+    },
+    {
+      "name": "MailchimpDetector"
+    },
+    {
+      "name": "NpmDetector"
+    },
+    {
+      "name": "OpenAIDetector"
+    },
+    {
+      "name": "PrivateKeyDetector"
+    },
+    {
+      "name": "PypiTokenDetector"
+    },
+    {
+      "name": "SendGridDetector"
+    },
+    {
+      "name": "SlackDetector"
+    },
+    {
+      "name": "SoftlayerDetector"
+    },
+    {
+      "name": "SquareOAuthDetector"
+    },
+    {
+      "name": "StripeDetector"
+    },
+    {
+      "name": "TelegramBotTokenDetector"
+    },
+    {
+      "name": "TwilioKeyDetector"
+    }
+  ],
+  "filters_used": [
+    {
+      "path": "detect_secrets.filters.allowlist.is_line_allowlisted"
+    },
+    {
+      "path": "detect_secrets.filters.common.is_ignored_due_to_verification_policies",
+      "min_level": 2
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_indirect_reference"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_likely_id_string"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_lock_file"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_not_alphanumeric_string"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_potential_uuid"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_prefixed_with_dollar_sign"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_sequential_string"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_swagger_file"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_templated_secret"
+    },
+    {
+      "path": "detect_secrets.filters.regex.should_exclude_file",
+      "pattern": [
+        "\\.venv|\\.mypy_cache|samples|uv\\.lock|node_modules"
+      ]
+    }
+  ],
+  "results": {},
+  "generated_at": "2026-05-13T21:55:02Z"
+}