123 lines
4.6 KiB
Markdown
123 lines
4.6 KiB
Markdown
# Architecture
|
|
|
|
## Overview
|
|
Augor is a Flutter desktop application that aggregates business and finance news feeds, clusters related articles into events, uses an LLM to assess likely market impact, and outputs a probabilistic growth signal for each event.
|
|
|
|
## MVP Goal
|
|
Deliver a working desktop prototype that:
|
|
- fetches articles from configured RSS/Atom feeds
|
|
- groups related reporting into event clusters
|
|
- asks an LLM to interpret each event cluster
|
|
- outputs a signal of `growth`, `decline`, or `neutral`
|
|
- includes a `probability` and `confidence` score
|
|
- displays results in the UI and exports them to JSON
|
|
|
|
## What Is In Scope For MVP
|
|
- RSS/Atom feed ingestion
|
|
- Embedding generation for articles
|
|
- Relevance filtering for business/finance news
|
|
- Event clustering using cosine similarity
|
|
- LLM event interpretation per cluster
|
|
- Signal generation: `growth`, `decline`, `neutral`
|
|
- Probability/confidence scoring
|
|
- Result display in Flutter UI
|
|
- JSON export of generated signals
|
|
|
|
## What Is Out Of Scope For MVP
|
|
- Backtesting
|
|
- Automated trading execution
|
|
- Backend/cloud processing
|
|
- Historical price-data integration
|
|
- Company/ticker extraction
|
|
- Multi-model comparison
|
|
- Advanced bias reduction or source weighting
|
|
|
|
## Runtime Components
|
|
- `lib/main.dart`
|
|
- App entrypoint.
|
|
- Loads persisted settings before rendering UI.
|
|
- Registers `SettingsProvider` in `MultiProvider`.
|
|
- Configures navigation with `go_router`.
|
|
- `lib/pages/home.dart`
|
|
- Main user flow trigger.
|
|
- Runs feed fetch, embedding generation, relevance filtering, grouping, LLM signal generation, export, and result rendering.
|
|
- `lib/pages/settings.dart`
|
|
- Settings UI for API key, feed list management, and output directory selection.
|
|
- `lib/providers/settings.dart`
|
|
- `ChangeNotifier` state container.
|
|
- Persists OpenRouter key, feed list, and storage path with `SharedPreferences`.
|
|
- `lib/utils/agrigator.dart`
|
|
- Feed parsing, feed retrieval, embeddings, relevance filtering, and event grouping.
|
|
- `lib/utils/openrouter.dart`
|
|
- OpenRouter API wrapper for embeddings and chat completions.
|
|
- `lib/utils/signal_generator.dart`
|
|
- Builds event-cluster prompts.
|
|
- Calls chat completions.
|
|
- Parses structured JSON into app signal models.
|
|
- `lib/models/event_signal.dart`
|
|
- Data model for a generated event signal.
|
|
- `lib/widgets/event_signal_card.dart`
|
|
- Displays one generated signal in the UI.
|
|
|
|
## MVP Data Flow
|
|
1. App startup loads persisted settings in `SettingsProvider.load()`.
|
|
2. User starts analysis from the Home page.
|
|
3. App builds the list of enabled feed URLs.
|
|
4. Feeds are fetched and parsed into `FeedItem`s.
|
|
5. Raw aggregated articles are exported to `aggregated_feed.json`.
|
|
6. Embeddings are generated for each article using `text-embedding-3-small`.
|
|
7. Enriched articles are exported to `enriched_aggregated_feed.json`.
|
|
8. Articles are filtered for business/finance relevance.
|
|
9. Relevant articles are exported to `relevant_aggregated_feed.json`.
|
|
10. Relevant articles are grouped into event clusters by cosine similarity.
|
|
11. Grouped readable output is exported.
|
|
12. Each event cluster is sent to an LLM prompt for interpretation.
|
|
13. The LLM returns structured JSON containing:
|
|
- `event_summary`
|
|
- `signal`
|
|
- `probability`
|
|
- `confidence`
|
|
- `rationale`
|
|
14. Parsed signals are displayed in the UI.
|
|
15. Signals are exported to `signals.json`.
|
|
|
|
## LLM Output Contract
|
|
Each analyzed event cluster must produce JSON in this shape:
|
|
|
|
```json
|
|
{
|
|
"event_summary": "short description of the event",
|
|
"signal": "growth",
|
|
"probability": 0.78,
|
|
"confidence": 0.71,
|
|
"rationale": "why this event suggests growth"
|
|
}
|
|
```
|
|
|
|
Allowed signal values:
|
|
- `growth`
|
|
- `decline`
|
|
- `neutral`
|
|
|
|
## MVP Build Order
|
|
1. Add `EventSignal` model.
|
|
2. Add `signal_generator.dart` for prompt building and LLM parsing.
|
|
3. Wire signal generation into `lib/pages/home.dart` after clustering.
|
|
4. Add basic signal result rendering in the UI.
|
|
5. Export generated signals to `signals.json`.
|
|
6. Validate the end-to-end flow in the desktop app.
|
|
|
|
## Current Constraints
|
|
- Processing is still UI-triggered and client-side only.
|
|
- No cancellation or progress reporting beyond basic UI state.
|
|
- No retry/backoff for network or model calls.
|
|
- No historical validation or backtesting in MVP.
|
|
- Quality of outputs depends on feed quality and LLM consistency.
|
|
|
|
## Definition Of Done For MVP
|
|
- User clicks the main action on Home.
|
|
- App fetches articles from enabled feeds.
|
|
- App groups related stories into events.
|
|
- App generates one interpreted signal per event cluster.
|
|
- UI shows event summary, signal, probability, confidence, and rationale.
|
|
- Signals are written to `signals.json` in the configured output directory.
|