# Project export: Neural Courier: A Hybrid Architecture for LLM Agents

This document was generated by HackStack to give an AI agent context about a hackathon project. Sections are labeled with their provenance; content marked as truncated was cut to keep this document small.

## Project metadata

- Hackathon: UC Berkeley AI Hackathon 2025
- Tagline: Neural Courier: A sim where a Groq LLM is the real-time brain for an autonomous drone. It makes strategic choices in <400ms, proving a new hybrid architecture for real-world AI agents.
- Devpost: https://devpost.com/software/neural-courier-a-hybrid-architecture-for-llm-agents
- GitHub: https://github.com/araikar08/Neural-Courier-A-Hybrid-Architecture-for-LLM-Agents
- Video: https://www.youtube.com/embed/G0fgDeE5XXY?enablejsapi=1&hl=en_US&rel=0&start=&version=3&wmode=transparent
- Result: winner (Nitrode: Nitrode Turbo Mode Award)
- Team: 1 GitHub contributor(s) — Aryan Raikar (5 commits)

## Devpost submission (written by the team)

### Inspiration

I've always been fascinated by autonomous systems, from warehouse robots to planetary rovers. Their biggest challenge isn't just moving; it's making smart, strategic decisions in real-time in complex environments. I wanted to see if modern, high-speed LLMs like the ones served by Groq could serve as the 'strategic brain' for such an agent, moving beyond simple commands to genuine tactical reasoning.

### What it does

Neural Courier is a real-time strategy simulation where you don't directly control the agent; you command it. The user gives a final objective to an autonomous drone. The drone, powered by a Groq LLM brain, analyzes the hostile environment and chooses the best tactical waypoint to approach the goal. Its strategic thoughts, and the incredible sub-400ms latency of its decisions, are displayed on a live command HUD, demonstrating a new way to interact with and observe AI decision-making.

### How we built it

Neural Courier is a full-stack application built solo in 48 hours. The 3D world and agent physics were built using Nitrode (a custom Godot engine), with game logic written in GDScript. This client communicates in real-time with a Node.js backend via a WebSocket server. When the agent needs a decision, the server packages the game state into a JSON object and sends it to the Groq API, which runs the Llama 3 8b model. The AI's JSON response, containing its strategic choice, is sent back to the client, which uses Nitrode's built-in Navigation Engine to reliably execute the high-level plan. This creates a complete, closed-loop, hybrid AI system.

### Challenges we ran into

My initial approach was to use the LLM for direct, low-level navigation commands ("move left," "move forward"). I quickly hit a wall. I discovered that while the Groq API was incredibly fast, LLMs are not inherently reliable for the kind of stateful, precise spatial reasoning required for moment-to-moment navigation. This led to the agent getting stuck in infinite loops. This failure was the project's biggest breakthrough. It forced me to pivot from a naive architecture to a more sophisticated one. The insight was: the LLM shouldn't be the puppet; it should be the puppet master. Refactoring the system to use the AI for high-level strategic choice instead of low-level control was the main challenge, but it resulted in a far more robust and intelligent agent.

### Accomplishments we're proud of

Building a Full End-to-End System Solo in 48 Hours: From the 3D game client to the backend server to the AI integration, this entire complex project was designed, built, and debugged by a single person. Achieving True Real-Time AI: The sub-400ms latency from the Groq API allowed me to create a truly responsive agent, proving the viability of LLMs for time-sensitive strategic tasks. Designing a Novel Hybrid Architecture: The final architecture, which uses the LLM for high-level strategy and the game engine for low-level execution, is a robust and scalable pattern for future AI agents.

### What we learned

The future of effective AI agents isn't just about bigger models; it's about smarter system design. I learned that the most powerful solutions combine the strengths of different technologies—using LLMs for what they're best at (high-level reasoning and choice-making) and leveraging deterministic engines for what they're best at (flawless execution). This hybrid approach is the key to creating reliable, real-world autonomous systems.

### What's next

The hybrid architecture of Neural Courier is incredibly scalable. The next step is to expand it into a multi-agent simulation platform. This would involve introducing multiple AI drones that need to communicate and collaborate to solve more complex objectives, like coordinating a delivery or mapping a larger area. This would allow for benchmarking different LLMs not just on speed, but on their ability to perform cooperative strategic reasoning, a key step towards real-world autonomous fleets.

## README (from the GitHub repository)

# Neural Courier: A Hybrid Architecture for Autonomous LLM Agents

**A solo project by Aryan Raikar for the Berkeley AI Hackathon 2025.**

---

### ► Watch the Demo Video

[![Watch the Demo](https://i.imgur.com/Jy8gJjG.png)](https://www.youtube.com/watch?v=G0fgDeE5XXY)

*(Click the image to watch the 2-minute demonstration)*

---

### The Concept

Neural Courier is a stealth strategy game that acts as a demonstration platform for a powerful, real-world hybrid AI architecture. It tackles a core challenge in modern robotics: how can we use the creative reasoning of Large Language Models (LLMs) for real-time navigation without succumbing to their unreliability for precise, low-level tasks?

Our system proves that by elevating the LLM to the role of a **Strategic Planner** and combining it with a deterministic game engine for execution, we can build smarter, more robust autonomous agents.

### Tech Stack & Architecture

This project integrates a full stack of modern technologies to achieve real-time AI decision-making:

* **Game Client (Nitrode/Godot):** Renders the 3D world, manages physics, and uses the built-in Navigation engine to execute movement commands.
* **Backend Server (Node.js):** Acts as the communication bridge, using WebSockets for low-latency, bidirectional communication with the game client.
* **AI Brain (Groq):** The Groq platform serves the Llama 3 8b model at incredible speed, allowing us to get strategic decisions in under 400ms, which is essential for a real-time loop.
* **Voice Output (say.js/Vapi):** The AI's "thoughts" are converted to speech, providing a multimodal user experience.

![Architecture Diagram](https://i.imgur.com/eH0C7Qp.png)

### How to Run It

1.  **Clone the repository.**
2.  **Create a `.env` file** in the root directory with your Groq API key:
    `GROQ_API_KEY="gsk_..."`
3.  **Install server dependencies:**
    `npm install`
4.  **Run the brain server:**
    `node brain_server.js`
5.  **Run the game:**
    Open the project in the Nitrode editor and press the Play button.

---

## License

This project is licensed under the [MIT License](LICENSE).


## Detected evidence (automated analysis)

Indexed codebase: 2 recognized source files, 5 KB.
- JavaScript (language) — detected in the code
- Node.js (technology) — claimed on Devpost, not found in the code

## Codebase structure (from repository index)

### Files (5 of 5)

```
.gitignore
brain_server.js
LICENSE
package.json
README.md
```

### Dependencies

- package.json: dotenv@^16.5.0, groq-sdk@^0.25.0, say@^0.16.0, ws@^8.18.2

### Recent commits (newest first)

- Update README.md
- FINAL3
- FINAL2
- FINAL
- docs: Create final README and add license for submission pt 1
- Working product pre-vapi
- feat: SUCCESS! Established WebSocket connection between Nitrode and Brain Server
- Update README.md
- Update README.md
- Initial commit

## Key source files (fetched from GitHub, selected and truncated for size)

### package.json

```
{
  "name": "calhacks-ai-arena",
  "version": "1.0.0",
  "description": "An interactive AI battle arena where you don't play the character — you **coach** the AI.",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "repository": {
    "type": "git",
    "url": "git+https://github.com/araikar08/calhacks-ai-arena.git"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "bugs": {
    "url": "https://github.com/araikar08/calhacks-ai-arena/issues"
  },
  "homepage": "https://github.com/araikar08/calhacks-ai-arena#readme",
  "dependencies": {
    "dotenv": "^16.5.0",
    "groq-sdk": "^0.25.0",
    "say": "^0.16.0",
    "ws": "^8.18.2"
  }
}

```

### brain_server.js

```javascript
require('dotenv').config();
const Groq = require('groq-sdk');
const { WebSocketServer } = require('ws');

const groq = new Groq();
const wss = new WebSocketServer({ port: 8080 });

const say = require('say');

console.log("Strategic Planner Brain Server v2 is listening on port 8080...");

wss.on('connection', function connection(ws) {
    console.log("A Nitrode client has connected!");
    ws.on('error', console.error);
    ws.on('message', async function message(data) {
        const gameState = JSON.parse(data.toString());
        
        const startTime = performance.now();
        const decision = await getWaypointFromGroq(gameState);
        const endTime = performance.now();
        const latency = (endTime - startTime).toFixed(2);

        // Combine the AI's decision with the latency metric
        const response_to_client = {
            ...decision, // This will include "choice" and "thought"
            latency: latency
        };

        console.log("Sending to client:", JSON.stringify(response_to_client));
        ws.send(JSON.stringify(response_to_client));

        speakText(decision.thought); 
    });
});

async function getWaypointFromGroq(gameState) {
    const systemPrompt = `You are a master military strategist. Your job is to select the single best tactical waypoint for a ground drone to approach its target.
You will be given the drone's position, the final target's position, and a numbered list of available waypoints.
You must choose the waypoint that offers the best path to the final target while avoiding obstacles.
You MUST respond ONLY with a clean JSON object with two keys: "choice" (the index number of the waypoint) and "thought" (a brief explanation of your choice).

Example Response:
{"choice": 1, "thought": "Waypoint 1 is the clearest path to flank the main obstacle."}
`;

    const userPrompt = `Game State: ${JSON.stringify(gameState)}. Which waypoint is the best choice?`;

    try {
        const chatCompletion = await groq.chat.completions.create({
            messages: [
                { role: 'system', content: systemPrompt },
                { role: 'user', content: userPrompt }
            ],
            model: 'llama3-8b-8192',
            response_format: { type: "json_object" },
        });
        const responseJson = JSON.parse(chatCompletion.choices[0].message.content);
        return responseJson;
    } catch (e) {
        return { "choice": 0, "thought": "Error in AI. Defaulting to first waypoint." };
    }
}

// This is the final, bulletproof version of the text-to-speech function.
function speakText(text) {
    // 1. More robust check to make sure the text is a real, non-empty string.
    if (typeof text !== 'string' || text.trim() === '') {
      console.log("Speak command skipped: text is empty.");
      return;
    }
  
    console.log(`Attempting to speak: "${text}"`);
  
    // 2. Stop any speech that is currently playing. This prevents conflicts.
    say.stop();
  
    // 3. Speak the new text, and use the callback to log success or any errors.
    // The '1.0' is the speed. 1.0 is normal.
    say.speak(text, 'Alex', 1.0, (err) => {
      if (err) {
        return console.error('Error occurred while speaking:', err);
      }
      console.log(`Successfully queued text for speaking: "${text}"`);
    });
  }
```