# What Is the Function of the doctor.py Module in Agent Reach?

> Discover the function of the doctor.py module in Agent Reach. This essential tool inspects platform channels and generates a formatted diagnostic report for environment health.

- Repository: [Pnant/Agent-Reach](https://github.com/Panniantong/Agent-Reach)
- Tags: internals
- Published: 2026-07-04

---

**The [`doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/doctor.py) module serves as the environment health-checker for Agent Reach, inspecting every supported platform channel and presenting a formatted diagnostic report.**

The [`doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/doctor.py) module in Agent Reach acts as the central diagnostic system that validates whether all configured platform channels are properly installed and ready for use. Located at [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py), this module provides the underlying functionality for the `agent-reach doctor` CLI command, enabling users to verify their environment before executing search operations. It aggregates status checks from every registered channel and renders them into human-readable reports using Rich markup.

## Core Health-Checking Functions in doctor.py

The module implements three primary functions that work together to diagnose the Agent Reach environment.

### check_all(config)

The `check_all()` function, implemented in [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py) at lines 12-35, serves as the main inspection engine. It iterates over all registered channels via `get_all_channels()` and calls each channel's `check(config)` method.

When a channel check raises an exception, `check_all` normalizes the error into a status `"error"` with a descriptive message. The function returns a dictionary keyed by channel name, containing:

- **status**: The health state (e.g., `"ok"`, `"error"`, or configuration warnings)
- **description**: A human-readable explanation of the channel
- **message**: Any error or warning details
- **tier**: The service tier classification
- **backends**: A list of available back-end options
- **active_backend**: The currently selected back-end

### _name_msg(r, escape)

This helper function at lines 38-44 in [`doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/doctor.py) constructs individual report lines. It handles the display logic for channels with multiple back-ends, optionally appending the active back-end name to provide context about which specific tool is being used (e.g., `opencli`, `yt-dlp`, or `twurl`).

### format_report(results)

The `format_report()` function, spanning lines 47-100 in [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py), transforms the raw dictionary from `check_all` into a visually structured console output. Using **Rich markup**, it generates a color-coded, tier-grouped text report that indicates:

- ✅ **Ready** channels (status ok)
- **!** Channels needing configuration
- **X** Missing or error states

The function also calculates an overall health summary showing the count of operational channels versus the total.

## How to Use the Agent Reach Doctor Module

### Programmatic API

You can invoke the doctor module directly within Python scripts to verify environment health before running operations:

```python
from agent_reach.doctor import check_all, format_report
from agent_reach.config import Config

cfg = Config()                     # loads user config (YAML / env)

report_data = check_all(cfg)       # → dict of per‑channel statuses

print(format_report(report_data))  # pretty Rich‑styled text

```

This returns the same colorful console output available through the CLI, useful for embedding in management scripts or administrative tools.

### Command Line Interface

The most common usage is through the `agent-reach doctor` command, which delegates to `check_all` and `format_report` (see `cli.py::_cmd_doctor`):

```bash

# Basic health check with formatted output

$ agent-reach doctor

# JSON-friendly output for scripting

$ agent-reach doctor --json

```

The CLI automatically loads the configuration via [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) and passes it to the underlying check functions.

### Custom Integration

For CI pipelines or installation scripts that require boolean validation, wrap the doctor check to return a simple pass/fail result:

```python
def health_summary():
    from agent_reach.doctor import check_all, format_report
    from agent_reach.config import Config
    results = check_all(Config())
    # Return brief boolean for automation

    return all(v["status"] == "ok" for v in results.values())

```

This allows automated systems to verify that all required back-ends are available before proceeding with deployments or tests.

## Key Files in the Doctor Workflow

The diagnostic system spans several files in the Agent Reach codebase:

- **[`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py)**: Contains the core health-checking logic (`check_all`, `format_report`) and helper functions.
- **[`agent_reach/channels/__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/__init__.py)**: Provides `get_all_channels()`, the registry that the doctor iterates over to discover available platforms.
- **[`agent_reach/core.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/core.py)**: Implements the high-level API (`AgentReach.doctor()`) that calls the doctor module for programmatic use.
- **[`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py)**: Parses the `agent-reach doctor` command and prints the formatted report.
- **[`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py)**: Loads user configuration that the doctor passes to each channel's `check` method.

## Summary

The [`doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/doctor.py) module functions as Agent Reach's diagnostic engine, providing clear visibility into platform readiness:

- **`check_all(config)`** inspects every registered channel and aggregates status reports.
- **`format_report(results)`** renders diagnostic data into color-coded console output using Rich markup.
- The module supports both **CLI invocation** (`agent-reach doctor`) and **programmatic integration** for automation scripts.
- It validates back-end availability (such as `opencli`, `yt-dlp`, or `twurl`) without performing actual searches or reads.

## Frequently Asked Questions

### How does doctor.py determine if a channel is healthy?

The module delegates health checks to each channel's own `check(config)` method. According to the source code in [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py) (lines 12-35), `check_all` iterates through all channels retrieved via `get_all_channels()` and captures any exceptions, converting them into standardized error statuses. This architecture ensures that [`doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/doctor.py) remains agnostic about specific platform requirements while providing uniform reporting.

### Can I use the doctor module without the CLI?

Yes. The [`doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/doctor.py) module is designed for programmatic use. You can import `check_all` and `format_report` directly from `agent_reach.doctor`, instantiate a `Config` object from `agent_reach.config`, and generate reports within your own Python applications. This is particularly useful for embedding health checks into deployment scripts or monitoring systems.

### What information does the doctor report include?

The report generated by `format_report` (lines 47-100 in [`doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/doctor.py)) includes each channel's operational status, description, error messages, service tier, available back-ends, and currently active back-end. The output uses Rich markup to provide visual indicators (✅ for ready, ! for configuration needed, X for missing) and summarizes overall health with an `ok/total` count.

### Where does doctor.py get the list of channels to check?

The module imports the channel registry from [`agent_reach/channels/__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/__init__.py) via the `get_all_channels()` function. This registry contains all supported platform channels (such as those wrapping `opencli`, `yt-dlp`, or `twurl`), allowing the doctor to dynamically inspect whatever platforms are installed in the current Agent Reach environment.