# raga-ai-hub/ragaai-catalyst architecture

> Architecture diagram of the GitHub repository raga-ai-hub/ragaai-catalyst, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/raga-ai-hub/ragaai-catalyst
- Repository: https://github.com/raga-ai-hub/ragaai-catalyst

## Overview

RagaAI Catalyst is a Python client for managing LLM projects and their datasets, evaluations, prompts, and safeguards, alongside data-generation and tracing workflows. Users authenticate through the client, then call management APIs; tracing records application activity and uploads it for analysis, while red-teaming generates and evaluates adversarial cases. The README documents the major capabilities, and the source index supports several internal tracing and red-teaming relationships. Some branches are represented by their documented entry modules because their implementation was not sampled; uncertain runtime links are omitted.

Main entry points: [`ragaai_catalyst/tracers/tracer.py`](https://github.com/raga-ai-hub/ragaai-catalyst/blob/main/ragaai_catalyst/tracers/tracer.py) (Trace management), [`ragaai_catalyst/redteaming/red_teaming.py`](https://github.com/raga-ai-hub/ragaai-catalyst/blob/main/ragaai_catalyst/redteaming/red_teaming.py) (Red-team workflow), [`ragaai_catalyst/tracers/agentic_tracing/tracers/base.py`](https://github.com/raga-ai-hub/ragaai-catalyst/blob/main/ragaai_catalyst/tracers/agentic_tracing/tracers/base.py) (Trace lifecycle), [`ragaai_catalyst/synthetic_data_generation.py`](https://github.com/raga-ai-hub/ragaai-catalyst/blob/main/ragaai_catalyst/synthetic_data_generation.py) (Synthetic data)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Project management"]
  node_client["Catalyst client<br/>[ragaai_catalyst.py]"]
  node_projects["Project operations<br/>[ragaai_catalyst.py]"]
end

subgraph group_data["Data and evaluation"]
  node_dataset["Dataset management<br/>[dataset.py]"]
  node_evaluation["Metric evaluation<br/>[evaluation.py]"]
  node_experiment["Experiment management<br/>[experiment.py]"]
end

subgraph group_trace["Tracing"]
  node_tracer["Trace management<br/>[tracer.py]"]
  node_callbacks["Framework callbacks"]
  node_agentic["Agentic tracers<br/>[llm_tracer.py]"]
  node_trace_model["Trace data model<br/>[data_structure.py]"]
  node_trace_base["Trace lifecycle<br/>[base.py]"]
  node_trace_upload["Agentic upload<br/>[trace_uploader.py]"]
  node_trace_export["Trace export<br/>[raga_exporter.py]"]
end

subgraph group_safety["Safety and prompts"]
  node_guardrails["Guardrail management"]
  node_guard_exec["Guard execution<br/>[guard_executor.py]"]
  node_prompts["Prompt management<br/>[prompt_manager.py]"]
  node_redteam["Red-team workflow<br/>[red_teaming.py]"]
  node_scenarios["Scenario generation"]
  node_red_eval["Adversarial evaluation<br/>[evaluator.py]"]
  node_llm_gen["LLM generation<br/>[llm_generator.py]"]
end

subgraph group_generation["Data generation"]
  node_synthetic["Synthetic data"]
  node_proxy["Proxy calls<br/>[proxy_call.py]"]
  node_internal_completion["Completion API"]
end

node_user(("Catalyst user"))
node_platform[("Catalyst platform")]
node_llm_provider(("LLM provider"))

node_user -->|"initializes"| node_client
node_client -->|"authenticates"| node_platform
node_user -->|"manages projects"| node_projects
node_user -->|"manages datasets"| node_dataset
node_user -->|"runs evaluations"| node_evaluation
node_evaluation -->|"evaluates dataset"| node_dataset
node_user -->|"records traces"| node_tracer
node_tracer -->|"uses callbacks"| node_callbacks
node_tracer -->|"initializes"| node_agentic
node_agentic -->|"extends"| node_trace_base
node_trace_base -->|"constructs"| node_trace_model
node_trace_base -->|"submits uploads"| node_trace_upload
node_tracer -->|"configures exporter"| node_trace_export
node_trace_export -->|"uploads traces"| node_platform
node_user -->|"manages prompts"| node_prompts
node_user -->|"manages safeguards"| node_guardrails
node_user -->|"executes safeguards"| node_guard_exec
node_user -->|"tests applications"| node_redteam
node_redteam -->|"generates scenarios"| node_scenarios
node_redteam -->|"evaluates cases"| node_red_eval
node_redteam -->|"uses generation"| node_llm_gen
node_scenarios -->|"generates with"| node_llm_gen
node_user -->|"generates data"| node_synthetic
node_synthetic -->|"uses proxy"| node_proxy
node_synthetic -->|"calls completion"| node_internal_completion
node_llm_gen -->|"requests generation"| node_llm_provider
node_guardrails -->|"sends requests"| node_platform

click node_client "https://github.com/raga-ai-hub/ragaai-catalyst/blob/main/ragaai_catalyst/ragaai_catalyst.py"
click node_projects "https://github.com/raga-ai-hub/ragaai-catalyst/blob/main/ragaai_catalyst/ragaai_catalyst.py"
click node_dataset "https://github.com/raga-ai-hub/ragaai-catalyst/blob/main/ragaai_catalyst/dataset.py"
click node_evaluation "https://github.com/raga-ai-hub/ragaai-catalyst/blob/main/ragaai_catalyst/evaluation.py"
click node_experiment "https://github.com/raga-ai-hub/ragaai-catalyst/blob/main/ragaai_catalyst/experiment.py"
click node_tracer "https://github.com/raga-ai-hub/ragaai-catalyst/blob/main/ragaai_catalyst/tracers/tracer.py"
click node_callbacks "https://github.com/raga-ai-hub/ragaai-catalyst/blob/main/ragaai_catalyst/tracers/langchain_callback.py"
click node_agentic "https://github.com/raga-ai-hub/ragaai-catalyst/blob/main/ragaai_catalyst/tracers/agentic_tracing/tracers/llm_tracer.py"
click node_trace_model "https://github.com/raga-ai-hub/ragaai-catalyst/blob/main/ragaai_catalyst/tracers/agentic_tracing/data/data_structure.py"
click node_trace_base "https://github.com/raga-ai-hub/ragaai-catalyst/blob/main/ragaai_catalyst/tracers/agentic_tracing/tracers/base.py"
click node_trace_upload "https://github.com/raga-ai-hub/ragaai-catalyst/blob/main/ragaai_catalyst/tracers/agentic_tracing/upload/trace_uploader.py"
click node_trace_export "https://github.com/raga-ai-hub/ragaai-catalyst/blob/main/ragaai_catalyst/tracers/exporters/raga_exporter.py"
click node_guardrails "https://github.com/raga-ai-hub/ragaai-catalyst/blob/main/ragaai_catalyst/guardrails_manager.py"
click node_guard_exec "https://github.com/raga-ai-hub/ragaai-catalyst/blob/main/ragaai_catalyst/guard_executor.py"
click node_prompts "https://github.com/raga-ai-hub/ragaai-catalyst/blob/main/ragaai_catalyst/prompt_manager.py"
click node_redteam "https://github.com/raga-ai-hub/ragaai-catalyst/blob/main/ragaai_catalyst/redteaming/red_teaming.py"
click node_scenarios "https://github.com/raga-ai-hub/ragaai-catalyst/blob/main/ragaai_catalyst/redteaming/data_generator/scenario_generator.py"
click node_red_eval "https://github.com/raga-ai-hub/ragaai-catalyst/blob/main/ragaai_catalyst/redteaming/evaluator.py"
click node_llm_gen "https://github.com/raga-ai-hub/ragaai-catalyst/blob/main/ragaai_catalyst/redteaming/llm_generator.py"
click node_synthetic "https://github.com/raga-ai-hub/ragaai-catalyst/blob/main/ragaai_catalyst/synthetic_data_generation.py"
click node_proxy "https://github.com/raga-ai-hub/ragaai-catalyst/blob/main/ragaai_catalyst/proxy_call.py"
click node_internal_completion "https://github.com/raga-ai-hub/ragaai-catalyst/blob/main/ragaai_catalyst/internal_api_completion.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_client,node_projects,node_user toneBlue
class node_dataset,node_evaluation,node_experiment,node_platform toneAmber
class node_tracer,node_callbacks,node_agentic,node_trace_model,node_trace_base,node_trace_upload,node_trace_export toneMint
class node_guardrails,node_guard_exec,node_prompts,node_redteam,node_scenarios,node_red_eval,node_llm_gen toneRose
class node_synthetic,node_proxy,node_internal_completion,node_llm_provider toneIndigo
```

## Components

### Project management

- [Catalyst client](https://github.com/raga-ai-hub/ragaai-catalyst/blob/main/ragaai_catalyst/ragaai_catalyst.py): `ragaai_catalyst/ragaai_catalyst.py`
- [Project operations](https://github.com/raga-ai-hub/ragaai-catalyst/blob/main/ragaai_catalyst/ragaai_catalyst.py): `ragaai_catalyst/ragaai_catalyst.py`

### Data and evaluation

- [Dataset management](https://github.com/raga-ai-hub/ragaai-catalyst/blob/main/ragaai_catalyst/dataset.py): `ragaai_catalyst/dataset.py`
- [Metric evaluation](https://github.com/raga-ai-hub/ragaai-catalyst/blob/main/ragaai_catalyst/evaluation.py): `ragaai_catalyst/evaluation.py`
- [Experiment management](https://github.com/raga-ai-hub/ragaai-catalyst/blob/main/ragaai_catalyst/experiment.py): `ragaai_catalyst/experiment.py`

### Tracing

- [Trace management](https://github.com/raga-ai-hub/ragaai-catalyst/blob/main/ragaai_catalyst/tracers/tracer.py): `ragaai_catalyst/tracers/tracer.py`
- [Framework callbacks](https://github.com/raga-ai-hub/ragaai-catalyst/blob/main/ragaai_catalyst/tracers/langchain_callback.py): `ragaai_catalyst/tracers/langchain_callback.py`
- [Agentic tracers](https://github.com/raga-ai-hub/ragaai-catalyst/blob/main/ragaai_catalyst/tracers/agentic_tracing/tracers/llm_tracer.py): `ragaai_catalyst/tracers/agentic_tracing/tracers/llm_tracer.py`
- [Trace data model](https://github.com/raga-ai-hub/ragaai-catalyst/blob/main/ragaai_catalyst/tracers/agentic_tracing/data/data_structure.py): `ragaai_catalyst/tracers/agentic_tracing/data/data_structure.py`
- [Trace lifecycle](https://github.com/raga-ai-hub/ragaai-catalyst/blob/main/ragaai_catalyst/tracers/agentic_tracing/tracers/base.py): `ragaai_catalyst/tracers/agentic_tracing/tracers/base.py`
- [Agentic upload](https://github.com/raga-ai-hub/ragaai-catalyst/blob/main/ragaai_catalyst/tracers/agentic_tracing/upload/trace_uploader.py): `ragaai_catalyst/tracers/agentic_tracing/upload/trace_uploader.py`
- [Trace export](https://github.com/raga-ai-hub/ragaai-catalyst/blob/main/ragaai_catalyst/tracers/exporters/raga_exporter.py): `ragaai_catalyst/tracers/exporters/raga_exporter.py`

### Safety and prompts

- [Guardrail management](https://github.com/raga-ai-hub/ragaai-catalyst/blob/main/ragaai_catalyst/guardrails_manager.py): `ragaai_catalyst/guardrails_manager.py`
- [Guard execution](https://github.com/raga-ai-hub/ragaai-catalyst/blob/main/ragaai_catalyst/guard_executor.py): `ragaai_catalyst/guard_executor.py`
- [Prompt management](https://github.com/raga-ai-hub/ragaai-catalyst/blob/main/ragaai_catalyst/prompt_manager.py): `ragaai_catalyst/prompt_manager.py`
- [Red-team workflow](https://github.com/raga-ai-hub/ragaai-catalyst/blob/main/ragaai_catalyst/redteaming/red_teaming.py): `ragaai_catalyst/redteaming/red_teaming.py`
- [Scenario generation](https://github.com/raga-ai-hub/ragaai-catalyst/blob/main/ragaai_catalyst/redteaming/data_generator/scenario_generator.py): `ragaai_catalyst/redteaming/data_generator/scenario_generator.py`
- [Adversarial evaluation](https://github.com/raga-ai-hub/ragaai-catalyst/blob/main/ragaai_catalyst/redteaming/evaluator.py): `ragaai_catalyst/redteaming/evaluator.py`
- [LLM generation](https://github.com/raga-ai-hub/ragaai-catalyst/blob/main/ragaai_catalyst/redteaming/llm_generator.py): `ragaai_catalyst/redteaming/llm_generator.py`

### Data generation

- [Synthetic data](https://github.com/raga-ai-hub/ragaai-catalyst/blob/main/ragaai_catalyst/synthetic_data_generation.py): `ragaai_catalyst/synthetic_data_generation.py`
- [Proxy calls](https://github.com/raga-ai-hub/ragaai-catalyst/blob/main/ragaai_catalyst/proxy_call.py): `ragaai_catalyst/proxy_call.py`
- [Completion API](https://github.com/raga-ai-hub/ragaai-catalyst/blob/main/ragaai_catalyst/internal_api_completion.py): `ragaai_catalyst/internal_api_completion.py`

### Other components

- **Catalyst user**
- **Catalyst platform**
- **LLM provider**

## Connections

- Catalyst user → Catalyst client: initializes (evidence: `README.md`)
- Catalyst client → Catalyst platform: authenticates (evidence: `ragaai_catalyst/ragaai_catalyst.py`)
- Catalyst user → Project operations: manages projects (evidence: `README.md`)
- Catalyst user → Dataset management: manages datasets (evidence: `README.md`)
- Catalyst user → Metric evaluation: runs evaluations (evidence: `README.md`)
- Metric evaluation → Dataset management: evaluates dataset (evidence: `README.md`)
- Catalyst user → Trace management: records traces (evidence: `README.md`)
- Trace management → Framework callbacks: uses callbacks (evidence: `ragaai_catalyst/tracers/tracer.py`)
- Trace management → Agentic tracers: initializes (evidence: `ragaai_catalyst/tracers/tracer.py`)
- Agentic tracers → Trace lifecycle: extends (evidence: `ragaai_catalyst/tracers/agentic_tracing/tracers/llm_tracer.py`)
- Trace lifecycle → Trace data model: constructs (evidence: `ragaai_catalyst/tracers/agentic_tracing/tracers/base.py`)
- Trace lifecycle → Agentic upload: submits uploads (evidence: `ragaai_catalyst/tracers/agentic_tracing/tracers/base.py`)
- Trace management → Trace export: configures exporter (evidence: `ragaai_catalyst/tracers/tracer.py`)
- Trace export → Catalyst platform: uploads traces (evidence: `ragaai_catalyst/tracers/exporters/raga_exporter.py`)
- Catalyst user → Prompt management: manages prompts (evidence: `README.md`)
- Catalyst user → Guardrail management: manages safeguards (evidence: `README.md`)
- Catalyst user → Guard execution: executes safeguards (evidence: `README.md`)
- Catalyst user → Red-team workflow: tests applications (evidence: `README.md`)
- Red-team workflow → Scenario generation: generates scenarios (evidence: `ragaai_catalyst/redteaming/red_teaming.py`)
- Red-team workflow → Adversarial evaluation: evaluates cases (evidence: `ragaai_catalyst/redteaming/red_teaming.py`)
- Red-team workflow → LLM generation: uses generation (evidence: `ragaai_catalyst/redteaming/red_teaming.py`)
- Scenario generation → LLM generation: generates with (evidence: `ragaai_catalyst/redteaming/data_generator/scenario_generator.py`)
- Catalyst user → Synthetic data: generates data (evidence: `README.md`)
- Synthetic data → Proxy calls: uses proxy (evidence: `ragaai_catalyst/synthetic_data_generation.py`)
- Synthetic data → Completion API: calls completion (evidence: `ragaai_catalyst/synthetic_data_generation.py`)
- LLM generation → LLM provider: requests generation (evidence: `ragaai_catalyst/redteaming/llm_generator.py`)
- Guardrail management → Catalyst platform: sends requests (evidence: `ragaai_catalyst/guardrails_manager.py`)
