# zaheerjklabs/sagecli architecture

> Architecture diagram of the GitHub repository zaheerjklabs/sagecli, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zaheerjklabs/sagecli
- Repository: https://github.com/zaheerjklabs/sagecli

## Overview

SageCLI is a terminal-based autonomous AI engineering agent for ML/DL workspaces. A developer starts an interactive session or supplies a task; the agent gathers repository and dataset context, plans and generates changes with an LLM, then uses workspace tools to execute, test, debug, evaluate, and manage Git checkpoints. Configuration and setup select the provider and execution mode, while project state tracks memory and metrics. The README documents deployment and several slash-command capabilities beyond the sampled source; those are represented at their documented subsystem paths, without implying unverified internal wiring.

Main entry points: [`src/sagecli/core/agent.py`](https://github.com/zaheerjklabs/sagecli/blob/main/src/sagecli/core/agent.py) (Agent Execution Loop), [`src/sagecli/tools/registry.py`](https://github.com/zaheerjklabs/sagecli/blob/main/src/sagecli/tools/registry.py) (Tool Registry), [`src/sagecli/cli.py`](https://github.com/zaheerjklabs/sagecli/blob/main/src/sagecli/cli.py) (CLI and REPL), [`src/sagecli/llm/factory.py`](https://github.com/zaheerjklabs/sagecli/blob/main/src/sagecli/llm/factory.py) (Provider Factory)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI and Setup"]
  node_cli["CLI and REPL<br/>[cli.py]"]
  node_wizard["Setup Wizard<br/>[wizard.py]"]
  node_config["Provider Configuration<br/>[config.py]"]
end

subgraph group_agent["Agent Workflow"]
  node_agent_loop["Agent Execution Loop<br/>[agent.py]"]
  node_context["Workspace Context<br/>[context.py]"]
  node_planning["ML Pipeline Planning<br/>[orchestrator.py]"]
end

subgraph group_providers["LLM Providers"]
  node_provider_factory["Provider Factory<br/>[factory.py]"]
  node_gemini["Gemini Adapter<br/>[gemini_provider.py]"]
  node_openai["OpenAI-Compatible Adapter<br/>[openai_provider.py]"]
  node_anthropic["Anthropic Adapter"]
end

subgraph group_tools["Workspace Tools"]
  node_registry["Tool Registry<br/>[registry.py]"]
  node_dataset["Dataset Inspection<br/>[dataset_ops.py]"]
  node_files["File Operations<br/>[file_ops.py]"]
  node_execution["Command Execution<br/>[shell_ops.py]"]
  node_testing["Test and Evaluation<br/>[test_eval_ops.py]"]
  node_git["Git Checkpoints<br/>[git_ops.py]"]
end

subgraph group_support["Project Support"]
  node_state[("Memory and Metrics<br/>[state.py]")]
  node_tracker["Usage Tracking<br/>[tracker.py]"]
  node_doctor["Environment Diagnostics<br/>[doctor.py]"]
  node_security["Safety Checks<br/>[security.py]"]
end

node_developer(("Developer"))
node_workspace["Project Workspace"]
node_provider_apis(("LLM Services"))

node_developer -->|"starts tasks"| node_cli
node_cli -->|"configures setup"| node_wizard
node_wizard -->|"validates credentials"| node_provider_factory
node_wizard -->|"saves settings"| node_config
node_cli -->|"loads settings"| node_config
node_cli -->|"dispatches task"| node_agent_loop
node_agent_loop -->|"gathers context"| node_context
node_agent_loop -->|"builds instructions"| node_planning
node_agent_loop -->|"requests model"| node_provider_factory
node_provider_factory -->|"creates adapter"| node_gemini
node_provider_factory -->|"creates adapter"| node_openai
node_provider_factory -->|"creates adapter"| node_anthropic
node_gemini -->|"sends requests"| node_provider_apis
node_openai -->|"sends requests"| node_provider_apis
node_anthropic -->|"sends requests"| node_provider_apis
node_agent_loop -->|"dispatches tools"| node_registry
node_registry -->|"runs inspection"| node_dataset
node_registry -->|"runs file actions"| node_files
node_registry -->|"runs commands"| node_execution
node_registry -->|"runs tests"| node_testing
node_registry -->|"runs Git actions"| node_git
node_dataset -->|"reads datasets"| node_workspace
node_context -->|"scans workspace"| node_workspace
node_files -->|"reads and writes"| node_workspace
node_execution -->|"executes in"| node_workspace
node_testing -->|"tests project"| node_workspace
node_git -->|"manages changes"| node_workspace
node_registry -->|"checks permissions"| node_security
node_agent_loop -->|"persists task memory"| node_state
node_agent_loop -->|"tracks usage"| node_tracker
node_cli -->|"runs diagnostics"| node_doctor
node_agent_loop -->|"delivers changes"| node_workspace

click node_cli "https://github.com/zaheerjklabs/sagecli/blob/main/src/sagecli/cli.py"
click node_wizard "https://github.com/zaheerjklabs/sagecli/blob/main/src/sagecli/wizard.py"
click node_config "https://github.com/zaheerjklabs/sagecli/blob/main/src/sagecli/config.py"
click node_agent_loop "https://github.com/zaheerjklabs/sagecli/blob/main/src/sagecli/core/agent.py"
click node_context "https://github.com/zaheerjklabs/sagecli/blob/main/src/sagecli/core/context.py"
click node_planning "https://github.com/zaheerjklabs/sagecli/blob/main/src/sagecli/core/orchestrator.py"
click node_state "https://github.com/zaheerjklabs/sagecli/blob/main/src/sagecli/core/state.py"
click node_tracker "https://github.com/zaheerjklabs/sagecli/blob/main/src/sagecli/core/tracker.py"
click node_doctor "https://github.com/zaheerjklabs/sagecli/blob/main/src/sagecli/core/doctor.py"
click node_provider_factory "https://github.com/zaheerjklabs/sagecli/blob/main/src/sagecli/llm/factory.py"
click node_gemini "https://github.com/zaheerjklabs/sagecli/blob/main/src/sagecli/llm/gemini_provider.py"
click node_openai "https://github.com/zaheerjklabs/sagecli/blob/main/src/sagecli/llm/openai_provider.py"
click node_anthropic "https://github.com/zaheerjklabs/sagecli/blob/main/src/sagecli/llm/anthropic_provider.py"
click node_registry "https://github.com/zaheerjklabs/sagecli/blob/main/src/sagecli/tools/registry.py"
click node_dataset "https://github.com/zaheerjklabs/sagecli/blob/main/src/sagecli/tools/dataset_ops.py"
click node_files "https://github.com/zaheerjklabs/sagecli/blob/main/src/sagecli/tools/file_ops.py"
click node_execution "https://github.com/zaheerjklabs/sagecli/blob/main/src/sagecli/tools/shell_ops.py"
click node_testing "https://github.com/zaheerjklabs/sagecli/blob/main/src/sagecli/tools/test_eval_ops.py"
click node_git "https://github.com/zaheerjklabs/sagecli/blob/main/src/sagecli/tools/git_ops.py"
click node_security "https://github.com/zaheerjklabs/sagecli/blob/main/src/sagecli/security.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_wizard,node_config toneBlue
class node_agent_loop,node_context,node_planning toneAmber
class node_provider_factory,node_gemini,node_openai,node_anthropic toneMint
class node_registry,node_dataset,node_files,node_execution,node_testing,node_git toneRose
class node_state,node_tracker,node_doctor,node_security,node_developer,node_workspace,node_provider_apis toneIndigo
```

## Components

### CLI and Setup

- [CLI and REPL](https://github.com/zaheerjklabs/sagecli/blob/main/src/sagecli/cli.py): `src/sagecli/cli.py`
- [Setup Wizard](https://github.com/zaheerjklabs/sagecli/blob/main/src/sagecli/wizard.py): `src/sagecli/wizard.py`
- [Provider Configuration](https://github.com/zaheerjklabs/sagecli/blob/main/src/sagecli/config.py): `src/sagecli/config.py`

### Agent Workflow

- [Agent Execution Loop](https://github.com/zaheerjklabs/sagecli/blob/main/src/sagecli/core/agent.py): `src/sagecli/core/agent.py`
- [Workspace Context](https://github.com/zaheerjklabs/sagecli/blob/main/src/sagecli/core/context.py): `src/sagecli/core/context.py`
- [ML Pipeline Planning](https://github.com/zaheerjklabs/sagecli/blob/main/src/sagecli/core/orchestrator.py): `src/sagecli/core/orchestrator.py`

### LLM Providers

- [Provider Factory](https://github.com/zaheerjklabs/sagecli/blob/main/src/sagecli/llm/factory.py): `src/sagecli/llm/factory.py`
- [Gemini Adapter](https://github.com/zaheerjklabs/sagecli/blob/main/src/sagecli/llm/gemini_provider.py): `src/sagecli/llm/gemini_provider.py`
- [OpenAI-Compatible Adapter](https://github.com/zaheerjklabs/sagecli/blob/main/src/sagecli/llm/openai_provider.py): `src/sagecli/llm/openai_provider.py`
- [Anthropic Adapter](https://github.com/zaheerjklabs/sagecli/blob/main/src/sagecli/llm/anthropic_provider.py): `src/sagecli/llm/anthropic_provider.py`

### Workspace Tools

- [Tool Registry](https://github.com/zaheerjklabs/sagecli/blob/main/src/sagecli/tools/registry.py): `src/sagecli/tools/registry.py`
- [Dataset Inspection](https://github.com/zaheerjklabs/sagecli/blob/main/src/sagecli/tools/dataset_ops.py): `src/sagecli/tools/dataset_ops.py`
- [File Operations](https://github.com/zaheerjklabs/sagecli/blob/main/src/sagecli/tools/file_ops.py): `src/sagecli/tools/file_ops.py`
- [Command Execution](https://github.com/zaheerjklabs/sagecli/blob/main/src/sagecli/tools/shell_ops.py): `src/sagecli/tools/shell_ops.py`
- [Test and Evaluation](https://github.com/zaheerjklabs/sagecli/blob/main/src/sagecli/tools/test_eval_ops.py): `src/sagecli/tools/test_eval_ops.py`
- [Git Checkpoints](https://github.com/zaheerjklabs/sagecli/blob/main/src/sagecli/tools/git_ops.py): `src/sagecli/tools/git_ops.py`

### Project Support

- [Memory and Metrics](https://github.com/zaheerjklabs/sagecli/blob/main/src/sagecli/core/state.py): `src/sagecli/core/state.py`
- [Usage Tracking](https://github.com/zaheerjklabs/sagecli/blob/main/src/sagecli/core/tracker.py): `src/sagecli/core/tracker.py`
- [Environment Diagnostics](https://github.com/zaheerjklabs/sagecli/blob/main/src/sagecli/core/doctor.py): `src/sagecli/core/doctor.py`
- [Safety Checks](https://github.com/zaheerjklabs/sagecli/blob/main/src/sagecli/security.py): `src/sagecli/security.py`

### Other components

- **Developer**
- **Project Workspace**
- **LLM Services**

## Connections

- Developer → CLI and REPL: starts tasks
- CLI and REPL → Setup Wizard: configures setup
- Setup Wizard → Provider Factory: validates credentials
- Setup Wizard → Provider Configuration: saves settings
- CLI and REPL → Provider Configuration: loads settings
- CLI and REPL → Agent Execution Loop: dispatches task
- Agent Execution Loop → Workspace Context: gathers context
- Agent Execution Loop → ML Pipeline Planning: builds instructions
- Agent Execution Loop → Provider Factory: requests model
- Provider Factory → Gemini Adapter: creates adapter
- Provider Factory → OpenAI-Compatible Adapter: creates adapter
- Provider Factory → Anthropic Adapter: creates adapter
- Gemini Adapter → LLM Services: sends requests
- OpenAI-Compatible Adapter → LLM Services: sends requests
- Anthropic Adapter → LLM Services: sends requests
- Agent Execution Loop → Tool Registry: dispatches tools
- Tool Registry → Dataset Inspection: runs inspection
- Tool Registry → File Operations: runs file actions
- Tool Registry → Command Execution: runs commands
- Tool Registry → Test and Evaluation: runs tests
- Tool Registry → Git Checkpoints: runs Git actions
- Dataset Inspection → Project Workspace: reads datasets
- Workspace Context → Project Workspace: scans workspace
- File Operations → Project Workspace: reads and writes
- Command Execution → Project Workspace: executes in
- Test and Evaluation → Project Workspace: tests project
- Git Checkpoints → Project Workspace: manages changes
- Tool Registry → Safety Checks: checks permissions
- Agent Execution Loop → Memory and Metrics: persists task memory
- Agent Execution Loop → Usage Tracking: tracks usage
- CLI and REPL → Environment Diagnostics: runs diagnostics
- Agent Execution Loop → Project Workspace: delivers changes