commit d8243c31f993aca4bd50aee446982933a37ed6ac · bretton.dev/coves

aggregators/kagi-news/.env.example

···

       1
       +
       # Aggregator Identity (pre-created account credentials)

     

       2
       +
       AGGREGATOR_HANDLE=kagi-news.local.coves.dev

     

       3
       +
       AGGREGATOR_PASSWORD=your-secure-password-here

     

       4
       +
       

     

       5
       +
       # Optional: Override Coves API URL (defaults to config.yaml)

     

       6
       +
       # COVES_API_URL=http://localhost:3001

+173

aggregators/kagi-news/README.md

···

       1
       +
       # Kagi News RSS Aggregator

     

       2
       +
       

     

       3
       +
       A Python-based RSS aggregator that posts Kagi News stories to Coves communities using rich text formatting.

     

       4
       +
       

     

       5
       +
       ## Overview

     

       6
       +
       

     

       7
       +
       This aggregator:

     

       8
       +
       - Fetches RSS feeds from Kagi News daily via CRON

     

       9
       +
       - Parses HTML descriptions to extract structured content (highlights, perspectives, sources)

     

       10
       +
       - Formats posts using Coves rich text with facets (bold, italic, links)

     

       11
       +
       - Hot-links images from Kagi's proxy (no blob upload)

     

       12
       +
       - Posts to configured communities via XRPC

     

       13
       +
       

     

       14
       +
       ## Project Structure

     

       15
       +
       

     

       16
       +
       ```

     

       17
       +
       aggregators/kagi-news/

     

       18
       +
       ├── src/

     

       19
       +
       │   ├── models.py              # Data models (KagiStory, Perspective, etc.)

     

       20
       +
       │   ├── rss_fetcher.py         # RSS feed fetching with retry logic

     

       21
       +
       │   ├── html_parser.py         # Parse Kagi HTML to structured data

     

       22
       +
       │   ├── richtext_formatter.py  # Format content with rich text facets (TODO)

     

       23
       +
       │   ├── atproto_client.py      # ATProto authentication and operations (TODO)

     

       24
       +
       │   ├── state_manager.py       # Deduplication state tracking (TODO)

     

       25
       +
       │   ├── config.py              # Configuration loading (TODO)

     

       26
       +
       │   └── main.py                # Entry point (TODO)

     

       27
       +
       ├── tests/

     

       28
       +
       │   ├── test_rss_fetcher.py    # RSS fetcher tests ✓

     

       29
       +
       │   ├── test_html_parser.py    # HTML parser tests ✓

     

       30
       +
       │   └── fixtures/

     

       31
       +
       │       ├── sample_rss_item.xml

     

       32
       +
       │       └── world.xml

     

       33
       +
       ├── scripts/

     

       34
       +
       │   └── generate_did.py        # Helper to generate aggregator DID (TODO)

     

       35
       +
       ├── requirements.txt           # Python dependencies

     

       36
       +
       ├── config.example.yaml        # Example configuration

     

       37
       +
       ├── .env.example               # Environment variables template

     

       38
       +
       ├── crontab                    # CRON schedule

     

       39
       +
       └── README.md

     

       40
       +
       ```

     

       41
       +
       

     

       42
       +
       ## Setup

     

       43
       +
       

     

       44
       +
       ### Prerequisites

     

       45
       +
       

     

       46
       +
       - Python 3.11+

     

       47
       +
       - python3-venv package (`apt install python3.12-venv`)

     

       48
       +
       

     

       49
       +
       ### Installation

     

       50
       +
       

     

       51
       +
       1. Create virtual environment:

     

       52
       +
          ```bash

     

       53
       +
          python3 -m venv venv

     

       54
       +
          source venv/bin/activate

     

       55
       +
          ```

     

       56
       +
       

     

       57
       +
       2. Install dependencies:

     

       58
       +
          ```bash

     

       59
       +
          pip install -r requirements.txt

     

       60
       +
          ```

     

       61
       +
       

     

       62
       +
       3. Copy configuration templates:

     

       63
       +
          ```bash

     

       64
       +
          cp config.example.yaml config.yaml

     

       65
       +
          cp .env.example .env

     

       66
       +
          ```

     

       67
       +
       

     

       68
       +
       4. Edit `config.yaml` to map RSS feeds to communities

     

       69
       +
       5. Set environment variables in `.env` (aggregator DID and private key)

     

       70
       +
       

     

       71
       +
       ## Running Tests

     

       72
       +
       

     

       73
       +
       ```bash

     

       74
       +
       # Activate virtual environment

     

       75
       +
       source venv/bin/activate

     

       76
       +
       

     

       77
       +
       # Run all tests

     

       78
       +
       pytest -v

     

       79
       +
       

     

       80
       +
       # Run specific test file

     

       81
       +
       pytest tests/test_html_parser.py -v

     

       82
       +
       

     

       83
       +
       # Run with coverage

     

       84
       +
       pytest --cov=src --cov-report=html

     

       85
       +
       ```

     

       86
       +
       

     

       87
       +
       ## Development Status

     

       88
       +
       

     

       89
       +
       ### ✅ Phase 1-2 Complete (Oct 24, 2025)

     

       90
       +
       - [x] Project structure created

     

       91
       +
       - [x] Data models defined (KagiStory, Perspective, Quote, Source)

     

       92
       +
       - [x] RSS fetcher with retry logic and tests

     

       93
       +
       - [x] HTML parser extracting all sections (summary, highlights, perspectives, sources, quote, image)

     

       94
       +
       - [x] Test fixtures from real Kagi News feed

     

       95
       +
       

     

       96
       +
       ### 🚧 Next Steps (Phase 3-4)

     

       97
       +
       - [ ] Rich text formatter (convert to Coves format with facets)

     

       98
       +
       - [ ] State manager for deduplication

     

       99
       +
       - [ ] Configuration loader

     

       100
       +
       - [ ] ATProto client for post creation

     

       101
       +
       - [ ] Main orchestration script

     

       102
       +
       - [ ] End-to-end tests

     

       103
       +
       

     

       104
       +
       ## Configuration

     

       105
       +
       

     

       106
       +
       Edit `config.yaml` to define feed-to-community mappings:

     

       107
       +
       

     

       108
       +
       ```yaml

     

       109
       +
       coves_api_url: "https://api.coves.social"

     

       110
       +
       

     

       111
       +
       feeds:

     

       112
       +
         - name: "World News"

     

       113
       +
           url: "https://news.kagi.com/world.xml"

     

       114
       +
           community_handle: "world-news.coves.social"

     

       115
       +
           enabled: true

     

       116
       +
       

     

       117
       +
         - name: "Tech News"

     

       118
       +
           url: "https://news.kagi.com/tech.xml"

     

       119
       +
           community_handle: "tech.coves.social"

     

       120
       +
           enabled: true

     

       121
       +
       ```

     

       122
       +
       

     

       123
       +
       ## Architecture

     

       124
       +
       

     

       125
       +
       ### Data Flow

     

       126
       +
       

     

       127
       +
       ```

     

       128
       +
       Kagi RSS Feed

     

       129
       +
           ↓ (HTTP GET)

     

       130
       +
       RSS Fetcher

     

       131
       +
           ↓ (feedparser)

     

       132
       +
       Parsed RSS Items

     

       133
       +
           ↓ (for each item)

     

       134
       +
       HTML Parser

     

       135
       +
           ↓ (BeautifulSoup)

     

       136
       +
       Structured KagiStory

     

       137
       +
           ↓

     

       138
       +
       Rich Text Formatter

     

       139
       +
           ↓ (with facets)

     

       140
       +
       Post Record

     

       141
       +
           ↓ (XRPC)

     

       142
       +
       Coves Community

     

       143
       +
       ```

     

       144
       +
       

     

       145
       +
       ### Rich Text Format

     

       146
       +
       

     

       147
       +
       Posts use Coves rich text with UTF-8 byte-positioned facets:

     

       148
       +
       

     

       149
       +
       ```python

     

       150
       +
       {

     

       151
       +
         "content": "Summary text...\n\nHighlights:\n• Point 1\n...",

     

       152
       +
         "facets": [

     

       153
       +
           {

     

       154
       +
             "index": {"byteStart": 20, "byteEnd": 31},

     

       155
       +
             "features": [{"$type": "social.coves.richtext.facet#bold"}]

     

       156
       +
           },

     

       157
       +
           {

     

       158
       +
             "index": {"byteStart": 50, "byteEnd": 75},

     

       159
       +
             "features": [{"$type": "social.coves.richtext.facet#link", "uri": "https://..."}]

     

       160
       +
           }

     

       161
       +
         ]

     

       162
       +
       }

     

       163
       +
       ```

     

       164
       +
       

     

       165
       +
       ## License

     

       166
       +
       

     

       167
       +
       See parent Coves project license.

     

       168
       +
       

     

       169
       +
       ## Related Documentation

     

       170
       +
       

     

       171
       +
       - [PRD: Kagi News Aggregator](../../docs/aggregators/PRD_KAGI_NEWS_RSS.md)

     

       172
       +
       - [PRD: Aggregator System](../../docs/aggregators/PRD_AGGREGATORS.md)

     

       173
       +
       - [Coves Rich Text Lexicon](../../internal/atproto/lexicon/social/coves/richtext/README.md)

+29

aggregators/kagi-news/config.example.yaml

···

       1
       +
       # Kagi News RSS Aggregator Configuration

     

       2
       +
       

     

       3
       +
       # Coves API endpoint

     

       4
       +
       coves_api_url: "https://api.coves.social"

     

       5
       +
       

     

       6
       +
       # Feed-to-community mappings

     

       7
       +
       feeds:

     

       8
       +
         - name: "World News"

     

       9
       +
           url: "https://news.kagi.com/world.xml"

     

       10
       +
           community_handle: "world-news.coves.social"

     

       11
       +
           enabled: true

     

       12
       +
       

     

       13
       +
         - name: "Tech News"

     

       14
       +
           url: "https://news.kagi.com/tech.xml"

     

       15
       +
           community_handle: "tech.coves.social"

     

       16
       +
           enabled: true

     

       17
       +
       

     

       18
       +
         - name: "Business News"

     

       19
       +
           url: "https://news.kagi.com/business.xml"

     

       20
       +
           community_handle: "business.coves.social"

     

       21
       +
           enabled: false

     

       22
       +
       

     

       23
       +
         - name: "Science News"

     

       24
       +
           url: "https://news.kagi.com/science.xml"

     

       25
       +
           community_handle: "science.coves.social"

     

       26
       +
           enabled: false

     

       27
       +
       

     

       28
       +
       # Logging configuration

     

       29
       +
       log_level: "info"  # debug, info, warning, error

aggregators/kagi-news/crontab

···

       1
       +
       # Run Kagi News aggregator daily at 1 PM UTC (after Kagi updates around noon)

     

       2
       +
       0 13 * * * cd /app && /usr/local/bin/python -m src.main >> /var/log/cron.log 2>&1

     

       3
       +
       

     

       4
       +
       # Blank line required at end of crontab

     

       5
       +

+12

aggregators/kagi-news/pytest.ini

···

       1
       +
       [pytest]

     

       2
       +
       testpaths = tests

     

       3
       +
       python_files = test_*.py

     

       4
       +
       python_classes = Test*

     

       5
       +
       python_functions = test_*

     

       6
       +
       addopts =

     

       7
       +
           -v

     

       8
       +
           --strict-markers

     

       9
       +
           --tb=short

     

       10
       +
           --cov=src

     

       11
       +
           --cov-report=term-missing

     

       12
       +
           --cov-report=html

+17

aggregators/kagi-news/requirements.txt

···

       1
       +
       # Core dependencies

     

       2
       +
       feedparser==6.0.11

     

       3
       +
       beautifulsoup4==4.12.3

     

       4
       +
       requests==2.31.0

     

       5
       +
       atproto==0.0.55

     

       6
       +
       pyyaml==6.0.1

     

       7
       +
       

     

       8
       +
       # Testing

     

       9
       +
       pytest==8.1.1

     

       10
       +
       pytest-cov==5.0.0

     

       11
       +
       responses==0.25.0

     

       12
       +
       

     

       13
       +
       # Development

     

       14
       +
       black==24.3.0

     

       15
       +
       mypy==1.9.0

     

       16
       +
       types-PyYAML==6.0.12.12

     

       17
       +
       types-requests==2.31.0.20240311