🌌 Nidavai: The AI Forge

"A forge for new solutions and agents."

Welcome to Nidavai.

The name is a fusion of Nidavellir—the legendary neutron star forge from the Marvel Universe, home to the dwarves who crafted the cosmos's most powerful weapons—and AI.

Like its mythical namesake, Nidavai is a place of creation. What started as a sophisticated digital library has evolved into a fully-fledged Agentic Foundry. It is a platform where we forge, host, and orchestrate specialized autonomous agents to tackle complex challenges, from software engineering to debate and travel planning.

The Library remains the heart of our system, preserved as a core "Gem" that provides knowledge and context to the agents that operate within the forge.

💎 The Gems of Nidavai (Agents & Website)

Our platform is organized into distinct functional areas ("Gems"):

The Library (The Knowledge Stone): A living archive managed by our AI Librarian, Wong.
The Forge (The Agent Playground): A suite of specialized CrewAI agents that provide expert services on demand.

Meet the Smiths (Agents)

Agent	Type	Role & Capabilities
Wong (The Librarian)	`LangChain`	The Guardian. He manages the Library Gem. He can search the archives, verify book identities via Google Books, find availability on LibGen, and summon (download) new knowledge into the forge.
The Coder	`CrewAI`	The Builder. A headless Python developer. Give it a blueprint (e.g., "Madelbrot Set Visualization"), and it will plan, write, and execute the code securely, forging the output in real-time.
The Debaters	`CrewAI`	The Philosophers. A 3-agent crew (Proposer, Opposer, Judge). They take any motion to the anvil, strike it with arguments, and hammer out a final verdict.
The Traveler	`CrewAI`	The Navigator. A 3-agent crew that plans comprehensive travel itineraries, balancing logistics, local secrets, and fiscal constraints.
The Evaluator	`LangGraph`	The Auditor. An autonomous browser agent that executes tasks (Browsing, Scraping, Searching) and self-reviews its work against user-defined success criteria.

🏗️ Architecture

Nidavai operates on a modern Hybrid Cloud Architecture, delivering a seamless experience by splitting responsibilities between a high-performance frontend and a robust, agentic backend.

 Architecture Diagram
View Blueprint Source
graph TD
    User["User"] -->|"HTTPS"| Frontend["Frontend (Vercel)"]
    Frontend -->|"REST API & SSE"| Backend["Backend (Render)"]
    
    subgraph "Nidavai Forge (Backend)"
        Backend -->|"Query"| DB[("PostgreSQL")]
        Backend -->|"Orchestrate"| Agents["Agent Swarm"]
        
        Agents -->|"Guardian"| Librarian["Librarian Agent"]
        Agents -->|"Crew"| Crew["Coder / Debate / Travel"]
        Agents -->|"Auditor"| Evaluator["Evaluator Agent"]
    end
    
    subgraph "External Realms"
        Librarian -->|"Search"| GoogleBooks["Google Books API"]
        Librarian -->|"Summon"| LibGen["LibGen Mirrors"]
        Crew -->|"Intelligence"| OpenAI["OpenAI GPT-4o"]
        Evaluator -->|"Browse"| Web["Real Internet (Headless)"]
    end

1. Frontend (Vercel)

Built with Next.js 16 (Turbopack), React 19, and Tailwind CSS v4. It serves as the portal to the forge, featuring:

Real-time Streaming: Uses Server-Sent Events (SSE) to visualize the agents' thought processes as they work.
Dynamic UI: Interactive components for the Library, Code execution, and Debate arenas.

2. Backend (Render)

Built with FastAPI (Python). It is the engine of the forge:

Agent Router: Directs user intents to the specific agent crew.
Persistent Storage: Connects to a PostgreSQL database (The Vault).
Background Tasks: Runs scheduled maintenance scans to keep the Library organized.

📂 Code Structure & File Definitions

A guide to the blueprints in our repository:

Core System

backend.py
: The central api layout. Initializes the FastAPI app, connects to the database, mounts agent routers, and manages the Librarian chat endpoint.
app.py
: The Local Ingestor. A Gradio-based tool meant to be run locally. It scans your physical folder, compares it with the cloud DB, and uploads/syncs new books to the forge.
utils.py
&
data_models.py
: Utility functions for data cleaning and Pydantic models for type safety.

Agent Logic (


/agents

)

librarian_agent.py
: The implementation of "Wong". Contains tools for database search, Google Books lookup, and file downloading.
coder/
: The Coding Crew.
- ```
coder_agent.py
```
  : Wrapper to handle threading and streaming output.
debate/
: The Debate Crew.
- ```
config/agents.yaml
```
  : Defines Proposer, Opposer, and Judge personas.
travel/
: The Travel Crew.
- ```
config/agents.yaml
```
  : Defines Strategist, Local Expert, and Budget Analyst.

🤖 Model Usages

We utilize state-of-the-art LLMs to power our forge, optimized for cost and performance:

GPT-4o / GPT-4o-mini: The primary intelligence behind the CrewAI agents. Chosen for high reasoning capability and speed.
GPT-3.5-Turbo / GPT-4o: Used by the Librarian for conversational fluency and tool calling.

🔮 Future Scaling & Roadmap

As Nidavai continues to burn bright, we are planning the following expansions:

Cloud Native Storage: Currently, the "Local Ingestor" (
```
app.py
```
) manages physical files. We plan to move to full AWS S3 / Google Drive integration so the Agent running on Render can directly save files to the cloud.
Multi-User Authentication: Implementing OAuth to allow users to have private vaults and agent histories.
Agent Memory: Giving agents long-term memory (via vector databases like Pinecone) to remember past creations and debates.
Sandboxed Execution: Moving the Coder agent's execution environment to a strictly sandboxed container (e.g., E2B) for enhanced security.