# sarthakrastogi/rival architecture

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

- Interactive diagram: https://gitdiagram.com/sarthakrastogi/rival
- Repository: https://github.com/sarthakrastogi/rival

## Overview

##### Project type and purpose
- This is an open-source Python library and SDK (“Rival AI”) for AI safety in production:
- Real-time attack detection (two built-in detectors: Bhairava & Narasimha)
- Automated red-teaming and benchmarking of AI agents
- Consumers install the package, import detectors/evaluators/generators, and integrate into their own AI pipelines.

##### File structure
- Top-level:
- setup.py, requirements.txt → Python packaging
- src/rival_ai → core code
- examples/ → usage examples for attack detection & red-teaming
- tests/ → unit and integration tests
- src/rival_ai/core/ → fundamental abstractions: AgentDefinition, Testcase, Benchmarking, Evaluation
- src/rival_ai/detectors/ → plugin detectors (Bhairava, Narasimha), each with data/models/training utilities
- src/rival_ai/generators/ → attack_criteria definitions and testcase_generator
- src/rival_ai/evaluators/ → local_evaluator and prompt templates
- src/rival_ai/utils/ → LLM wrappers, parsing, agent representation

##### README for additional insights
- Highlights two detection models (Bhairava-0.4B, Narasimha-0.6B)
- Describes “detect_attack” APIs, “detect_attack_with_details” for reasoning
- Mentions red-teaming: automated generation + running of attack scenarios

##### Detail
- Subcomponents (e.g., detectors/bhairava/models/classifier.py vs. detectors/narasimha/detector.py)
- How config.py drives environment settings
- Example scripts folder as “Usage Examples” block

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Consumer
    ConsumerAgent["Consumer AI Agent"]:::external

    %% SDK Core Layer
    subgraph "SDK Core Layer"
        direction TB
        AgentDefinition["AgentDefinition"]:::core
        Testcase["Testcase"]:::core
        Benchmarking["Benchmarking"]:::core
        BenchmarkingResult["BenchmarkingResult"]:::core
        Evaluation["Evaluation"]:::core
    end

    %% Detector Plugins
    subgraph "Detector Module" 
        direction TB
        BhairavaDetector["BhairavaAttackDetector"]:::detector
        DatasetUtils["Bhairava Dataset Utils"]:::detector
        ClassifierModel["Bhairava Classifier Model"]:::detector
        Trainer["Bhairava Trainer"]:::detector
        Preprocessing["Bhairava Preprocessing"]:::detector
        NarasimhaDetector["NarasimhaAttackDetector"]:::detector
    end

    %% Generator & Evaluator
    subgraph "Generator & Evaluator Module"
        direction TB
        AttackCriteriaRegistry["AttackCriteriaRegistry"]:::genEval
        CriteriaModels["CriteriaModels"]:::genEval
        HarmfulContentAttack["HarmfulContentAttack"]:::genEval
        PrivacyAttack["PrivacyAndDataSecurityAttack"]:::genEval
        PromptManipulationAttack["PromptManipulationAttack"]:::genEval
        TestcaseGenerator["TestcaseGenerator"]:::genEval
        LocalEvaluator["LocalEvaluator"]:::genEval
        PromptTemplates["PromptTemplates"]:::genEval
    end

    %% Utility Layer
    subgraph "Utility Layer"
        direction TB
        LLMWrapper["LLM API Wrappers"]:::util
        AgentRepresentation["AgentRepresentation Utils"]:::util
        ParsingHelpers["Output Parsing Helpers"]:::util
    end

    %% Configuration
    Config["Configuration (config.py)"]:::core

    %% Examples
    subgraph "Usage Examples"
        direction TB
        AttackExamples["Attack Detection Examples"]:::external
        RedTeamingExamples["Red-Teaming Examples"]:::external
        SampleAgents["Sample Agent Scripts"]:::external
        Snippets["Code Snippets"]:::external
    end

    %% Tests
    subgraph "Tests"
        direction TB
        CoreTests["Core Tests"]:::external
        DetectorTests["Detector Tests"]:::external
        GeneratorTests["Generator Tests"]:::external
        Conftest["Conftest & Fixtures"]:::external
    end

    %% External Systems & Storage
    ExternalLLM["External LLMs\n(OpenAI/HuggingFace)"]:::external
    ModelFiles["Model Artifacts"]:::datastore
    Datasets["Datasets"]:::datastore
    LogsStorage["Logs & Benchmark Results"]:::datastore

    %% Relationships
    ConsumerAgent -->|"uses SDK"| AgentDefinition
    ConsumerAgent -->|"imports detectors"| BhairavaDetector
    ConsumerAgent --> NarasimhaDetector
    BhairavaDetector --> DatasetUtils
    BhairavaDetector --> ClassifierModel
    BhairavaDetector --> Trainer
    BhairavaDetector --> Preprocessing
    NarasimhaDetector -->|"loads model"| ExternalLLM

    ConsumerAgent -->|"requests attack detection"| BhairavaDetector
    ConsumerAgent -->|"requests attack detection"| NarasimhaDetector
    BhairavaDetector -->|"returns {is_attack,confidence,reasoning}"| ConsumerAgent
    NarasimhaDetector -->|"returns {is_attack,confidence,reasoning}"| ConsumerAgent

    ConsumerAgent -->|"calls TestcaseGenerator"| TestcaseGenerator
    TestcaseGenerator -->|"generates prompts"| ConsumerAgent
    ConsumerAgent -->|"agent responds"| LocalEvaluator
    ConsumerAgent -->|"agent responds"| Benchmarking
    LocalEvaluator --> PromptTemplates
    Benchmarking --> BenchmarkingResult
    BenchmarkingResult --> LogsStorage

    AgentDefinition --> Evaluation
    Testcase --> TestcaseGenerator
    Evaluation --> LocalEvaluator

    AgentDefinition --> AgentRepresentation
    ConsumerAgent --> LLMWrapper
    ConsumerAgent --> ParsingHelpers

    Config --> AgentDefinition
    Config --> BhairavaDetector
    Config --> NarasimhaDetector
    Config --> TestcaseGenerator
    Config --> LocalEvaluator

    ConsumerAgent --> AttackExamples
    ConsumerAgent --> RedTeamingExamples
    ConsumerAgent --> SampleAgents
    ConsumerAgent --> Snippets

    CoreTests --> AgentDefinition
    DetectorTests --> BhairavaDetector
    DetectorTests --> NarasimhaDetector
    GeneratorTests --> TestcaseGenerator
    Conftest -->|fixtures| DetectorTests
    Conftest --> CoreTests
    Conftest --> GeneratorTests

    ExternalLLM --> LLMWrapper
    DatasetUtils --> Datasets
    ClassifierModel --> ModelFiles
    Trainer --> ModelFiles
    LogsStorage -->|"stores"| LogsStorage

    %% Click Events
    click AgentDefinition "https://github.com/sarthakrastogi/rival/blob/main/src/rival_ai/core/agent_definition.py"
    click Testcase "https://github.com/sarthakrastogi/rival/blob/main/src/rival_ai/core/testcase.py"
    click Benchmarking "https://github.com/sarthakrastogi/rival/blob/main/src/rival_ai/core/benchmarking.py"
    click BenchmarkingResult "https://github.com/sarthakrastogi/rival/blob/main/src/rival_ai/core/benchmarking_result.py"
    click Evaluation "https://github.com/sarthakrastogi/rival/blob/main/src/rival_ai/core/evaluation.py"
    click BhairavaDetector "https://github.com/sarthakrastogi/rival/blob/main/src/rival_ai/detectors/bhairava/detector.py"
    click DatasetUtils "https://github.com/sarthakrastogi/rival/blob/main/src/rival_ai/detectors/bhairava/data/dataset.py"
    click ClassifierModel "https://github.com/sarthakrastogi/rival/blob/main/src/rival_ai/detectors/bhairava/models/classifier.py"
    click Trainer "https://github.com/sarthakrastogi/rival/blob/main/src/rival_ai/detectors/bhairava/models/trainer.py"
    click Trainer "https://github.com/sarthakrastogi/rival/blob/main/src/rival_ai/detectors/bhairava/train_and_deploy.py"
    click Preprocessing "https://github.com/sarthakrastogi/rival/blob/main/src/rival_ai/detectors/bhairava/utils/preprocessing.py"
    click NarasimhaDetector "https://github.com/sarthakrastogi/rival/blob/main/src/rival_ai/detectors/narasimha/detector.py"
    click AttackCriteriaRegistry "https://github.com/sarthakrastogi/rival/blob/main/src/rival_ai/generators/attack_criteria/registry.py"
    click CriteriaModels "https://github.com/sarthakrastogi/rival/blob/main/src/rival_ai/generators/attack_criteria/models.py"
    click HarmfulContentAttack "https://github.com/sarthakrastogi/rival/blob/main/src/rival_ai/generators/attack_criteria/attacks/harmful_content_generation.py"
    click PrivacyAttack "https://github.com/sarthakrastogi/rival/blob/main/src/rival_ai/generators/attack_criteria/attacks/privacy_and_data_security.py"
    click PromptManipulationAttack "https://github.com/sarthakrastogi/rival/blob/main/src/rival_ai/generators/attack_criteria/attacks/prompt_manipulation_and_instruction_adherence.py"
    click TestcaseGenerator "https://github.com/sarthakrastogi/rival/blob/main/src/rival_ai/generators/testcase_generator.py"
    click LocalEvaluator "https://github.com/sarthakrastogi/rival/blob/main/src/rival_ai/evaluators/local_evaluator.py"
    click PromptTemplates "https://github.com/sarthakrastogi/rival/blob/main/src/rival_ai/evaluators/prompts.py"
    click LLMWrapper "https://github.com/sarthakrastogi/rival/blob/main/src/rival_ai/utils/llm.py"
    click AgentRepresentation "https://github.com/sarthakrastogi/rival/blob/main/src/rival_ai/utils/agent_representation.py"
    click ParsingHelpers "https://github.com/sarthakrastogi/rival/blob/main/src/rival_ai/utils/parsing.py"
    click Config "https://github.com/sarthakrastogi/rival/blob/main/src/rival_ai/config.py"
    click AttackExamples "https://github.com/sarthakrastogi/rival/blob/main/examples/embedding_based_attack_detection.md"
    click RedTeamingExamples "https://github.com/sarthakrastogi/rival/blob/main/examples/red_teaming.md"
    click SampleAgents "https://github.com/sarthakrastogi/rival/blob/main/examples/sample_agents/customer_support.py"
    click SampleAgents "https://github.com/sarthakrastogi/rival/blob/main/examples/sample_agents/travel_recommedation.py"
    click Snippets "https://github.com/sarthakrastogi/rival/tree/main/examples/snippets/"
    click CoreTests "https://github.com/sarthakrastogi/rival/tree/main/tests/test_core/"
    click DetectorTests "https://github.com/sarthakrastogi/rival/tree/main/tests/test_detectors/"
    click GeneratorTests "https://github.com/sarthakrastogi/rival/tree/main/tests/test_generators/"
    click Conftest "https://github.com/sarthakrastogi/rival/blob/main/tests/conftest.py"

    %% Styles
    classDef core fill:#BBDEFB,stroke:#0D47A1,color:#0D47A1,stroke-width:1px
    classDef detector fill:#C8E6C9,stroke:#1B5E20,color:#1B5E20,stroke-width:1px
    classDef genEval fill:#FFE0B2,stroke:#E65100,color:#E65100,stroke-width:1px
    classDef util fill:#FFF9C4,stroke:#F57F17,color:#F57F17,stroke-width:1px
    classDef external fill:#ECEFF1,stroke:#455A64,color:#455A64,stroke-width:1px
    classDef datastore fill:#E1BEE7,stroke:#4A148C,color:#4A148C,stroke-width:1px
```
