FRED Navigator

Purpose

Provide a reliable workflow to navigate FRED categories and series, with support for:

• Direct category_id
• Direct series_id
• Natural-language query → intent recognition → double validation

Inputs

• category_id: FRED category id
• series_id: FRED series id
• query: natural language request
• limit: number of candidates to return (default 5)
• api_key: read from environment FRED_API_KEY only

Required Resources

• references/fred_categories_tree.json
• references/fred_categories_flat.json
• Optional: references/category_paths.json (precomputed)
• Optional: references/synonyms.json
• Helper script: scripts/fred_query.py
• Path builder: scripts/build_paths.py

Optional Resource Structure Notes

• references/category_paths.json format:
• { "category_id": { "id": , "name": "", "path": "" }, ... }
• references/synonyms.json format:
• { "concept": ["alias1", "alias2", ...], ... }

Workflow

1. Category Exploration

• Load fred_categories_tree.json for hierarchical browsing.
• If user provides category_id, validate it exists.
• If user provides category_name, fuzzy match against flat names and return candidates.

2. Series Discovery

• Use search_by_category(category_id) to list available series.
• Prefer scripts/fred_query.py category for consistent output.
• Return key columns:
• id, title, frequency, units, seasonal_adjustment, last_updated.

3. Series Retrieval

• Use get_series(series_id) for time series.
• Use get_series_info(series_id) for metadata.
• Prefer scripts/fred_query.py series and scripts/fred_query.py series-info .
• Provide:
• data head/tail
• missing counts
• latest value and date

4. Natural Language Query

#### 4.1 Intent Identification (Top-K)

• Use the IDE agent (Codex) to interpret the natural-language intent.
• Select the single best-matching category.
• If confidence is low, ask the user to confirm the category before proceeding.
• Use references/category_paths.json and references/synonyms.json as supporting context if available.

#### 4.2 Double Validation

Structural validation

• Candidate must exist in fred_categories_tree.json.
• Pass if at least one:
• children non-empty
• search_by_category(id) returns >= 1 series
• Prefer scripts/fred_query.py check-category for a quick check

Semantic validation (agent)

• Compare query with candidate name/path.
• Return pass/fail or numeric relevance score.

#### 4.3 Decision

• If structural + semantic validation both pass → accept category.
• Otherwise:
• return Top-5 candidates
• ask user to choose one explicitly

Failure Handling

• Always provide Top-5 candidates when uncertain.
• Never proceed to series retrieval if category validation fails.

Notes

• Do not hardcode API keys.
• Keep heavy reference data in references/, not in this file.
• When running Python functions for querying, execute them inside the sandbox environment.

Maintenance

• Update workflow or constraints: edit SKILL.md.
• Update category data: replace files in references/.
• Improve natural-language matching: add or edit references/synonyms.json (key → list of related terms).
• Regenerate precomputed paths (optional): run scripts/build_paths.py.
• Add helper scripts (optional): place in scripts/ and document usage here.