Species Research

WRONG vs CORRECT

❌ WRONG (combining everything into one blob):

{
  "claim_type": "cultural_significance",
  "claim_value": "Sacred in Buddhism, Confucianism, Taoism, and Shintoism. Buddhist monks preserved it. Hiroshima survivor trees are symbols of peace. Used in TCM for 5000 years.",
  "confidence": 0.85
}

This is ONE insight containing 5+ facts = WRONG

✅ CORRECT (atomic - one fact per insight):

[
  {
    "claim_type": "cultural_significance",
    "claim_value": {"text": "Sacred in Buddhism - monks preserved species through temple plantings for over 1000 years", "context": "Buddhism", "region": "East Asia"},
    "confidence": 0.95,
    "sources": [{"url": "https://...", "title": "Buddhist temple records", "type": "historical", "credibility": 0.88}]
  },
  {
    "claim_type": "cultural_significance",
    "claim_value": {"text": "Six trees survived 1945 Hiroshima atomic bomb within 2km of blast center, now symbols of peace", "context": "Hiroshima hibaku jumoku", "region": "Japan"},
    "confidence": 0.98,
    "sources": [{"url": "https://...", "title": "Hiroshima Peace Memorial", "type": "database", "credibility": 0.95}]
  },
  {
    "claim_type": "cultural_significance",
    "claim_value": {"text": "Leaves used in Traditional Chinese Medicine for memory and circulation for 2000+ years", "context": "TCM", "region": "China"},
    "confidence": 0.88,
    "sources": [{"url": "https://...", "title": "TCM pharmacopoeia", "type": "database", "credibility": 0.85}]
  },
  {
    "claim_type": "cultural_significance",
    "claim_value": {"text": "Sacred tree in Shintoism, planted at temples throughout Japan", "context": "Shintoism", "region": "Japan"},
    "confidence": 0.85,
    "sources": [{"url": "https://...", "title": "Japanese temple guide", "type": "cultural", "credibility": 0.82}]
  }
]

This is 4 insights for 4 distinct cultural facts = CORRECT

Expected Output

A well-researched species should have 50-80+ total insights across 35 fields:

• Single-value fields: ~20 insights (1 each)
• Multi-insight fields: ~30-60 insights (2-6 each)

If you only have ~35 insights (one per field), you are doing it wrong.

API Base URL

Local (on VM): http://localhost:3000 Remote (Djimo / external): https://treekipedia-api.silvi.earth

All examples below use $API as placeholder. Set it before starting:

API="http://localhost:3000"        # on the VM
API="https://treekipedia-api.silvi.earth"  # remote

Adaptive Research Workflow

Mode 1: Queue-driven (preferred for batch)

Pull from queue, research, save, mark complete. Prevents duplicate work across sessions.

STEP 1: Get next species

curl -s $API/research/queue/next

Response: {"queue_id": 1, "taxon_id": "AngMaMyMyRt39690-00", "species_name": "Myrtus communis", ...}

If queue_empty: true, all species are done.

STEP 2: Mark as processing (locks it so other sessions skip it)

curl -s -X POST $API/research/queue/{queue_id}/start

STEP 3: Get research context

curl -s $API/research/{taxon_id}/context

Returns recommended_focus ("full" for first research, "gaps" for re-research), priority_fields, skip_fields, and existing insight count.

STEP 4: Conduct research — web search all 35 fields, build atomic insights (see below).

STEP 5: Save insights

curl -s -X POST $API/research/{taxon_id}/save \
  -H "Content-Type: application/json" \
  -d '{"model_version": "claude-opus-4-5-20251101", "insights": [...]}'

Response: {"success": true, "insights_saved": 73, "average_confidence": 0.873, "version": 1}

STEP 6: Mark complete

curl -s -X POST $API/research/queue/{queue_id}/complete

STEP 7: Loop — go back to STEP 1 until queue is empty.

Mode 2: Direct (for a specific taxon_id)

If ARGUMENTS provides a taxon_id, skip the queue and research that species directly (steps 3-5 only). Useful for one-off research or re-research.

Research Modes (from context endpoint)

The 35 Research Fields

Identity (4 fields)

• popular_common_name - Most widely-used name + regional variants
• etymology - Meaning of scientific name (Latin/Greek roots)
• synonyms - All taxonomic synonyms from POWO/WCVP
• identification_features - Key visual ID features

Ecological (10 fields)

• general_description - 2-4 sentence botanical description
• habitat - MULTI-INSIGHT: One per habitat type
• elevation_ranges - Actual recorded elevations (meters)
• ecological_function - MULTI-INSIGHT: One per ecosystem service
• native_adapted_habitats - MULTI-INSIGHT: One per region
• conservation_status - IUCN + national listings
• compatible_soil_types - Specific soil preferences
• climate_tolerance - Temperature extremes + rainfall requirements
• tolerances - MULTI-INSIGHT: One per tolerance type
• associated_species - MULTI-INSIGHT: One per community type

Morphological (10 fields)

• growth_form - Tree/shrub/multi-stemmed + variations
• leaf_type - Complete leaf description
• deciduous_evergreen - Note climate variation
• flower_color - With flowering season
• fruit_type - Complete fruit/seed info
• bark_characteristics - How bark changes with age
• maximum_height - Maximum + typical range (meters)
• maximum_diameter - DBH measurements (cm)
• lifespan - Typical vs maximum (years)
• maximum_tree_age - Oldest recorded specimen

Stewardship (11 fields)

• stewardship_best_practices - MULTI-INSIGHT: One per practice
• planting_recipes - Detailed planting instructions
• pruning_maintenance - When and how to prune
• disease_pest_management - MULTI-INSIGHT: One per disease/pest
• fire_management - Fire ecology and management
• propagation_methods - All viable methods
• cultural_significance - MULTI-INSIGHT: One per culture/tradition
• agroforestry_use_cases - MULTI-INSIGHT: One per use case
• timber_value - Wood properties and commercial value
• non_timber_products - MULTI-INSIGHT: One per product category
• nutritional_caloric_value - Edible parts and nutrition

Insight JSON Structure

{
  "claim_type": "field_name",
  "claim_value": {
    "text": "The specific fact being claimed",
    "context": "Category within the field (for multi-insight fields)",
    "region": "Geographic scope if applicable"
  },
  "methodology": "extraction",
  "sources": [
    {
      "url": "https://source-url.com/...",
      "title": "Source Title",
      "type": "database|journal|government|cultural|grey_literature",
      "credibility": 0.90
    }
  ]
}

Note: Do NOT include confidence in your insights. The orchestrator calculates evidence-based confidence from your sources automatically.

Search Strategy

Core Searches (every species)

"{species}" POWO OR WCVP taxonomy accepted name
"{species}" IUCN conservation status assessment
"{species}" GBIF distribution native range
"{species}" ecology habitat ecosystem biome
"{species}" morphology height diameter bark leaf flower fruit
"{species}" traditional use ethnobotany medicinal cultural
"{species}" cultivation propagation planting agroforestry
"{species}" timber wood properties uses

Grey Literature

"{species}" filetype:pdf site:.edu OR site:.gov
"{species}" dissertation OR thesis
"{species}" site:fao.org OR site:worldagroforestry.org

Source Credibility Tiers

Key Endpoints ($API = http://localhost:3000 or https://treekipedia-api.silvi.earth)

Remember

1. ATOMIC INSIGHTS - Split multi-value fields into separate insights
2. 50-80+ insights expected per well-documented species
3. If you only have ~35 insights, you're doing it wrong
4. CHECK CONTEXT FIRST - Call $API/research/{taxon_id}/context before researching
5. ADAPT your research based on recommended_focus
6. Don't include confidence - orchestrator calculates it from sources
7. Search HARDER for poorly documented species
8. USE THE QUEUE for batch work — it prevents duplicate effort across sessions