Skip to main content

Fangbot

PyPI version Python 3.10+ License: MIT CI

Clinical reasoning agent powered by OpenMedicine — fangs of the healing serpent.

This is NOT a diagnostic tool — it is a research platform for validating LLM-based clinical tool orchestration.

What it does

Fangbot connects to the OpenMedicine MCP server to perform deterministic, auditable clinical calculations via a ReAct (Reasoning + Acting) loop. It supports multiple LLM providers for benchmarking.

Critical constraint: The agent always calls OpenMedicine's MCP tools for clinical calculations — it never computes scores from its own knowledge.

Install

# Recommended: install as a global CLI tool
pipx install fangbot

# Or with uv
uv tool install fangbot

# With OpenAI support
pipx install "fangbot[openai]"

Quick start

# Interactive setup — configure provider, API key, test MCP connection
fangbot init

# Start a clinical reasoning session
fangbot chat

Usage

fangbot init                          # First-time setup wizard
fangbot chat                          # Interactive clinical reasoning session
fangbot run studies/chadsvasc/config.yaml   # Batch evaluation against gold standard cases
fangbot report studies/chadsvasc/results/   # Generate cross-provider comparison report

Chat commands

Inside fangbot chat, use slash commands:

Command Description
/help Show all commands
/status Current provider, model, session info
/claude [model] Switch to Claude
/openai [model] Switch to OpenAI
/model [name] Interactive model picker
/models List all available models
/clear Clear conversation history
/history Show message count and tool calls
/compact Compress conversation history
quit End the session

Configuration

Fangbot stores config in ~/.fangbot/:

~/.fangbot/
├── .env          # API keys and settings
└── logs/         # JSONL audit trail

Environment variables (prefix FANGBOT_):

Variable Default Description
FANGBOT_PROVIDER claude LLM provider (claude, openai)
FANGBOT_MODEL claude-sonnet-4-20250514 Model to use
ANTHROPIC_API_KEY — Anthropic API key
OPENAI_API_KEY — OpenAI API key

Supported providers

Provider Models Status
Anthropic Claude Opus 4.6, Sonnet 4.6, Haiku 4.5, Sonnet 4, Opus 4 Supported
OpenAI GPT-5, GPT-4o, GPT-4.1, o3, o4-mini Supported
Google Gemini — Planned
Ollama (local) — Planned

Architecture

Gateway (CLI) → Brain (ReAct loop) → Skills (MCP tools) → Memory (audit trail)
                                                        → Evaluation (batch runner, metrics, reports)
  • Gateway — CLI interface with typer + rich
  • Brain — ReAct loop engine, LLM providers, clinical guardrails
  • Skills — MCP client connecting to OpenMedicine server via stdio
  • Memory — Session context, JSONL audit logger
  • Evaluation — Batch runner, gold standard comparison, metrics engine, Markdown report generator

Evaluation

Fangbot includes a batch evaluation framework for benchmarking LLM providers against gold standard clinical cases.

# Run all CHA2DS2-VASc cases through the agent
fangbot run studies/chadsvasc/config.yaml

# Generate a comparison report from saved results
fangbot report studies/chadsvasc/results/ --config studies/chadsvasc/config.yaml

Gold standard cases are YAML files with expected scores, risk tiers, and tool calls. The evaluation engine computes:

Metric Description
Accuracy Exact score match rate
MAE Mean absolute error
Cohen's Kappa Inter-rater reliability
Sensitivity/Specificity Per risk tier (low/moderate/high)
Protocol adherence Did the agent call the required MCP tools?
CoT quality Was reasoning auditable with chain-of-thought?

Development

See CONTRIBUTING.md for development setup and guidelines.

git clone https://github.com/RamosFBC/fangbot.git
cd fangbot
uv sync --extra dev --extra openai
uv run python -m pytest -v

License

MIT — Copyright (c) 2026 RamosFBC

Metadata

Release files for fangbot 0.4.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for fangbot 0.4.0
File Size Uploaded Provenance Actions
fangbot-0.4.0.tar.gz 141.9 kB With provenance Details for fangbot-0.4.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for fangbot 0.4.0
File Interpreter ABI Platform Actions
fangbot-0.4.0-py3-none-any.whl Python 3 none any Details for fangbot-0.4.0-py3-none-any.whl

Total release size: 228.7 kB

Release files / fangbot-0.4.0.tar.gz

Download URL fangbot-0.4.0.tar.gz
Size 141.9 kB
Tags Source
SHA-256 checksum
How to use checksums
faf34911c0fca09100b02e5930373656311b0882073dc8e542cd8e4efa1589d2
BLAKE2b-256 checksum
How to use checksums
2c139c7a075523be282d580072f14dadd70e8fb843153a97a4b833c84a9b472b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Mar 13, 2026.

Transparency log

Release files / fangbot-0.4.0-py3-none-any.whl

Download URL fangbot-0.4.0-py3-none-any.whl
Size 86.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
75b3c06e52ebb93357ad3cfe0ffb3245d81612e2663e943750ef8e1e7fc8a217
BLAKE2b-256 checksum
How to use checksums
a2f1c9050a3d4738c91aa586b4234125a6cbea239a7143fb93ab3a23e352ac57
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Mar 13, 2026.

Transparency log

Security for fangbot 0.4.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for fangbot-0.4.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Mar 13, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page