FRED Navigator

Purpose

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

1. 1. Direct INLINECODE0
2. Direct INLINECODE1
3. Natural-language query → intent recognition → double validation

Inputs

• - category_id: FRED category id
• INLINECODE4: FRED series id
• INLINECODE5: natural language request
• INLINECODE6: number of candidates to return (default 5)
• INLINECODE7: read from environment FRED_API_KEY only

Required Resources

• - INLINECODE9
• INLINECODE10
• Optional: references/category_paths.json (precomputed)
• Optional: INLINECODE12
• Helper script: INLINECODE13
• Path builder: INLINECODE14

Optional Resource Structure Notes

• - references/category_paths.json format:

• - references/synonyms.json format:

Workflow

1. Category Exploration

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

2. Series Discovery

1. 1. Use search_by_category(category_id) to list available series.
2. Prefer scripts/fred_query.py category <id> for consistent output.
3. Return key columns:

3. Series Retrieval

1. 1. Use get_series(series_id) for time series.
2. Use get_series_info(series_id) for metadata.
3. Prefer scripts/fred_query.py series <id> and scripts/fred_query.py series-info <id>.
4. Provide:

4. Natural Language Query

4.1 Intent Identification (Top-K)

1. 1. Use the IDE agent (Codex) to interpret the natural-language intent.
2. Select the single best-matching category.
3. If confidence is low, ask the user to confirm the category before proceeding.
4. 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:

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:

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.