Welcome to the Athomic

Athomic is an opinionated, production-ready engine for building resilient, observable, and scalable microservices in Python. It provides a robust foundation—the Athomic Layer—that handles cross-cutting concerns, allowing developers to focus purely on business logic.

Our philosophy is grounded in battle-tested software engineering principles like SOLID, Single Responsibility (SRP), and Dependency Injection (DI), ensuring that applications built on this engine are maintainable, scalable, and easy to test.

Getting Started

Follow these steps to get a local development environment up and running.

Prerequisites

Docker & Docker Compose
Python 3.11+
Poetry

1. Clone the Repository

git clone https://github.com/guandaline/athomic.git
cd athomic

2. Start Infrastructure Services

This command will start all necessary services defined in docker-compose.yml, such as MongoDB, Redis, and Vault.

docker-compose up -d

3. Install Dependencies

Install the project's Python dependencies using Poetry.

poetry install

4. Run the Application

Execute the application using uvicorn. The server will start on http://127.0.0.1:8000.

poetry run uvicorn nala.api.main:app --reload

You can now access the API documentation at http://127.0.0.1:8000/docs.

Explore the Documentation

Architecture Overview: Dive deep into the layered architecture and design principles.
Dependency Injection: Understand how services are managed.

Athomic Layer Modules

Core & Lifecycle

Services: The base service lifecycle.
Lifecycle Management: How services are started and stopped in order.
Plugins: The extensible plugin system.
Session Management: Generic leasing, TTL, and lifecycle management for reusable resources.

Configuration & Context

Configuration Management: The Dynaconf and Pydantic based configuration system.
Context Management: Handling request-scoped context for tracing and multi-tenancy.

Data & Persistence

Connection Management: The central manager for all data store connections.
Document Stores: Abstraction for document databases like MongoDB.
Key-Value Stores: Abstraction for KV stores like Redis, with a powerful wrapper system.
Vector Stores: Abstraction for Vector databases like Qdrant/Weaviate.
Graph Databases: Integration with Graph DBs like Neo4j.
Transactional Outbox: For guaranteeing at-least-once event delivery.
Database Migrations: Version-controlled schema management.
File Storage: Abstraction for object storage like GCS or local files.

Artificial Intelligence

AI Agents: Framework for building ReAct agents with tool execution.
Workflow Orchestration: Graph-based execution engine for complex, cyclic AI workflows (loops, conditional branching).
Cognitive Intent Engine: Service for user intent classification and query understanding before execution.
Agent Persistence: State management, checkpointing, and fault tolerance for agents.
AI Sandbox & Code Interpreter: Secure, isolated execution environment for untrusted code generated by LLMs.
RAG Pipeline: Stream-first architecture for Retrieval-Augmented Generation.
Semantic Cache: Optimization layer using vector similarity to cache LLM responses.
LLM Abstraction: Unified interface for providers (OpenAI, Vertex) with streaming support.
AI Governance: Guardrails for PII sanitization and policy enforcement.
Semantic Memory: Service for managing embeddings and vector storage.
Embeddings: Text-to-vector transformation services.
Document Ingestion: ETL pipelines for processing documents into knowledge.
QA & Evaluation: Testing harness for evaluating RAG/Agent quality (Faithfulness, Relevancy).

Security

Secrets Management: Securely resolve secrets at runtime from backends like Vault.
Authentication & Authorization: Policy-based security for endpoints using JWT or API Keys.
Cryptography: High-level abstraction for symmetric encryption.

Observability

Structured Logging: Loguru-based logging with automatic sensitive data masking.
Distributed Tracing: End-to-end tracing with OpenTelemetry.
Metrics: Out-of-the-box instrumentation with Prometheus.
Health & Readiness: Extensible readiness probes for Kubernetes.
Data Lineage: Tracking data movement via OpenLineage.

Cross-Cutting Concerns

Serializer: Pluggable serializers (JSON, Protobuf) for data conversion.
Payload Processing Pipeline: A "Pipes and Filters" system for composing transformations like encryption and compression.
Notifications: Resiliently send emails via SMTP or other providers.
Internal Event Bus: In-process Pub/Sub for decoupling internal components.
Resilient HTTP Client: A factory for creating pre-configured, resilient clients.
Smart Router: Dynamic, resilient, and domain-agnostic execution routing engine with predictive scoring and fallback chains.