# Hybrid AI Local News Classification Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Unify RSS and scraping news classification so category and Bangladesh location are assigned by source mapping/rules first and Gemini only as an optional fallback, with admin controls and district/division Local News API queries.

**Architecture:** Add an isolated classification service with deterministic precedence: strict source mapping → rule/dictionary detection → optional AI fallback. Persist classification provenance/confidence on each news row and source-level classification settings on RSS/scrape sources. Preserve GPS local-news behavior while adding district/division filters.

**Tech Stack:** PHP 8+, MySQL/PDO, existing Gemini/OpenAI/Anthropic HTTP helper, existing admin PHP UI.

**Spec:** `docs/superpowers/specs/2026-09-14-hybrid-ai-local-news-classification-design.md`

## Global Constraints
- Existing ingestion must continue when AI is disabled, unavailable, rate-limited, or returns invalid output.
- Source/page fixed mapping has higher precedence than AI.
- AI category output must be restricted to the existing category whitelist.
- Existing GPS Local News API remains backward-compatible.
- Database migration must be additive and safe for existing installs.

---

### Task 1: Classification Engine
**Files:** Create `includes/news_classification.php`; modify `includes/functions.php`; test `tests/test_news_classification.php`.
- [ ] Write failing tests for category whitelist, strict mapping, deterministic geo, AI fallback parsing and no-AI fallback.
- [ ] Run tests and verify failure.
- [ ] Implement pure classification helpers and single-call AI structured classification.
- [ ] Run tests and verify pass.

### Task 2: Persistence and Migration
**Files:** Create `database/migration_hybrid_local_classification.sql`; modify `database/schema.sql`, `includes/functions.php`.
- [ ] Add source classification mode/location fields and news provenance/location fields.
- [ ] Update source save/load functions without breaking old defaults.
- [ ] Update RSS and scraping inserts to persist classification result.
- [ ] Verify PHP syntax and migration contract.

### Task 3: Admin Controls
**Files:** Modify `admin/settings.php`, `admin/sources.php`, `admin/scrape_sources.php`.
- [ ] Add global AI classification master switch/confidence/daily-call controls.
- [ ] Add source-level category mode/location mode/division/district/upazila/AI toggle controls for RSS and scrape sources.
- [ ] Preserve existing source create/toggle/delete behavior.
- [ ] Verify form contracts and PHP syntax.

### Task 4: Local News API
**Files:** Modify `api/local_news.php`; test `tests/test_local_news_api_contract.php`.
- [ ] Add district, districts and division filtering while preserving GPS mode.
- [ ] Return location provenance/confidence in items where present.
- [ ] Validate filter inputs and pagination.
- [ ] Run contract tests and PHP syntax checks.

### Task 5: Verification and Packaging
**Files:** Create `HYBRID_LOCAL_NEWS_V33.md`; package `BD-News-Control-Center-V3.3-Hybrid-Local-News.zip`.
- [ ] Run classification/API tests plus existing backend tests.
- [ ] Run PHP lint across project.
- [ ] Run ZIP integrity test.
- [ ] Document migration/import and admin setup examples (Sunamganj strict/smart source mapping).