Philosophy

The Arshai framework is built on a fundamental philosophy: developers should have complete control over their AI applications. This section explains the core principles, architectural decisions, and design philosophy that guide the framework.

Philosophy & Principles

• Introduction
  • What is Arshai?
  • The Framework vs. The Implementations
  • Why Arshai Exists
  • Who is Arshai For?
  • Core Philosophy
  • What You’ll Build
  • Getting Started
• Three-Layer Architecture
  • Overview
  • Layer 1: LLM Clients
  • Layer 2: Agents
  • Layer 3: Agentic Systems
  • Key Benefits
  • Design Principles
• Developer Authority
  • The Philosophy
  • Traditional vs Arshai Approach
  • Core Principles
  • Real-World Benefits
  • Common Patterns
  • What This Means for You
• Design Decisions
  • Why We Removed the Settings Pattern
  • Why Direct Instantiation Over Factories
  • Why Agents Are Stateless
  • Why Interface-First Design
  • Why Environment Variables for Secrets
  • Why Three Layers Instead of More (or Fewer)
  • Why Python Protocols Over ABC
  • Why Async-First Design
  • Why Minimal Base Classes
  • Summary of Design Principles

Core Principles

You’re in Control

Every component is created explicitly by you. No hidden factories, no magic configuration, no framework taking over.

Building Blocks, Not Solutions

Arshai provides the foundation - interfaces and base classes. You build the solution that fits your needs.

Progressive Complexity

Start simple with Layer 1 (LLM clients), add logic with Layer 2 (agents), orchestrate with Layer 3 (systems).

Direct Instantiation

You create components when you need them, configure them how you want, and control their lifecycle.

Interface-Driven Design

Clean interfaces define contracts. Implement them your way, extend as needed, compose freely.

Why This Matters

Traditional AI frameworks often:

• Hide complexity behind abstractions

• Force specific patterns and workflows

• Create vendor lock-in through proprietary abstractions

• Make testing and debugging difficult

Arshai takes a different approach:

• Transparent: You see and control everything

• Flexible: Use what you need, ignore what you don’t

• Testable: Easy to mock and test components

• Portable: No vendor lock-in, just clean interfaces

Next Steps

Start with Introduction to understand what Arshai is and why it exists, then explore the Three-Layer Architecture that provides the framework’s structure.