harshil-sorathiya/ai-engineering-compendium

A comprehensive, battle-tested repository for engineers, architects, and product teams who want to master the art and science of building production-ready AI-powered applications. This is not a theoretical textbook but a practical, hands-on guide filled with real-world patterns, anti-patterns, optimization techniques, and integration blueprints for harnessing the full potential of OpenAI, Claude, and other large language models (LLMs).
The Big Idea: Stop Treating AI as a Black Box
Most AI projects fail not because the models are weak, but because the engineering around them is fragile. This playbook treats AI not as magic, but as a composable, testable, and observable subsystem of your software architecture. It is designed for teams who want to move from "prototype that works on my machine" to "system that survives production traffic."
Think of this repository as the missing manual for building software that thinks. It is the engineering equivalent of a seasoned navigator's map—drawn from real deployments, countless prompt iterations, and a healthy number of failures.
Why This Playbook Exists
The landscape of AI engineering is cluttered with tutorials that show you how to call an API endpoint and call it a day. This playbook goes deeper. It answers the tough questions that emerge when your chatbot needs to be reliable, your data pipeline needs to be secure, and your user interface needs to adapt to 14 languages at 2 AM.
It is a living document, updated through 2026, reflecting the latest stable practices for integrating OpenAI's GPT-4o, Claude 3.5 Sonnet, and open-source alternatives into a cohesive, maintainable system.
Mermaid Diagram: The AI Engineering Stack
**Figure 1:** The recommended architecture for a resilient AI system. Notice how the Orchestration Layer acts as the brain's prefrontal cortex—deciding which model to call, how to structure the context, and when to fall back gracefully.
Example Profile Configuration
Your journey begins with a single file: agent.profile.yaml. This is the DNA of your AI agent. Below is a production-ready configuration that powers a multilingual customer support chatbot with a 99.5% uptime target.
Example Console Invocation
Once your profile is ready, you can invoke the agent through a powerful CLI that feels like a UNIX command but talks to the cloud. This is the ai-console tool.
The console output is designed to be machine-readable by default (JSON) but can be configured for human-friendly tables or markdown. This makes it ideal for integration into CI/CD pipelines, Slack bots, or cron jobs.
Emoji OS Compatibility Table
| Operating System | Support Status | Notes |
|:---|:---:|:---|
| Ubuntu 22.04+ | ✅ Full Support | Primary development target. All features tested. |
| macOS 14+ (Sonoma) | ✅ Full Support | Native Metal acceleration for embedding models. |
| Windows 11 + WSL2 | ✅ Full Support | Requires WSL2 for optimal file system performance. |
| Windows 10 (Native) | ⚠️ Limited | Console UI works; vector DB may have path issues. |
| Raspberry Pi OS (ARM64) | 🧪 Experimental | Works for lightweight agents. No GPU acceleration. |
| FreeBSD 13+ | ❌ Not Supported | Missing kernel-level threading primitives. |
Feature List: The Complete Arsenal
This playbook is modular. You do not need to use everything at once, but the power grows exponentially the more pieces you integrate.
Core Engine Features
- **Multi-Provider AI Routing**: Dynamically switch between OpenAI, Claude, and local models based on cost, latency, or task complexity.
- **Semantic Context Assembly**: Automatically retrieves relevant conversation history and knowledge base articles to fit within the model's context window without losing critical information.
- **Adaptive Prompt Engineering**: Templates that auto-adjust based on detected language, user intent, and desired output format.