Developer Guide - brahm-ai-official/brahm-ai GitHub Wiki

🏠 Home · ✨ Features · 🗺️ Roadmap · 🧠 Philosophy · 👨‍💻 Developer Guide · 🌐 Live Platform

👨‍💻 BRAHM-AI Developer & Architecture Guide

This page provides a public high-level guide to the BRAHM-AI architecture.

It does not expose private production credentials, protected prompts, internal datasets, infrastructure secrets, or complete commercial source code.

🏗️ Platform Architecture

BRAHM-AI uses a modular and API-oriented architecture.

User Input
  ├── Text
  ├── Voice
  ├── Camera / Image
  ├── Document
  └── Supported Action Request
        ↓
Input Normalization
  ├── Language Detection
  ├── Speech-to-Text
  ├── OCR
  ├── Vision Observation
  └── Session Context
        ↓
Intent and Capability Router
  ├── General Conversation
  ├── Scripture Retrieval
  ├── Panchang Computation
  ├── Vision Intelligence
  ├── Live Search
  ├── Market
  ├── Agriculture
  ├── Language
  └── Automation
        ↓
BRAHM Core Reasoning
  ├── Exact Response
  ├── RAG Response
  ├── Live-Data Explanation
  ├── General Reasoning
  └── Safe Fallback
        ↓
Response Delivery
  ├── Text
  ├── Multilingual TTS
  ├── Avatar
  ├── Structured Data
  └── Action Result

🧠 Central Conversation Flow

BRAHM True remains the primary conversational source.

Responsibilities include:

Intent analysis
Context management
Helper selection
Structured retrieval
Live-data routing
Model routing
Safety formatting
Final response generation

BRAHM Voice uses this same central flow.

🎙️ Voice Architecture

Microphone
  ↓
Speech-to-Text
  ↓
Central BRAHM Conversation Flow
  ↓
Response Text
  ↓
Text-to-Speech
  ↓
Lipsync / Avatar / Audio Output

Voice-specific responsibilities:

Microphone permission
Audio capture
Silence and end-of-speech detection
Duplicate-submit protection
Language-aware STT
TTS voice selection
Playback control
Avatar states
Text fallback

Voice should not maintain an independent answer engine when BRAHM True is the source of truth.

📖 Scripture Retrieval Architecture

Preferred flow:

Query
  ↓
Scripture and Section Detection
  ↓
Exact Lookup
  ↓
Alias and Metadata Matching
  ↓
RAG Retrieval when needed
  ↓
Source Validation
  ↓
Explanation

Structured scripture records may contain:

Scripture identifier
Kanda or section
Chapter or Sarga
Verse number
Original Sanskrit
Translation
Explanation
Context
Keywords
Source edition
Verification status

Generated content should not be inserted into canonical datasets without verification.

🪔 Panchang and Jyotish Architecture

Required flow:

Date + Time + Location + Timezone
                 ↓
       Computation or Provider
                 ↓
          Structured Result
                 ↓
        BRAHM Explanation

The reasoning model should not generate exact astronomical values without computation.

📷 Vision Architecture

Camera / Uploaded Image
          ↓
Image and Frame Validation
          ↓
Detection / OCR / Scene Analysis
          ↓
Confidence and Safety Checks
          ↓
Structured Visual Observation
          ↓
BRAHM Reasoning

Vision services should support:

Confidence thresholds
User verification
File and image limits
Privacy-aware processing
Clear uncertainty
Medical safeguards
Graceful fallback

🦅 Garudaa LLMG 108 V2 Architecture

Garudaa is being developed as a local model provider inside the BRAHM ecosystem.

BRAHM Request
  ↓
Identity and Quota Validation
  ↓
Language and Intent Detection
  ↓
Exact Helper Lookup
  ↓
RAG Retrieval
  ↓
Garudaa Local Model
  ↓
Safety and Formatting
  ↓
BRAHM True
  ↓
Text or Voice Delivery

Development goals:

Compact 3B-class model evaluation
Local Ollama-compatible serving
CPU and GPU profiles
Hindi-first instruction quality
Sanskrit and Devanagari understanding
RAG grounding
Quantization
Timeout protection
Model pre-warming
Usage metering
Structured logging

🔌 API Architecture

Planned public and partner APIs use versioned routes.

Examples:

/api/v1/chat
/api/v1/panchang/daily
/api/v1/scriptures/search
/api/v1/language/process
/api/v1/vision/analyze
/api/v1/mandi/prices
/api/v1/market/analyze
/api/v1/voice/session
/api/v1/automation/plan

Expected platform features:

API keys
Bearer authentication
Scope-based permissions
Per-key quotas
Rate limiting
Request IDs
Usage metering
Structured errors
Source metadata
Freshness metadata
Audit logging
Streaming where supported
Test and production environments

📦 Suggested API Response Envelope

{
  "success": true,
  "request_id": "req_xxxxx",
  "data": {},
  "usage": {
    "units": 1,
    "remaining": 999
  },
  "meta": {
    "language": "hi",
    "source_mode": "structured",
    "generated_at": "ISO-8601 timestamp"
  }
}

Errors should use a predictable structured format and appropriate HTTP status code.

🧱 Architecture Principles

Specialized Routing

Use the most appropriate helper, database, provider, computation engine, vision model, retrieval system, or reasoning model.

Exact Data Before Generation

Do not ask the language model to invent data already available from a structured source.

API-Driven Frontend

Keep heavy intelligence, authentication, metering, and routing logic in backend services rather than public UI scripts.

Modular Deployment

Voice, True, vision, language, Panchang, scripture, market, agriculture, automation, wallet, and agents should remain independently upgradeable.

Fallback-Oriented Reliability

A provider failure should not crash the entire user experience.

🔐 Security Requirements

Never expose:

API keys
Environment files
Database passwords
Private keys
OAuth secrets
Payment credentials
Internal prompts
User conversations
Camera or voice data
Production logs containing sensitive information

Security issues should be reported according to:

https://github.com/brahm-ai-official/brahm-ai/blob/main/SECURITY.md

🧪 Testing Areas

Depending on the module, testing should include:

Syntax and build
Route and API contract
Authentication
Quotas and rate limits
Database compatibility
Helper-level behaviour
Exact retrieval
RAG fallback
Multilingual input
STT and TTS
Camera and OCR
Mobile browsers
Provider timeouts
Safe fallback
Cross-module regression

A change to one helper should not silently break unrelated modules.

🚀 Production Safety

Production changes should include:

Backup
Syntax or build verification
Deployment steps
Service restart
Health check
Endpoint verification
Relevant log checks
Rollback method

📚 Public Repository Documents

🤝 Development and Licensing

BRAHM-AI is proprietary.

Public documentation does not grant rights to copy, deploy, redistribute, train from, reverse engineer, or commercially reuse protected materials.

For approved collaboration:

Email: [email protected] , [email protected]
Website: https://brahm-ai.in

Build modularly. Retrieve exactly. Explain honestly.

⬅️ Back: Philosophy · 🏠 Home