HelseCLI Architecture

HelseCLI is engineered with a modular, extensible architecture optimized for high-performance AI interaction and secure computational execution.

System Components

1. Entrance Wrapper (helsecli.py)

The primary system entry point. It manages environment initialization, virtual environment virtualization, and command routing to the internal CLI core.

2. CLI Framework (src/cli/)

Built on a robust foundation of argparse and rich, this layer manages:

• Command-line argument parsing
• Structured UI rendering (technical tables, panels, and progress telemetry)
• Interactive prompt management
• Optimized output formatting

3. Core Assistant Engine (src/core/assistant.py)

The central orchestrator of HelseCLI. It manages:

• State and conversation history
• Provider-agnostic model interaction
• Tool orchestration and selection logic
• Autonomous agent planning and task chain synthesis
• Document generation workflows

4. Provider Abstraction Layer (src/providers/)

Standardizes communication protocols across various LLM APIs:

• openai.py: Implementation for OpenAI API integration.
• anthropic.py: Implementation for Anthropic (Claude) API integration.
• google.py: Implementation for Google Vertex/AI API integration.
• ollama.py: Integration for local inference via Ollama.

5. Tool Registry (src/tools/)

A modular system of capabilities exposed to the LLM:

• File System Operations: file_ops.py, code_tools.py
• Computational Execution: sandbox_tools.py (Supporting Local, Docker, and E2B)
• Search and Retrieval: search.py, web_tools.py, browser_tools.py
• Scientific Research: research_tools.py
• Asset Processing: vision_tools.py, pandoc_tools.py

Data Flow Architecture

graph TD
    User([User Input]) --> CLI[CLI Layer]
    CLI --> Assistant[Core Assistant]
    Assistant --> Plan[Planner/Agent]
    Plan --> Tools[Tool Registry]
    Tools --> System[System/OS/Sandbox]
    System --> Tools
    Tools --> Assistant
    Assistant --> Provider[LLM Provider]
    Provider --> LLM[External LLM Service]
    LLM --> Provider
    Provider --> Assistant
    Assistant --> CLI
    CLI --> UI([Rich UI Output])

Security and Sandboxing

HelseCLI implements a hierarchical safety protocol for code execution:

1. Local Host: Unisolated execution (default).
2. Docker Containers: Temporary containerization for environment isolation.
3. E2B Managed Cloud: Secure, ephemeral virtual machines for high-risk computational tasks.

Document Generation Pipeline

The Document Mode utilizes a structured multi-phase pipeline:

1. Strategic Planning: The system synthesizes a "Task Chain" of required sections.
2. Data Acquisition: If research is enabled, autonomous tools retrieve web-based data for each section.
3. Synthesis: Sections are generated sequentially to maintain contextual coherence.
4. Assembly and Export: Components are merged into the final Markdown, DOCX, or PDF output.