v1.8.1

Release v1.8.1

• rewrite tool descriptions (run_query, search_terms, get_term_info)
  with explicit workflow rules and search filter recipes
• self-healing run_query errors: on failure, fetch get_term_info and
  embed the actual valid Queries array in the error message
• document RelatedTools field in get_term_info and LLM_GUIDANCE.md;
  surfaces get_hierarchy, find_stocks, find_combo_publications with
  copy-ready default_args
• LLM_GUIDANCE.md "READ THIS FIRST" three-rule preamble plus
  stage-agnostic search filter cookbook

v1.8.0

Highlights

• Hierarchy display: render class/instance hierarchies in tool output
• Hierarchy guidance: LLM instructions for navigating and querying hierarchies
• Instance-level queries on classes: guidance for instance-level queries scoped to class terms
• Improved connectivity guidance: clarified cross-dataset comparative usage of query_connectivity
• Bump package and runtime version metadata to 1.8.0

Commits since v1.7.4

• 4656125 display of hierarchies
• 11fac66 instructions for hierarchies
• fd0ded3 instructions for instance-level queries on classes
• 030566c improve connectivity guidance
• e2e6d01 Merge pull request #2 from VirtualFlyBrain/clare-testing

v1.7.4

Release v1.7.4

• require unresolved user text for resolve_entity and resolve_combination instead of resolved IDs
• add guardrails that return corrective errors when FlyBase or VFB IDs are passed to resolve tools
• update MCP guidance, README, examples, and HTTP landing-page copy to show the correct workflow
• bump package and runtime version metadata to 1.7.4

v1.7.3

What's Changed

Connectivity tool clarity & reliability

• Clarified query_connectivity as a cross-dataset comparative connectomics tool — description now explains it queries across ALL connectome datasets simultaneously, supports filtering at both upstream AND downstream ends by neuron class, and is not pre-cached (live queries)
• Added 5-minute axios timeout for query_connectivity to prevent premature disconnection on slow cross-dataset queries
• Performance guidance: recommend weight ≥ 50 for both-ends queries to avoid timeouts; suggest group_by_class=true for faster aggregated results

LLM Guidance improvements

• Added "Choosing the Right Connectivity Tool" comparison table to LLM_GUIDANCE.md, clearly distinguishing:
  • query_connectivity — neuron class to class, cross-dataset, live comparative data
  • run_query + NeuronNeuronConnectivityQuery — single individual neuron, pre-computed, fast
• Added performance notes section with practical advice for query parameter tuning

Previous releases in this series

• v1.7.2: Fixed upstream API parameter names for 4 VFBquery endpoints (resolve_entity, resolve_combination, find_stocks, find_combo_publications)
• v1.7.1: Aligned all tool descriptions and LLM guidance with ask-vfb skill patterns (confirmation flows, result presentation, error recovery, follow-up suggestions)

Full Changelog: v1.7.0...v1.7.3

v1.7.2

Bug Fixes

• Fix upstream API parameter mismatches — 4 VFBquery endpoint handlers were sending incorrect query parameter names to the upstream ha_api.py, causing 400 errors:
  • resolve_entity: name= → query=
  • resolve_combination: name= → query=
  • find_stocks: feature_id= → id=, collection_filter= → collection=
  • find_combo_publications: fbco_id= → id=

Documentation (from v1.7.1)

• Enhanced tool descriptions for all 6 VFBquery tools (resolve_entity, find_stocks, resolve_combination, find_combo_publications, list_connectome_datasets, query_connectivity) — aligned with ask-vfb skill patterns including tiered resolution, user confirmation workflows, result presentation rules, and follow-up suggestions
• Expanded LLM_GUIDANCE.md with detailed workflow sections:
  • FlyBase Entity Resolution & Stocks Workflow
  • Split-GAL4 Combination Publications Workflow
  • Connectivity Query Workflow (with parameter inference table, relaxation loop, and result handling)
  • Cross-tool Patterns (tiered resolution, disambiguation, link conventions, error recovery, tool chaining)

v1.7.1 — Aligned tool guidance with ask-vfb skill patterns

What's Changed

Enhanced Tool Descriptions (6 tools)

All VFBquery tool descriptions have been significantly expanded to guide LLMs through proper usage patterns, matching the detailed skill definitions in ask-vfb:

• resolve_entity — Now documents accepted input types (GAL4 names, split-GAL4 synonyms, cell type labels, gene symbols, FlyBase IDs), tiered resolution strategy (exact → synonym → broad), and the critical instruction to confirm SYNONYM/BROAD matches with the user before proceeding
• find_stocks — Documents ID type routing (FBgn/FBal/FBti/FBco/FBst), gene query's 4 search paths, result presentation rules (≤30 full table, >30 top 20 + collection breakdown), and FlyBase report link formats
• resolve_combination — Documents accepted formats (formal names, synonyms like "MB002B"/"SS04495", FBco IDs), tiered resolution, and user confirmation requirements
• find_combo_publications — Documents returned fields (FBrf, title, year, miniref, DOI, PMID, PMCID), link formats for FlyBase/DOI/PubMed, and tool chaining from resolve_combination
• query_connectivity — Documents constraints (neuron classes only, not regions/individuals/muscles), recommended defaults (weight=5, exclude_dbs=["hb","fafb"]), zero-result relaxation strategy, and parameter confirmation workflow
• list_connectome_datasets — Documents relationship to exclude_dbs parameter and common dataset symbols

Expanded LLM Guidance

LLM_GUIDANCE.md now includes four detailed workflow sections (replacing the previous thin "Additional VFBquery Endpoints" section):

1. FlyBase Entity Resolution & Stocks Workflow — Full workflow with ID routing table, confirmation patterns, result presentation rules, and follow-up offers
2. Split-GAL4 Combination Publications Workflow — Resolution, confirmation, publication presentation with links, and follow-up suggestions
3. Connectivity Query Workflow — Query mode inference table, parameter confirmation, neuron type validation, result handling (per-neuron vs class mode), zero-result relaxation loop, and follow-up offers
4. Cross-tool Patterns — Tiered resolution, disambiguation, link conventions, error recovery, and tool chaining patterns

Key Behavioural Patterns Now Documented

• User confirmation on synonym matches — All resolve tools now instruct LLMs to stop and confirm with the user when a match is found via synonym rather than exact name
• Disambiguation lists — Guidance to present numbered lists when multiple matches are found
• Result presentation rules — Size-based truncation (stocks: 30 rows, connectivity: 50 rows) with summary statistics
• Zero-result relaxation — Step-wise constraint relaxation for connectivity queries
• Tool chaining — Documented flows: resolve_entity → find_stocks, resolve_combination → find_combo_publications, search_terms → query_connectivity

Full Changelog: v1.7.0...v1.7.1

v1.7.0

Add VFBquery endpoints (resolve_entity, find_stocks, resolve_combination, find_combo_publications, list_connectome_datasets, query_connectivity) and update docs/examples for new tool usage.

Full Changelog: v1.6.2...v1.7.0

v1.6.2

What's Changed

• Removed IP diagnostic dump (X-Forwarded-For confirmed working after HAProxy option forwardfor fix)
• Client IP now correctly logged in server logs and GA4 analytics via X-Forwarded-For header

v1.6.1

What's Changed

IP diagnostic logging

• Dumps all IP-related request headers on tools/list calls to help diagnose HA proxy forwarding
• Checks: x-forwarded-for, x-real-ip, cf-connecting-ip, true-client-ip, x-client-ip, forwarded, x-original-forwarded-for, req.ip, req.ips, req.socket.remoteAddress, plus full headers
• This is a diagnostic release — the dump will help determine which header (if any) HA proxy is using to forward the real client IP

v1.6.0

What's New

Batch support for get_term_info and run_query

• get_term_info: id parameter now accepts a single string or an array of strings — multiple IDs are fetched in parallel and returned as a JSON object keyed by ID
• run_query: accepts an array of IDs with a shared query_type, or a queries array of {id, query_type} pairs for mixed batch queries — results keyed by "ID::query_type"
• Single-call responses are unchanged (fully backward compatible)

Client IP logging

• Extracts originating client IP from X-Forwarded-For / X-Real-IP headers (for HA reverse proxy)
• Client IP included in server console logs and GA4 analytics events

Improved analytics

• GA4 events expanded for batch calls: one event per individual ID/query with batch_size and batch_index fields
• Per-request console logging for each upstream API call (id=, query_type=, success/error status)