Epidbot

Interact with EpidBot - AI-powered assistant for Brazilian public health data (DATASUS/SINAN)

Security Scan

The skill's declared requirements (API key + base URL) and instructions are generally consistent with a remote EpidBot REST API integration, with only minor documentation inconsistencies that should be checked before use.

Purpose & Capability

The skill's name/description (agent access to EpidBot for Brazilian public health data) aligns with the required environment variables (EPIDBOT_API_KEY, EPIDBOT_BASE_URL) and the documented REST/WebSocket endpoints. No unrelated credentials or unusual system access are requested.

Instruction Scope

SKILL.md stays within the scope of calling EpidBot APIs (chat submit/poll, sessions, websockets) and describes server-side behaviors (data downloads, SQL runs). However, examples assume presence of local tools (jq) that are not listed in bins/required binaries, and the doc shows a username/password login flow (returns JWT) even though only API key is declared as required—this could confuse implementers about what credentials the agent may prompt for.

Install Mechanism

This is an instruction-only skill with no install spec or downloaded code. That minimizes on-disk risk; nothing is fetched or executed by the skill package itself.

Credentials

The declared env vars (EPIDBOT_API_KEY, EPIDBOT_BASE_URL) are proportional to the stated purpose. Two minor issues: (1) the WebSocket example places the API key in the query string (wss://.../chat/stream?api_key=...), which increases the risk of leakage in logs or referrers; (2) a username/password login flow is documented but username/password are not listed as required env vars—this is likely optional but should be clarified.

Persistence & Privilege

The skill does not request permanent/always-on presence and has no install-time hooks. It does not request access to system config paths or other skills' credentials.

Assessment

This skill appears to be what it says: a thin wrapper describing how to call EpidBot's API. Before installing, confirm you trust the EpidBot service and its homepage (the registry lists a GitHub repo). Protect your EPIDBOT_API_KEY (it's placed in examples and in a websocket URL — avoid sharing logs that include it). Note the examples use jq but jq isn't declared as required; ensure your agent environment has the needed CLI tools. If you may enter username/password credentials, know those produce JWT tokens per the docs — decide whether you prefer API keys. Finally, because the service deals with public health data, verify compliance with any local data-privacy rules before sending sensitive datasets.

EpidBot OpenClaw Skill

Enables AI agents to interact with EpidBot's REST API for analyzing Brazilian public health data. EpidBot uses natural language processing to help users query, download, and analyze health data from DATASUS.

Overview

EpidBot provides access to:

• Brazilian health data: SINAN disease notifications, SIM mortality, SIH hospital admissions
• International data sources: WHO, PAHO, HealthData.gov, World Bank, ECDC
• Data analysis: Temporal trends, spatial distribution, demographic breakdowns
• Visualizations: Charts, maps, heatmaps, and reports
• SQL queries: Execute DuckDB SQL on parquet files

Authentication

Option 1: API Key (Recommended for agents)

1. Login to EpidBot web interface at https://epidbot.kwar-ai.com.br
2. Go to Admin Panel -> API Keys -> Create new API key
3. Set the API key as an environment variable:

export EPIDBOT_API_KEY="your-api-key-here"
export EPIDBOT_BASE_URL="https://api.epidbot.kwar-ai.com.br"

Option 2: Username/Password (Returns JWT tokens)

curl -X POST "$EPIDBOT_BASE_URL/api/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"username": "user", "password": "pass"}'

# Response:
# {
#   "access_token": "eyJ...",
#   "refresh_token": "eyJ...",
#   "token_type": "bearer",
#   "expires_in": 900
# }

API Base URL

Default: https://api.epidbot.kwar-ai.com.br/api/v1

Configure via EPIDBOT_BASE_URL environment variable.

Quick Examples

Check API Health

curl -H "X-API-Key: $EPIDBOT_API_KEY" \
  "$EPIDBOT_BASE_URL/api/v1/health"

Send a Chat Message (Async Submit + Poll)

Chat messages are processed asynchronously. Submit a message to get a job_id, then poll for the result.

Important: EpidBot queries may invoke data downloads, SQL execution, and LLM reasoning. Responses typically take 30 seconds to 3 minutes, and complex queries involving large datasets can take up to 5 minutes. Use exponential backoff when polling (start at 3s, double each interval up to 30s, max total wait 5 minutes).

# Step 1: Submit the message (returns immediately with job_id)
JOB=$(curl -s -X POST "$EPIDBOT_BASE_URL/api/v1/chat" \
  -H "X-API-Key: $EPIDBOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "Show me dengue cases in São Paulo for 2023", "locale": "en"}')

JOB_ID=$(echo $JOB | jq -r '.job_id')

# Step 2: Poll for result with exponential backoff
INTERVAL=3
MAX_WAIT=300  # 5 minutes
ELAPSED=0
while [ "$ELAPSED" -lt "$MAX_WAIT" ]; do
  RESULT=$(curl -s "$EPIDBOT_BASE_URL/api/v1/chat/$JOB_ID" \
    -H "X-API-Key: $EPIDBOT_API_KEY")
  STATUS=$(echo $RESULT | jq -r '.status')
  if [ "$STATUS" = "completed" ] || [ "$STATUS" = "failed" ]; then
    echo $RESULT | jq .
    break
  fi
  sleep $INTERVAL
  ELAPSED=$((ELAPSED + INTERVAL))
  INTERVAL=$((INTERVAL * 2))
  if [ "$INTERVAL" -gt 30 ]; then
    INTERVAL=30
  fi
done

List Available Tools

curl -H "X-API-Key: $EPIDBOT_API_KEY" \
  "$EPIDBOT_BASE_URL/api/v1/tools"

Tools / Capabilities

chat (async submit)

Submit a chat message for async processing. Returns a job_id immediately. LLM responses typically take 5-120 seconds.

Request:

{
  "message": "What data is available for dengue in 2023?",
  "session_id": null,
  "locale": "en"
}

Submit Response (200):

{
  "job_id": "job_a1b2c3d4...",
  "session_id": 1,
  "status": "processing"
}

chat_poll

Poll for the status and result of a chat job. Endpoint: GET /api/v1/chat/{job_id}

Recommended polling: exponential backoff starting at 3s, doubling up to 30s, max total wait 5 minutes. Responses may take 30s–3min for simple queries, up to 5min for complex data analysis.

Poll Response -- still processing:

{
  "job_id": "job_a1b2c3d4...",
  "status": "processing",
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:05Z"
}

Poll Response -- completed:

{
  "job_id": "job_a1b2c3d4...",
  "status": "completed",
  "session_id": 1,
  "content": "EpidBot has access to SINAN dengue data for 2023...",
  "images": ["![plot](plots/abc.png)"],
  "thinking": "The user is asking about available data...",
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:45Z"
}

Poll Response -- failed:

{
  "job_id": "job_a1b2c3d4...",
  "status": "failed",
  "error": "Error message description",
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:10Z"
}

chat_stream (WebSocket)

For streaming responses, connect via WebSocket at:

wss://api.epidbot.kwar-ai.com.br/api/v1/chat/stream?api_key=<your-api-key>

Client -> Server Messages:

{"type": "start", "payload": {"message": "...", "session_id": null, "locale": "en"}}
{"type": "cancel"}
{"type": "ping"}

Server -> Client Messages:

{"type": "thinking", "data": {"content": "..."}}
{"type": "chunk", "data": {"content": "..."}}
{"type": "complete", "data": {"content": "...", "images": [], "usage": {...}}}
{"type": "error", "data": {"error": "..."}}
{"type": "cancelled"}
{"type": "pong"}

list_sessions

List all chat sessions for the authenticated user.

Endpoint: GET /api/v1/sessions

Output:

[
  {
    "id": 1,
    "name": "Dengue Analysis",
    "message_count": 12,
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-02T00:00:00Z"
  }
]

get_session_messages

Get message history for a specific session.

Endpoint: GET /api/v1/sessions/{session_id}/messages

Output:

{
  "session_id": 1,
  "messages": [
    {
      "id": 1,
      "role": "user",
      "text_content": "Show me dengue data",
      "thinking": null,
      "created_at": "2024-01-01T00:00:00Z"
    },
    {
      "id": 2,
      "role": "assistant",
      "text_content": "Here is the dengue data...",
      "thinking": "The user is asking about...",
      "created_at": "2024-01-01T00:00:01Z"
    }
  ]
}

list_reports

List all generated reports.

Endpoint: GET /api/v1/reports

Output:

[
  {
    "id": 1,
    "title": "Dengue Analysis 2023",
    "report_type": "analysis",
    "image_count": 3,
    "content_size_bytes": 15234,
    "has_pdf": true,
    "created_at": "2024-01-01T00:00:00Z"
  }
]

get_report

Get full details of a specific report.

Endpoint: GET /api/v1/reports/{report_id}

Output:

{
  "id": 1,
  "title": "Dengue Analysis 2023",
  "report_type": "analysis",
  "prompt": "Show me dengue cases...",
  "content": "# Dengue Analysis\n\n...",
  "image_count": 3,
  "content_size_bytes": 15234,
  "has_pdf": true,
  "created_at": "2024-01-01T00:00:00Z"
}

download_report

Download report as a markdown file.

Endpoint: GET /api/v1/reports/{report_id}/download

Output: File download with Content-Disposition header.

list_tools

List all available agent tools with descriptions.

Endpoint: GET /api/v1/tools

Output:

[
  {
    "name": "download_sinan_data",
    "description": "Download SINAN disease notification data for a given disease",
    "parameters": null
  },
  {
    "name": "execute_sql_query",
    "description": "Execute a SQL query on the health database",
    "parameters": null
  },
  {
    "name": "get_temporal_trend",
    "description": "Calculate temporal trend for a dataset",
    "parameters": null
  }
]

Error Handling

All endpoints may return errors:

{
  "detail": "Error message description"
}

Common Status Codes:

• 400 - Bad Request (invalid input)
• 401 - Unauthorized (missing/invalid authentication)
• 403 - Forbidden (valid auth but insufficient permissions)
• 404 - Not Found
• 429 - Too Many Requests
• 500 - Internal Server Error

Agent Usage Patterns

Pattern 1: Async Chat (Submit + Poll) -- Recommended

Agent: POST /chat -> get job_id -> poll GET /chat/{job_id} with exponential backoff (3s, 6s, 12s, 24s, 30s, 30s...) -> return result
Best for: All queries. Responses take 30s–5min depending on complexity.
IMPORTANT: Always poll with exponential backoff up to 5 minutes total. Do not give up early.

Pattern 2: Streaming Chat (WebSocket)

Agent: Connect to WebSocket -> Send start message -> Receive streaming chunks -> Receive complete
Best for: Long responses, real-time feedback, progress indicators

Pattern 3: Session-Aware Chat

Agent: List sessions -> Get session messages -> Continue conversation in same session
Best for: Multi-turn analysis workflows

Pattern 4: Tool-Based Workflow

Agent: List tools -> Execute specific tool -> Process result -> Chat about results
Best for: Automated data retrieval pipelines

Available Data Sources

Brazilian Data (PySUS)

• SINAN: Disease notifications (dengue, Zika, chikungunya, measles, etc.)
• SIM: Mortality data
• SIH: Hospital admissions
• CNES: Health facilities
• IBGE: Census and demographic data

International Data

• WHO/GHO: Global health indicators
• PAHO: Americas health data
• HealthData.gov: US hospital capacity, COVID metrics
• World Bank: Development indicators
• ECDC: European disease surveillance

Specialized

• Mosqlimate/Infodengue: Brazilian epidemiological parameters

Configuration

Environment Variable	Default	Description
EPIDBOT_API_KEY	-	API key for authentication
EPIDBOT_BASE_URL	https://api.epidbot.kwar-ai.com.br	Base URL of EpidBot API

Rate Limits

Endpoint	Limit
POST /auth/login	10 requests/minute
POST /auth/register	5 requests/minute
Other endpoints	60 requests/minute

Deployment

EpidBot is typically deployed via Docker Compose:

services:
  api:
    ports:
      - '8123:8123'
  epidbot:
    ports:
      - '7860:7860'
  db:
    ports:
      - '5432:5432'

Health check: curl https://api.epidbot.kwar-ai.com.br/api/v1/health

Limitations

• Job expiry: Chat jobs expire after 1 hour
• Response time: Simple queries take 30s–3min; complex data analysis can take up to 5 minutes. Always poll with exponential backoff.
• File sizes: Large data exports may be limited by memory constraints
• Sandbox execution: Python/SQL code execution happens in an isolated sandbox with resource limits

Support

• GitHub: https://github.com/fccoelho/EpiDBot
• Documentation: https://github.com/fccoelho/EpiDBot/tree/main/docs