# holboxai/newberryai architecture

> Architecture diagram of the GitHub repository holboxai/newberryai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/holboxai/newberryai
- Repository: https://github.com/holboxai/newberryai

## Overview

##### Project type and purpose
- This is an open-source Python package (newberryai) that exposes a multi-tool AI assistant framework via:
- A command-line interface (CLI)
- Optional Gradio web interfaces
- A Python importable module for embedding in custom scripts
- It bundles a suite of “assistants” (Excel formula generator, PII redactor/extractor, differential diagnosis, PDF summarizer, medical-bill extractor, speech-to-speech, etc.) that internally call LLMs (OpenAI API) and, for certain features, AWS services (S3, HealthScribe).

##### File structure
- Top-level “newberryai” package directory containing:
- excel, PII, ddx, eda, bill_extractor, healthscribe, compliance, speech modules
- cli.py (CLI entrypoint, sub-command registration)
- _version.py, __init__.py (package metadata)
- Standard Python packaging files (setup.py, pyproject.toml, requirements.txt)
- GitHub actions workflow for PyPI publishing
- No separate “frontend” or “backend” directories—this is a monolithic library with a CLI front end.

##### Insights from README
- Each assistant can be run via `newberryai <command>` or via `assistant.run_cli()` / `.start_gradio()`.
- Assistants that process files rely on AWS S3 for input/output; others rely solely on the OpenAI API.
- The package acts as an adapter/facade around external AI services.

a. Main components
1. User Interfaces
- CLI (click/argparse in cli.py)
- Gradio Web UIs (optional per assistant)
2. Command Router / Dispatcher
- Reads sub-command (e.g., “ddx”, “ExcelO”, “PII_Red”), instantiates the matching assistant class
3. Assistant Modules
- HealthScribe
- ComplianceChecker
- DDxChat
- ExcelExp
- Bill_extractor
- CodeReviewAssistant
- PII_Redaction / PII_extraction
- RealtimeApp (speech-to-speech)
- EDA
- DocSummarizer
4. Infrastructure & Integration Layer
- OpenAI API (text, speech-to-text, text-to-speech)
- AWS Services
- S3 (input/output storage)
- AWS HealthScribe (medical transcription)
- IAM (credentials/roles)
5. Local Environment
- Python runtime + third-party libs (boto3, openai, gradio, pandas, etc.)
- Local file system (caching, temp files)
b. Relationships & interactions
- User invokes CLI or starts Gradio → CLI/Gradio UI calls Command Router
- Router → selects and instantiates the corresponding Assistant module
- Assistant → preprocesses input (files or text), then:
- If text-only feature → calls OpenAI API
- If file-based AWS feature → pushes file to S3, calls AWS HealthScribe or Lambdas, polls for results, retrieves from S3
- Assistant → post-processes the LLM/AWS response → returns/display to user
c. Architectural patterns and design principles
- Facade/Adapter pattern: each assistant class hides complexity of OpenAI/AWS calls behind a unified `.ask()` / `.process()` interface
- Single-package modularization: modules grouped by domain (PII, EDA, medical, etc.)
- CLI-first design with optional web-UI decorators
d. Key technologies
- Python 3.8+
- openai Python SDK
- boto3 (AWS SDK)
- Click or argparse (in cli.py)
- Gradio (optional web interfaces)
- pandas, matplotlib/seaborn (EDA)
- AWS services: S3, HealthScribe, IAM

##### Elements
- Clear component labels: “CLI Entrypoint”, “Command Router”, “ExcelExp Assistant”, “OpenAI API”, “AWS S3 / HealthScribe”
- User → CLI/Gradio UI
- CLI/Gradio → Router → Assistant
- Assistant → OpenAI / AWS → Assistant
- Assistant → CLI output or Web UI display
- Green blocks for “newberryai” internal components
- Orange blocks for external services (OpenAI, AWS)

##### Be detailed and comprehensive
- Shared infrastructure (env vars for AWS/OpenAI, Python runtime) at the bottom
- Both synchronous text calls (OpenAI chat completions) and asynchronous file workflows (S3 upload → HealthScribe job → S3 download)
- Credentials/access boundaries (environment variables, AWS IAM roles, OpenAI API key)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interfaces
    subgraph "User Interfaces"
        CLI["CLI Entrypoint"]:::ui
        WebUI["Gradio Web UI"]:::ui
    end
    click CLI "https://github.com/holboxai/newberryai/blob/main/newberryai/cli.py"

    %% Command Router
    Router["Command Router / Dispatcher"]:::internal
    click Router "https://github.com/holboxai/newberryai/blob/main/newberryai/cli.py"

    CLI --> Router
    WebUI -- "optional" --> Router

    %% Core Assistants
    subgraph "newberryai Core" 
        direction TB
        ExcelExp["ExcelExp Assistant"]:::internal
        DDx["DDxChat Assistant"]:::internal
        PIIExtr["PII Extraction Assistant"]:::internal
        PIIRed["PII Redaction Assistant"]:::internal
        EDA["EDA Assistant"]:::internal
        BillExt["Medical Bill Extractor Assistant"]:::internal
        Compliance["Health Compliance Checker Assistant"]:::internal
        HealthScribe["Health Scribe Assistant"]:::internal
        HealthChat["Health Chat Assistant"]:::internal
        PDFSum["PDF Summarizer Assistant"]:::internal
        Speech["Speech-to-Speech Assistant"]:::internal
        CodeRev["Code Review Assistant"]:::internal
        PackageMeta["Package Metadata / Version"]:::infra
        Packaging["Packaging Config"]:::infra
    end

    click ExcelExp "https://github.com/holboxai/newberryai/blob/main/newberryai/ExcelO.py"
    click DDx "https://github.com/holboxai/newberryai/blob/main/newberryai/ddx.py"
    click PIIExtr "https://github.com/holboxai/newberryai/blob/main/newberryai/PII_extractor.py"
    click PIIRed "https://github.com/holboxai/newberryai/blob/main/newberryai/PII_masking.py"
    click EDA "https://github.com/holboxai/newberryai/blob/main/newberryai/eda.py"
    click BillExt "https://github.com/holboxai/newberryai/blob/main/newberryai/medical_bill_extractor.py"
    click Compliance "https://github.com/holboxai/newberryai/blob/main/newberryai/health_compliance.py"
    click HealthScribe "https://github.com/holboxai/newberryai/blob/main/newberryai/healthscribe.py"
    click HealthChat "https://github.com/holboxai/newberryai/blob/main/newberryai/health_chat.py"
    click PDFSum "https://github.com/holboxai/newberryai/blob/main/newberryai/pdf_summarizer.py"
    click Speech "https://github.com/holboxai/newberryai/blob/main/newberryai/speechtospeech.py"
    click CodeRev "https://github.com/holboxai/newberryai/blob/main/newberryai/debugger.py"
    click PackageMeta "https://github.com/holboxai/newberryai/blob/main/newberryai/_version.py"
    click Packaging "https://github.com/holboxai/newberryai/blob/main/setup.py"

    Router --> ExcelExp
    Router --> DDx
    Router --> PIIExtr
    Router --> PIIRed
    Router --> EDA
    Router --> BillExt
    Router --> Compliance
    Router --> HealthScribe
    Router --> HealthChat
    Router --> PDFSum
    Router --> Speech
    Router --> CodeRev

    %% External Services
    subgraph "External Integrations"
        direction TB
        OpenAI["OpenAI API"]:::external
        AWS["AWS Services"]:::external
    end

    ExcelExp --> OpenAI
    DDx --> OpenAI
    PIIExtr --> OpenAI
    PIIRed --> OpenAI
    EDA --> OpenAI
    BillExt --> AWS
    Compliance --> AWS
    HealthScribe --> AWS
    HealthChat --> OpenAI
    PDFSum --> OpenAI
    Speech --> OpenAI
    CodeRev --> OpenAI

    %% Local Environment
    subgraph "Local Environment"
        direction TB
        Python["Python Runtime + Libraries"]:::infra
        LocalFS["Local File System"]:::infra
    end

    Python --> ExcelExp
    Python --> DDx
    Python --> PIIExtr
    Python --> PIIRed
    Python --> EDA
    Python --> BillExt
    Python --> Compliance
    Python --> HealthScribe
    Python --> HealthChat
    Python --> PDFSum
    Python --> Speech
    Python --> CodeRev

    LocalFS --> BillExt
    LocalFS --> HealthScribe

    %% Styles
    classDef ui fill:#b3d4fc,stroke:#0366d6,color:#0366d6;
    classDef internal fill:#c8e6c9,stroke:#2e7d32,color:#2e7d32;
    classDef external fill:#ffe0b2,stroke:#e65100,color:#e65100;
    classDef infra fill:#e0e0e0,stroke:#424242,color:#424242
```
