AthenaV2/PRD.md

# AthenaV2 PRD + Design Document v2.1

**Project**: AI News Daily Engine (AthenaV2)
**Owner**: Ty tech
**Repo**: Ty/AthenaV2
**Date**: 2026-07-15

## 1. Executive Summary
AthenaV2 powers **AI News Daily** — a curated daily operating system for serious AI practitioners who run local models, build agents, and tinker with hardware.

**Guiding Principle**: Optimize for *helping readers do things*, not just know things.

**Strategic Focus**: Builder Outcome Acquisition (real production wins, cost savings, shipped tools) to improve editorial quality and Keep Rate.

## 2. User Stories (Extracted from Original Scope)
- As a builder, I want curated “what shipped” + local setups (GGUF, Ollama, benchmarks) so I can install/run tonight.
- As a tinkerer, I want benchmarks, builds, and production stories (problem → solution → result).
- As a reader, I want strict filtering so only high-signal, actionable items reach me.
- As operator, I want the machine to handle ingestion, deduplication, classification, ranking, memory, trends, velocity/impact/hype scoring.
- Human Taste Layer retains final judgment, taste, and spotlights (Setup of the Day).
- As premium user, I want deeper agentic access via MCP beyond the static web page.
- Long-term: Builder Intelligence to surface verifiable outcomes (saved time/money, shipped tools, production wins) for higher Keep Rate.

## 3. Success Metrics
**Primary Health Metric**: Keep Rate = Stories Ingested → Candidates Clearing Editorial Test → Published
Example: 840 ingested → 73 candidates → 18 published (2.1% keep rate). Goal: Improve via outcome-focused sourcing.

## 4. Full Architecture (Tight & Consolidated — No Redundancies)
**Base Layer**
- Docker Compose on fresh colo Ubuntu 24.04 LTS
- Gitea (Git repo for content, PRs/issues for human review, Actions for CI)
  *Why*: Single lightweight hub for versioning, collaboration, audit, and human taste workflow. Self-hosted, low resource.

**Ingestion Layer**
- Python scripts / n8n (GitHub, Hugging Face APIs, webhooks, polite polling) + Redis queue
- Early outcome signal hunting (Builder Intelligence seeds)
  *Why*: Fast, controllable, respects “what shipped today” while feeding outcome discovery.

**AI Processing Layer**
- Ollama (Nomic embeddings + strong open LLM) + LlamaIndex pipelines
  *Why*: Local-first, efficient batch inference; unified service for classification, scoring (actionability + outcome strength + hype vs substance), summarization.

**Knowledge Layer**
- Postgres + pgvector (vectors, graph edges, similarity, trends, clustering)
- Structured Markdown in Gitea (human-readable drafts, history, direct site export)
  *Why*: Handles semantic search/clustering/memory without extra Neo4j bloat. Markdown ensures readability and easy export.

**Orchestration Layer**
- Prefect (self-hosted server + workers)
  *Why*: Single tool for DAGs, scheduling, monitoring, retries, and human approval gates. Eliminates cron redundancy.

**Public Output Layer**
- Astro/Hugo static site generation
  *Why*: Fast, secure, low-cost daily editions matching the 80/15/5 organizational structure.

**Premium Output Layer**
- MCP Server (agentic API endpoint)
  *Why*: Turns the static site into an interactive daily OS for paying users. Recurring revenue + deeper value.

## 5. MCP Premium Tier — Detailed Use Cases
MCP gives subscribers agentic, personalized, interactive access to the full knowledge graph, embeddings, and pipelines.

**Use Case 1: Personalized Research & Synthesis**
Query: “Summarize production wins for agent frameworks on RTX 50-series GPUs this month with benchmarks and outcome metrics.”
Output: Graph traversal + synthesized summary with links and verifiable results.
Value: Saves hours of manual searching; surfaces tailored, high-signal insights.

**Use Case 2: Hardware-Specific Setup Guidance**
Query: “Best GGUF quantization for my dual 5060 Ti setup from latest releases, with one-command install and expected throughput.”
Output: Hardware-aware recommendations + direct install commands.
Value: Direct “evening experiment” support with personalized performance expectations.

**Use Case 3: Workflow Stealing & Adaptation**
Query: “Find local RAG production stories and adapt for my WooCommerce inventory automation.”
Output: Problem-solution-result templates + customized code snippets.
Value: Accelerates building by stealing proven patterns safely.

**Use Case 4: Outcome & Trend Deep Dives (Builder Intelligence Powered)**
Query: “Real cost savings examples from switching to local LLMs in SaaS or agent products.”
Output: Builder Intelligence-enriched results with metrics and sources.
Value: Informs business decisions with evidence, not hype.

**Use Case 5: Proactive Monitoring & Alerts**
Scheduled or conversational: “Alert me to new high-impact quantization releases matching my hardware profile.”
Follow-up: “Build on yesterday’s analysis with the latest llama.cpp PR.”
Value: Turns daily edition into always-on companion.

**Use Case 6: Seamless Integration & Export**
Query: “Export top 3 setups as Markdown ready for my Obsidian vault or Hermes agent.”
Output: Native integration with user’s local stack.
Value: Embeds the engine directly into existing workflows.

**MCP Technical Notes**: Authenticated, rate-limited, sandboxed. Starts read-heavy; expands to light tools. Tiered pricing. Reuses existing Ollama/Postgres/Gitea resources.

## 6. Builder Intelligence Module (Week 5+ Priority)
**Purpose**: Solve the hidden supply-chain risk — most signals are junk; outcomes create memorable, high-value stories that readers remember and act on.

**Specific Outcome Signal Sources**:
- X/Twitter (advanced search with practitioner keywords + outcome verbs: shipped, launched, cut costs, production, customers, workflow)
- Reddit (r/LocalLLaMA, r/selfhosted, r/SaaS success threads)
- GitHub issues/PRs (showcase, production labels, linked blogs)
- Discord showcase channels (Ollama, llama.cpp, agent frameworks)
- Indie Hackers / Product Hunt launches with revenue/usage metrics
- Hugging Face discussions & model card comments

**How it Works**: Targeted crawlers + LLM outcome classifier → feeds main scoring pipeline (boosts actionability score). Enriches graph with outcome edges.
**MCP Bonus**: Premium users can query “find verified production wins for X on my hardware.”

## 7. The Real System Flow
```
Athena Engine
  ├─ Ingestion (+ Builder Outcome Signals)
  ├─ Scoring (Actionability + Outcome Strength + Hype/Substance)
  ├─ Memory / Knowledge Layer (pgvector + Gitea Markdown)
  ├─ Trends / Builder Intelligence
  └─ MCP (Premium Agentic Access)

         ↓ (Human Taste Layer — Editorial Review & Judgment)

      Daily Edition (Public Site)
```

## 8. Why This Design (Consolidations & Rationale)
- **No Redundancies**: Single orchestrator (Prefect), unified knowledge store (Markdown + pgvector), Gitea as central nervous system. Removed Neo4j, raw cron, dual schedulers.
- **Colo Practical**: Low idle footprint; reuses services; GPU optional for Ollama batches.
- **Scalable & Maintainable**: Start simple, add Builder Intelligence iteratively.
- **Strategic Moat**: Builder Intelligence + MCP premium directly addresses quality and monetization.
- **Risk-Managed**: Early filtering + human layer prevents junk; real editions drive learning.
- **Aligned with Architect Feedback**: Architecture approved; Builder Outcome Acquisition elevated as key future component.

## 9. Roadmap
- **Week 1**: Infrastructure, Ingestion, Storage.
- **Week 2**: Scoring, Classification, Draft generation.
- **Week 3**: Edition building, Human review workflow + Keep Rate dashboards.
- **Week 4**: Site launch, MCP foundation, Monitoring, Backups.
- **Week 5+**: Builder Intelligence (outcome pipelines) — prioritized over advanced graphs/narratives.

**Next Actions**: Build the pipeline. Generate real editions. Measure Keep Rate. Tighten the lens every week.

**Status**: Architecture approved. Captured in Ty/AthenaV2 repo.