Systems Overview

Ash is a Python-based personal assistant agent with modular architecture.

System Components

Agent Core

Orchestrates conversations, manages context, and coordinates tool execution.

LLM Providers

Abstraction layer for Anthropic Claude and OpenAI models.

Tool System

Extensible tools including sandboxed bash and web search.

Memory

SQLite-based storage with semantic search via embeddings.

Sandbox

Docker containers for secure command execution.

Providers

Communication channels (Telegram, CLI).

Data Flow

User Message
     │
     ▼
┌─────────────┐
│  Provider   │  (Telegram, CLI)
└─────┬───────┘
      │
      ▼
┌─────────────┐
│   Agent     │  Orchestrator
└─────┬───────┘
      │
      ├──────────────┐
      │              │
      ▼              ▼
┌─────────────┐ ┌─────────────┐
│    LLM      │ │   Memory    │
│  Provider   │ │   Store     │
└─────────────┘ └─────────────┘
      │
      ▼
┌─────────────┐
│   Tools     │ ──► Sandbox
└─────────────┘

Tech Stack

Component	Technology
Language	Python 3.12+
CLI	Typer
HTTP Server	FastAPI + Uvicorn
Telegram	aiogram 3.x
Database	SQLite + sqlite-vec
ORM	SQLAlchemy 2.0 (async)
LLM SDKs	anthropic, openai
Container	docker-py
Validation	Pydantic

Directory Structure

src/ash/
├── cli/           # Typer CLI
├── config/        # Configuration loading
├── core/          # Agent orchestrator
├── llm/           # LLM abstraction
├── providers/     # Communication providers
├── tools/         # Tool system
├── sandbox/       # Docker sandboxing
├── db/            # Database layer
├── memory/        # Memory + retrieval
├── skills/        # Skill system
├── server/        # FastAPI server
└── service/       # Background service

Key Design Principles

1. Async everywhere - All I/O is async using asyncio
2. Type hints required - Full type coverage with Pydantic validation
3. ABC for interfaces - Abstract base classes define contracts
4. Registry pattern - Dynamic discovery for tools, skills, providers
5. Security first - All command execution is sandboxed

Systems Documentation

Section	Description
LLM	LLM providers and model configuration
Tools	Tool system and execution
Skills	Configurable skill system
Agents	Built-in subagents
Memory	Storage and semantic search
Sandbox	Docker container isolation
Providers	Communication channels