fangbot 0.1.0__tar.gz

fangbot-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,52 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --extra dev --extra openai
+
+      - name: Run linter
+        run: uv run ruff check .
+
+      - name: Check formatting
+        run: uv run ruff format --check .
+
+      - name: Run tests
+        run: uv run python -m pytest -v --tb=short
+
+  build:
+    runs-on: ubuntu-latest
+    needs: test
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Build package
+        run: uv build
+
+      - name: Verify wheel
+        run: ls -la dist/

fangbot-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,27 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # trusted publishing
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

fangbot-0.1.0/.gitignore

@@ -0,0 +1,59 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg
+*.egg-info/
+dist/
+build/
+*.whl
+*.manifest
+*.spec
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# uv
+uv.lock
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Environment / secrets
+.env
+.env.*
+!.env.example
+*.pem
+*.key
+credentials.json
+
+# Testing / coverage
+.pytest_cache/
+.coverage
+htmlcov/
+.hypothesis/
+
+# Logs
+logs/
+*.log
+
+# Claude Code
+.claude/
+
+# Ruff
+.ruff_cache/
+
+# mypy
+.mypy_cache/
+
+# Jupyter
+.ipynb_checkpoints/

fangbot-0.1.0/.python-version

@@ -0,0 +1 @@
+3.10

fangbot-0.1.0/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-03-09
+
+### Added
+
+- Initial release of Fangbot
+- ReAct loop engine for clinical reasoning with mandatory MCP tool use
+- Anthropic Claude provider (Opus 4.6, Sonnet 4.6, Haiku 4.5, Sonnet 4, Opus 4)
+- OpenAI provider (GPT-5, GPT-4o, GPT-4.1, o3, o4-mini)
+- MCP client connecting to OpenMedicine server via stdio
+- Interactive CLI with `fangbot chat` command
+- Slash commands: `/help`, `/status`, `/claude`, `/openai`, `/model`, `/models`, `/clear`, `/history`, `/compact`
+- Interactive model picker with categorized display
+- `fangbot init` setup wizard — provider config, API key, MCP connection test
+- `~/.fangbot/` config home for settings and logs
+- JSONL audit trail for all agent interactions
+- Clinical guardrails enforcing mandatory tool use
+- Session context with conversation history management
+- 62 unit tests with full mock coverage
+
+[0.1.0]: https://github.com/RamosFBC/fangbot/releases/tag/v0.1.0

fangbot-0.1.0/CLAUDE.md

@@ -0,0 +1,108 @@
+# Fangbot
+
+A clinical reasoning agent powered by [OpenMedicine](https://github.com/open-medicine/openmedicine) — fangs of the healing serpent. Connects to the OpenMedicine MCP server to perform deterministic, auditable clinical calculations. **This is NOT a diagnostic tool** — it is a research platform for validating LLM-based clinical tool orchestration.
+
+## Critical Constraint
+
+> The agent MUST call OpenMedicine's deterministic MCP tools for any clinical calculation. It must NEVER compute scores, doses, or risk stratifications from its own parametric knowledge.
+
+Enforced by: system prompt rules, evaluation harness (protocol adherence check), and audit trail verification. Results without tool-call traces are failures regardless of correctness.
+
+## Commands
+
+```bash
+uv sync                                        # Install dependencies
+uv run fangbot chat                             # Interactive CLI mode
+uv run fangbot run studies/chadsvasc/config.yaml # Batch evaluation
+uv run fangbot report studies/chadsvasc/results/ # Generate comparison report
+uv run python -m pytest -v                       # Run tests
+uv run python -m pytest tests/test_file.py -v    # Run single test file
+uv run python -m pytest -k "test_name" -v        # Run specific test
+```
+
+## Configuration
+
+Environment variables use the `FANGBOT_` prefix (e.g. `FANGBOT_PROVIDER`, `FANGBOT_MODEL`). The agent also reads native SDK env vars (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`) as fallback.
+
+## Tech Stack
+
+- **Language:** Python 3.10+
+- **Package manager:** uv (matches OpenMedicine)
+- **LLM SDKs:** anthropic, openai, google-genai (multi-model benchmarking)
+- **MCP client:** mcp (Python SDK) — connects to OpenMedicine via stdio
+- **Validation:** Pydantic
+- **CLI:** typer + rich
+- **Testing:** pytest + Hypothesis
+- **Audit format:** JSON-lines (.jsonl)
+
+## Architecture
+
+```
+Gateway → Brain → Skills (MCP) → Memory
+                                → Evaluation
+```
+
+| Layer | Path | Purpose |
+|-------|------|---------|
+| Gateway | `src/fangbot/gateway/` | Case ingestion (CLI, API, file loader) |
+| Brain | `src/fangbot/brain/` | ReAct loop + clinical guardrails + LLM providers |
+| Skills | `src/fangbot/skills/` | MCP client connecting to OpenMedicine server |
+| Memory | `src/fangbot/memory/` | Session context, audit log (JSONL), chain-of-thought |
+| Workflows | `src/fangbot/workflows/` | Study-specific clinical workflows |
+| Evaluation | `src/fangbot/evaluation/` | Batch runner, gold standard comparison, metrics |
+| Safety | `src/fangbot/safety/` | Validators, contraindication flags |
+
+## MCP Integration Rules
+
+- The agent spawns `uv run open-medicine-mcp` as a subprocess and communicates via stdin/stdout
+- The agent NEVER imports OpenMedicine directly — always goes through MCP protocol
+- Available meta-tools: `search_clinical_calculators`, `execute_clinical_calculator`, `search_guidelines`, `retrieve_guideline`
+- OpenMedicine >= 0.4.0 required
+
+## LLM Providers
+
+Abstract base in `brain/providers/base.py`. Implementations:
+- `claude.py` — Anthropic Claude (primary)
+- `openai.py` — OpenAI GPT-4/GPT-5
+- `gemini.py` — Google Gemini (planned)
+- `ollama.py` — Local models via Ollama (planned)
+
+All providers must implement the same interface for benchmark comparability.
+
+## Research Studies
+
+| Study | Workflow | Calculator | Complexity |
+|-------|----------|-----------|------------|
+| 1: Renal Dosing | `renal_dosing.py` | CKD-EPI + dose adjustment | Multi-step chain |
+| 2: Glasgow Coma Score | `gcs_assessment.py` | GCS calculator | Narrative extraction |
+| 3: CHA2DS2-VASc | `chadsvasc.py` | CHA2DS2-VASc | Single calculator (simplest) |
+
+Build order: Study 3 first (simplest), then Study 2, then Study 1.
+
+## Evaluation Metrics
+
+- **accuracy** — exact score match
+- **mae** — mean absolute error
+- **kappa** — Cohen's Kappa (inter-rater reliability)
+- **sensitivity/specificity** — per risk tier
+- **protocol_adherence** — did the agent call the right tools?
+- **cot_quality** — was reasoning auditable and correct?
+
+## Audit Log
+
+Every agent run produces a JSONL audit file with events: `case_received`, `think`, `tool_call`, `tool_result`, `synthesis`, `evaluation`. Each tool result includes DOI references.
+
+## Code Style
+
+- Pydantic models for all data structures
+- Type hints on all public functions
+- Async where appropriate (MCP client, LLM calls)
+- Follow OpenMedicine patterns for consistency
+
+## Gotchas
+
+- MCP communication is stdio-based — never try HTTP/WebSocket to OpenMedicine
+- Synthetic patient data only — no real patient data (per Resolucao CNS 510/2016)
+- metric_mismatch_warning from tools must be included verbatim in responses
+- Contraindication results must be prominently flagged, never downplayed
+- Gold standard cases require expert validation before use in evaluation

fangbot-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,166 @@
+# Contributing to Fangbot
+
+Thanks for your interest in contributing! Fangbot is an open-source clinical reasoning agent and we welcome contributions of all kinds.
+
+## Code of Conduct
+
+Be respectful, constructive, and inclusive. We follow the [Contributor Covenant](https://www.contributor-covenant.org/version/2/1/code_of_conduct/).
+
+## Getting started
+
+### Prerequisites
+
+- Python 3.10+
+- [uv](https://docs.astral.sh/uv/) package manager
+- An API key for at least one LLM provider (Anthropic or OpenAI)
+
+### Development setup
+
+```bash
+# Clone the repo
+git clone https://github.com/RamosFBC/fangbot.git
+cd fangbot
+
+# Install all dependencies (dev + optional providers)
+uv sync --extra dev --extra openai
+
+# Run tests
+uv run python -m pytest -v
+
+# Run linter
+uv run ruff check .
+
+# Run formatter
+uv run ruff format .
+```
+
+### Project structure
+
+```
+src/fangbot/
+├── gateway/        # CLI interface (typer + rich)
+├── brain/          # ReAct loop, providers, guardrails
+│   └── providers/  # LLM provider implementations
+├── skills/         # MCP client, tool registry
+└── memory/         # Session context, audit logger
+tests/              # pytest test suite
+```
+
+## Development workflow
+
+1. **Fork** the repository
+2. **Create a branch** from `main`: `git checkout -b feat/your-feature`
+3. **Make your changes** — write tests for new functionality
+4. **Run the full test suite**: `uv run python -m pytest -v`
+5. **Run the linter**: `uv run ruff check .`
+6. **Commit** with a clear message (see conventions below)
+7. **Push** and open a Pull Request
+
+### Branch naming
+
+| Prefix | Use for |
+|--------|---------|
+| `feat/` | New features |
+| `fix/` | Bug fixes |
+| `docs/` | Documentation |
+| `refactor/` | Code restructuring |
+| `test/` | Test additions/fixes |
+
+### Commit messages
+
+Use clear, descriptive commit messages:
+
+```
+Add renal dosing workflow with CKD-EPI integration
+
+Implements the multi-step renal dosing calculation chain using
+CKD-EPI GFR estimation followed by dose adjustment lookup.
+```
+
+- Start with a verb (Add, Fix, Update, Remove, Refactor)
+- First line under 72 characters
+- Body explains **why**, not just **what**
+
+## Testing
+
+```bash
+# Full test suite
+uv run python -m pytest -v
+
+# Single test file
+uv run python -m pytest tests/test_react_loop.py -v
+
+# Specific test
+uv run python -m pytest -k "test_guardrail" -v
+
+# Integration tests (requires open-medicine-mcp)
+uv run python -m pytest -m integration -v
+```
+
+### Writing tests
+
+- Every new feature needs tests
+- Use `pytest` fixtures and `tmp_path` for file operations
+- Mock external services (LLM APIs, MCP server) — see `tests/conftest.py`
+- Use `@pytest.mark.asyncio` for async tests
+- Use `@pytest.mark.integration` for tests requiring a live MCP server
+
+## Code style
+
+- **Linter/formatter:** ruff (configured in `pyproject.toml`)
+- **Type hints** on all public functions
+- **Pydantic models** for all data structures
+- **Line length:** 100 characters
+- **Target:** Python 3.10+ (no walrus operator in hot paths, use `from __future__ import annotations`)
+
+Run before committing:
+
+```bash
+uv run ruff check . --fix
+uv run ruff format .
+```
+
+## Adding a new LLM provider
+
+1. Create `src/fangbot/brain/providers/your_provider.py`
+2. Implement the `LLMProvider` ABC from `base.py`
+3. Add the provider to `_create_provider()` in `gateway/cli.py`
+4. Add models to `gateway/models_catalog.py`
+5. Add the SDK as an optional dependency in `pyproject.toml`
+6. Write tests in `tests/test_providers.py`
+
+## Adding a new clinical workflow
+
+1. Create `src/fangbot/workflows/your_workflow.py`
+2. Define gold standard test cases
+3. Add to the study configuration
+4. Write evaluation tests
+
+## Critical rules
+
+- **Never compute clinical scores from LLM knowledge** — always use MCP tools
+- **Never import OpenMedicine directly** — communicate via MCP protocol only
+- **Synthetic patient data only** — no real patient data (per Resolucao CNS 510/2016)
+- **Always include DOI references** from tool results in responses
+- **Never downplay contraindication flags** from MCP tools
+
+## Releasing
+
+Releases follow [Semantic Versioning](https://semver.org/):
+
+- **MAJOR** (1.0.0) — breaking API changes
+- **MINOR** (0.2.0) — new features, backward compatible
+- **PATCH** (0.1.1) — bug fixes
+
+Releases are automated via GitHub Actions when a version tag is pushed:
+
+```bash
+# Update version in pyproject.toml and src/fangbot/__init__.py
+# Update CHANGELOG.md
+git tag v0.2.0
+git push origin v0.2.0
+```
+
+## Questions?
+
+Open an [issue](https://github.com/RamosFBC/fangbot/issues) or start a [discussion](https://github.com/RamosFBC/fangbot/discussions).

fangbot-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RamosFBC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fangbot-0.1.0/PKG-INFO

@@ -0,0 +1,163 @@
+Metadata-Version: 2.4
+Name: fangbot
+Version: 0.1.0
+Summary: Clinical reasoning agent powered by OpenMedicine — fangs of the healing serpent
+Project-URL: Homepage, https://github.com/RamosFBC/fangbot
+Project-URL: Repository, https://github.com/RamosFBC/fangbot
+Project-URL: Issues, https://github.com/RamosFBC/fangbot/issues
+Project-URL: Changelog, https://github.com/RamosFBC/fangbot/blob/main/CHANGELOG.md
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,clinical,llm,mcp,openmedicine,reasoning
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Healthcare Industry
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: anthropic>=0.40.0
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: open-medicine>=0.6.0
+Requires-Dist: pydantic-settings>=2.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: typer>=0.12.0
+Provides-Extra: dev
+Requires-Dist: hypothesis>=6.0.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.8.0; extra == 'dev'
+Provides-Extra: gemini
+Requires-Dist: google-genai>=1.0.0; extra == 'gemini'
+Provides-Extra: ollama
+Requires-Dist: ollama>=0.4.0; extra == 'ollama'
+Provides-Extra: openai
+Requires-Dist: openai>=1.0.0; extra == 'openai'
+Description-Content-Type: text/markdown
+
+# Fangbot
+
+[![PyPI version](https://img.shields.io/pypi/v/fangbot.svg)](https://pypi.org/project/fangbot/)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+[![CI](https://github.com/RamosFBC/fangbot/actions/workflows/ci.yml/badge.svg)](https://github.com/RamosFBC/fangbot/actions/workflows/ci.yml)
+
+Clinical reasoning agent powered by [OpenMedicine](https://github.com/open-medicine/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
+
+```bash
+# 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
+
+```bash
+# Interactive setup — configure provider, API key, test MCP connection
+fangbot init
+
+# Start a clinical reasoning session
+fangbot chat
+```
+
+## Usage
+
+```bash
+fangbot init                          # First-time setup wizard
+fangbot chat                          # Interactive clinical reasoning session
+fangbot run studies/config.yaml       # Batch evaluation (Phase 2)
+fangbot report studies/results/       # Generate comparison report (Phase 2)
+```
+
+### 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)
+```
+
+- **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
+
+## Development
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.
+
+```bash
+git clone https://github.com/RamosFBC/fangbot.git
+cd fangbot
+uv sync --extra dev --extra openai
+uv run python -m pytest -v
+```
+
+## License
+
+[MIT](LICENSE) — Copyright (c) 2026 RamosFBC