Medical Vector Search

Source: https://github.com/aipoch/medical-research-skills

Medical Research Vector Search Skill

Skill Objective

When users ask medical research questions, intelligently rewrite queries and call the vector knowledge base to retrieve the most relevant document segments, then provide evidence-backed answers. This ensures answers come from a reliable knowledge base rather than solely from model internal knowledge.

Workflow

Step 1: Rewrite User Question into High-Quality Search Query

Before calling the API, rewrite the user's original question into a professional query suited for vector retrieval. The purpose is to improve recall, as colloquial questions often fail to match professional expressions in documents.

Rewriting principles:

• Extract core medical concepts, use standardized professional terminology
• Remove interrogative tone, convert to declarative keyword combinations
• If the original question is vague, expand to include related concepts
• Keep queries concise, focusing on key concepts (10-30 words typically works best)

Rewriting examples:

Step 2: Call Vector Database Search API

The skill directory contains a pre-packaged search script scripts/search.py - call it directly:

python scripts/search.py "<rewritten query>"

The script automatically outputs relevance scores, source titles, and document content segments.

You can also import its search() function directly in Python code:

from scripts.search import search

results = search("<rewritten query>")

API parameters (fixed, no modification needed):

| Parameter | Value | Description | | --- | --- | | collection_alias | wiki_production | Knowledge base to search | | search_method | hybrid_search | Hybrid retrieval (vector + keyword) | | alpha | 0.7 | Vector weight 70% | | score_threshold | 0.1 | Minimum relevance threshold | | limit | 10 | Return max 10 results |

Step 3: Parse Results and Generate Answer

• Prioritize organizing answers based on high-relevance documents (score > 0.3)
• Use [1], [2] citation markers in the text (merge numbers when multiple passages cite the same document)
• List all citations at the end in reference format using Markdown hyperlinks, with helix_wiki_knowledge_name as link text and helix_wiki_node_url as URL:

**References**
[1] [Protein-Protein Interaction Research - Basic Research Elements](https://helixwiki.newidea.pro/xxx)
[2] [Introduction to Research Design - Basic Scientific Research Elements and Logic](https://helixwiki.newidea.pro/yyy)

URL comes from the child_chunks[0].properties.metadata.helix_wiki_node_url field in each API result.

• If different results share the same URL, merge into a single reference entry
• If relevance is low or results are insufficient, honestly state this and supplement with model knowledge (without citation markers)

Example Use Cases

• Research platform feature usage (e.g., review workbench, literature management)
• Medical literature search and review methodology
• Clinical trial design and statistical methods
• Drug mechanisms of action and side effects
• Disease diagnosis and treatment guidelines
• Biomedical experimental techniques (PCR, sequencing, flow cytometry, etc.)
• Bioinformatics analysis methods
• Medical writing and submission guidelines

Important Notes

• Never directly answer complex medical research questions without searching first — search-then-answer is the core value of this skill
• For very basic common knowledge questions (e.g., 'what is DNA'), a brief direct answer is acceptable, but deep questions must always be searched
• If first search results are unsatisfactory, try changing the query angle — e.g., switch to English terminology or split into multiple sub-queries

When to Use

• Use this skill when the user explicitly needs to perform the core task of medical-vector-search and has provided the minimum executable input.
• Use this skill when you need a structured deliverable rather than general advice.
• Use this skill when the current task can be completed using this skill's bundled scripts, templates, or reference materials.

When Not to Use

• Do not proceed when required input files, identifiers, parameters, or context are missing — ask the user to provide them first.
• Do not assume capabilities beyond this skill's declared scope when the user requests external operations or inferences.
• Do not proceed without user confirmation when overwriting existing results, executing high-cost batch operations, or expanding task scope.

Required Inputs

Output Contract

• Primary output: Structured result or target file aligned with this skill's objective.
• Optional output: Intermediate check notes, issue list, supplementary suggestions, or generated file paths.
• Format requirement: Unless the user specifies otherwise, prefer stable, reviewable Markdown or JSON; if the skill's bundled script requires a fixed format, use that format.
• If partially complete: Must explicitly mark as PARTIAL and state which steps are completed and which remain.

Failure Handling

• Missing critical input: Explicitly state which fields, files, or identifiers are missing and pause.
• Script, template, or resource execution failure: Report the failing step, likely cause, and recovery suggestions — do not silently degrade.
• Partial completion only: Return the verified portion first, then list remaining blockers and suggested next steps.

User Checkpoints

• Before executing batch processing, overwriting files, long-running searches, or multi-stage generation, confirm scope and output format with the user.
• Before proceeding when a key judgment is ambiguous, evidence is insufficient, or the workflow is entering the next stage, confirm with the user.

Input Validation

This skill accepts requests that match the documented purpose of medical-vector-search and include enough context to complete the workflow safely.

Do not continue the workflow when the request is out of scope, missing a critical input, or would require unsupported assumptions. Instead respond:

medical-vector-search only handles its documented workflow. Please provide the missing required inputs or switch to a more suitable skill.

Quick Validation

• Check that key scripts, templates, or reference file paths this skill depends on exist.
• Check that the final output contains the core fields, sections, or files specified for this task.
• Check that results clearly mark assumptions, limitations, and incomplete items.