hyperindex

name	hyperindex
description	Search and browse biodiversity records and hypercerts on the Hypersphere network. Use when users ask about existing observations, want to see community records, or search for species data.

Hyperindex

When to Use

• User asks 'what have we recorded?' or 'show me our observations'
• User asks about a specific species across the network
• User wants to see hypercerts/bumicerts or impact certificates
• User asks 'how many records do we have?'
• User asks 'how many have I done?' or 'show me my observations'

How to Use

• For community records: use type='occurrences' with the community DID
• For species search: use type='search' with the species name
• For browsing: use type='occurrences' without a DID filter
• Keep limit reasonable (5-10 for display, up to 20 for counts)

User-specific queries

When a user asks about THEIR observations ('how many have I done?', 'show me mine'):

1. Use type='occurrences' with the community DID
2. Set recordedByContains to "tg:<user_telegram_id>" — the user's Telegram ID is in every message you receive (e.g. tg:6224264108)
3. This filters server-side — fast and accurate, returns totalCount too
4. Do NOT ask the user for their DID — you already have their Telegram ID from the message
5. NEVER invent a DID for the user (e.g. did:telegram:xxx) — that's not a real thing
6. NEVER try client-side filtering — use recordedByContains instead

Presentation (HTML for Telegram)

Format results using HTML tags, not Markdown. Use emoji for visual structure.

For occurrences:

🌺 <b>Bougainvillea spectabilis</b> <i>(Buganvilla)</i>
   📍 Nairobi · 📅 26 mar 2026
   🔗 <a href="https://hyperscan.gainforest.app/...">Ver en Hyperscan</a>

🌳 <b>Ficus thonningii</b>
   📍 Kampala · 📅 26 mar 2026

For summaries: 'Hemos registrado 23 especies! Aquí van las más recientes...' For user-specific: 'Has registrado 5 observaciones! 🎉'

Don't

• Don't dump raw JSON or URIs on the user
• Don't show DIDs — they're internal identifiers
• Don't show more than 5 records at a time unless asked
• Don't query without a purpose — always in response to a user question
• Don't ask the user for their DID — you already know who they are from the message context
• Don't use Markdown formatting (bold, italic) — use HTML (, , )