Weekend Planner – Next Feature Roadmap (Copilot Handoff)

[LuminLynx]

Weekend Planner – Next Feature Roadmap (Copilot Handoff)

This document defines the next iteration of enhancements for the Weekend Planner project.
All features must be additive — no breaking changes or removals of existing logic.

---

1️⃣ User Personalization

Goal: make the planner adapt to users’ preferences and past choices.

Files:

• app/config/settings.example.yaml
• app/utils/profile.py (new)
• app/ranking/scorer.py (extend)
• app/server.py (optional new route /user/preferences)

Tasks

• Add a small user profile loader/saver (~/.weekend_profile.json or in-memory dict).
• Fields: home_city, preferred_currency, max_distance_km, preferred_cuisines.
• Update scorer to apply small bonuses if dining matches preferred cuisines or itineraries start near home_city.
• Add /user/preferences route to read/update these fields (temporary JSON, not DB).

Acceptance

curl /user/preferences -X POST -d '{"home_city": "Berlin"}'
curl /plan/debug?... | jq ".debug.scoring_inputs.preferences"


---

2️⃣ Weather Awareness

Goal: enrich itineraries with live or forecasted weather.

Files:

app/connectors/weather.py (new)

app/config/settings.example.yaml


Tasks

Use a free API like Open-Meteo (no key needed).

Given latitude/longitude or city name → fetch min/max temperature + conditions.

Add field weather per itinerary ({"desc": "Sunny", "temp_c": 19}).

Cache for 2h TTL.

Display weather in debug and structured logs.


Acceptance

/plan/debug includes debug.weather block.

Log line includes "weather":"Sunny" etc.



---

3️⃣ Travel Distance & Carbon Estimate

Goal: show trip distance and footprint.

Files:

app/connectors/travel.py (new)

app/ranking/scorer.py (extend)


Tasks

For each itinerary, estimate travel distance (km) between home_city → event_city.

Compute CO₂ estimate (e.g., 0.15 kg/km per person for air, 0.04 for rail).

Add fields distance_km, co2_kg_pp.

Incorporate distance penalty and CO₂ awareness into score.


Acceptance

/plan/debug shows distance_km and co2_kg_pp.

Scoring logic penalizes long, high-emission trips (visible in ranking).



---

4️⃣ Itinerary Sharing

Goal: allow sharing a planned weekend via link or static snapshot.

Files:

app/server.py

app/utils/share.py (new)

docs/ (for static HTML output)


Tasks

Add /share/{plan_id} endpoint.

Store latest plan payload as a JSON under .cache/shared/{uuid}.json.

Render HTML using existing docs/app.html template (read-only view).


Acceptance

curl /share/<uuid> | grep "<title>"

Returns static HTML with offer cards.


---

5️⃣ Async Connector Pipeline

Goal: increase speed and concurrency.

Files:

app/connectors/*

app/main.py


Tasks

Switch from requests to httpx.AsyncClient.

Run FX, vendor, and dining connectors concurrently with asyncio.gather.

Preserve identical results and debug output shape.


Acceptance

/plan/debug latency reduced by ≥40%.

No behavior change compared to current synchronous version.



---

6️⃣ Metrics Endpoint

Goal: expose lightweight observability metrics for ops dashboards.

Files:

app/server.py

app/utils/metrics.py (new)


Tasks

Add /metrics route returning Prometheus-style text format.

Metrics: fx_live_latency_ms, cache_hit_ratio, vendor_a_latency_ms, planning_duration_ms.

Update each connector to record metrics via helper in metrics.py.


Acceptance

curl /metrics | grep fx_live_latency_ms

Returns current metrics values.


---

7️⃣ Offline Mode

Goal: make planner run without internet using last-known data.

Files:

app/connectors/*

app/utils/cache.py


Tasks

Add CLI flag --offline or env OFFLINE_MODE=true.

When set, skip all live HTTP calls and rely purely on cached/last_good data.

Expose debug.offline=true in response.


Acceptance

With OFFLINE_MODE=true, /plan/debug succeeds and sets "fx_source": "last_good" for all data.



---

8️⃣ CLI Interface

Goal: allow quick testing without server UI.

Files:

app/cli.py (new)

Makefile


Tasks

Add CLI entry point:

python -m app.cli plan --date 2025-12-12 --budget 250 --with-dining

Outputs concise table (no web UI).

Support --debug to print debug JSON.


Acceptance

make cli alias runs the planner successfully.



---

9️⃣ Config Schema Validation

Goal: prevent runtime errors from malformed YAML config.

Files:

app/utils/config.py (new)

pyproject.toml (add pydantic if not present)


Tasks

Define Pydantic model for settings.yaml (timeouts, TTLs, credentials, etc.).

Validate and log any missing or invalid fields with defaults applied.


Acceptance

Bad configs log warnings but do not crash.



---

🔟 CI/CD Improvements

Goal: ensure project quality on PRs and deploys.

Files:

.github/workflows/ci.yml (new)


Tasks

Add GitHub Actions pipeline that runs:

make lint

make test

Build Docker image and check size


Trigger on PR and push to main.


Acceptance

CI badge visible and passes on green.



---

🔄 Summary Deliverables

#	Feature	Key Output	Acceptance

1	Personalization	/user/preferences + profile-aware scoring	Curl + debug
2	Weather	Weather data per itinerary	/plan/debug
3	Travel/CO₂	distance & emissions	/plan/debug
4	Sharing	/share/{uuid} HTML	HTML served
5	Async	faster requests	latency drop
6	Metrics	/metrics endpoint	Prometheus text
7	Offline	cached-only mode	debug.offline
8	CLI	python -m app.cli	terminal output
9	Config validation	validated YAML	warnings logged
10	CI/CD	GitHub Actions workflow	badge green



---

Notes

All modules must maintain compatibility with /plan and /plan/debug.

Prefer adding new files under app/utils or app/connectors instead of rewriting.

New dependencies must be lightweight (httpx, pydantic, aiofiles allowed).

Document all new routes in README.md.



---

File name:
NEXT_FEATURES.md