Skip to content

About

Agentic morning-run planner: checks calendar, free time, and weather, then picks a trail from an approved CSV list — showing its full working before every answer

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Trail-Scout 🏃🌲

An agentic app that plans your morning trail run. Every time it fires, the agent:

  1. Checks your calendar for the morning's schedule
  2. Works out how much free time you have before your first meeting (with a get-ready buffer)
  3. Checks the weather — Sunny, Shaded, or Cloudy
  4. Reads the approved-trails CSV (hike name, length, strenuous level, surrounding type)
  5. Suggests one trail that fits your time window and the weather, plus alternatives

The answer never appears alone — Trail-Scout prints its full working first. In agent mode you see every tool call and result live; in rule-based mode you get a step-by-step trace (calendar read, window math, weather, and the score for every trail) before the final pick. Add --quiet to skip the trace.

It runs in two modes:

Mode When How it decides
Claude agent ANTHROPIC_API_KEY is set A Claude tool-use loop (claude-opus-4-8 via the Anthropic SDK tool runner) calls the four tools and reasons about the best pick
Rule-based fallback No API key, or --no-llm Deterministic scoring: filter trails by estimated duration vs. free minutes, then rank by weather↔surroundings fit

All data sources are dummy/mock by design — swap them for real ones later (see Extending).

Quickstart

git clone https://github.com/abankar1/Trail-Scout.git
cd Trail-Scout
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

python main.py

Sample output (rule-based mode — the decision trace always comes before the answer):

Trail-Scout — morning run plan for 2026-07-17
====================================================
How this suggestion was made:
Step 1/4  Read calendar for 2026-07-17: 3 morning event(s) before 12:00.
          - 08:30-09:00  1:1 with manager
          ...
Step 2/4  Compute free window: wake-up 06:30 -> 07:45 (first event '1:1 with
          manager' at 08:30; includes a 45-min get-ready buffer) = 75 min for a run.
Step 3/4  Check weather: Sunny [mock (deterministic by date)].
Step 4/4  Evaluate 32 approved trails from data/trails.csv (assumed pace, min/km: ...):
          + Whispering Pines Loop: ~65 min fits; weather-fit 2/2 (shaded cover is
            ideal in direct sun); window-use 0.87 -> score 2.87.
          x Highland Traverse: 10.4 km Strenuous ~104 min — does NOT fit the 75-min window.
          ...
Decision  Rank by score (weather fit + share of window used): ...
----------------------------------------------------
Weather:   Sunny (mock (deterministic by date))
Free time: 75 min (06:30-07:45)

>> Whispering Pines Loop — 8.2 km, Moderate, Shaded forest (~65 min)

Options

python main.py --date 2026-07-19      # plan another day
python main.py --no-llm               # force the rule-based recommender
python main.py --quiet                # suggestion only, skip the decision trace
WEATHER=Cloudy python main.py         # override the mock weather

Enabling the Claude agent

export ANTHROPIC_API_KEY=sk-ant-...
python main.py

The agent defines four tools (get_morning_schedule, get_available_time, get_weather, get_approved_trails) and lets Claude drive the loop until it lands on a suggestion. Every tool call and its result is printed live ([call] / [tool] lines) so you watch the agent gather its evidence before it answers, and the model is instructed to show its working — window, weather, ruled-in/ruled-out trails — ahead of the final pick. If the API call fails for any reason, the CLI falls back to the rule-based recommender automatically.

Data (all dummy, regenerable)

File Contents
data/trails.csv 32 approved trails: Hike Name, Length (km), Strenuous Level, Surrounding Type
data/calendar.json Two weeks of fake calendar events starting from generation day

Regenerate anytime:

python scripts/generate_data.py

Run it daily (GitHub Actions)

.github/workflows/daily-suggestion.yml runs the agent every morning (05:30 UTC) and on manual dispatch, writing the suggestion to the workflow run summary. It works with zero secrets in rule-based mode; add an ANTHROPIC_API_KEY repo secret to run the Claude agent instead.

Project layout

main.py                    CLI entry point
trail_scout/
  tools.py                 Data sources: calendar, time window, weather, CSV trails
  agent.py                 Claude tool-use loop (Anthropic SDK tool runner)
  recommend.py             Rule-based fallback recommender
scripts/generate_data.py   Dummy-data generator
data/                      trails.csv + calendar.json (committed dummy data)

Extending

  • Real calendar — replace get_morning_schedule() in trail_scout/tools.py with a Google Calendar / CalDAV fetch; the agent and fallback both consume the same shape.
  • Real weather — swap get_weather() for a free API like Open-Meteo and map conditions onto Sunny/Shaded/Cloudy.
  • Your trails — edit data/trails.csv directly; the header row is the only contract.
  • Pace tuning — adjust PACE_MIN_PER_KM in tools.py to your own pace per difficulty level.

License

MIT

About

Agentic morning-run planner: checks calendar, free time, and weather, then picks a trail from an approved CSV list — showing its full working before every answer

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages