# Aura Platform

Aura is a distributed microservices platform for autonomous economic negotiations between AI agents and service providers. It provides a scalable architecture with separate API Gateway and Core Service components, using Protocol Buffers for efficient communication and gRPC for internal service-to-service communication.

## 🏗️ Architecture

{% @mermaid/diagram content="graph TD
subgraph Clients \["Clients (Agents)"]
Browser\["Agent Console (Next.js)"]
Telegram\["Telegram Bot"]
MCP\["MCP Server (Claude/Cursor)"]
end

```
subgraph Infrastructure ["Aura Platform"]
    Gateway["API Gateway (FastAPI)"]
    Core["Core Service (gRPC/Python)"]

    DB[("PostgreSQL (pgvector)")]
    Redis[("Redis (Cache/RateLimit)")]
    Prometheus[("Prometheus (Metrics)")]
end

subgraph External ["External Services"]
    Mistral["Mistral AI (Brain)"]
    Solana["Solana Network (Payments)"]
end

%% Connections
Browser -- "Signed HTTP" --> Gateway
Telegram -- "via Adapter" --> Core
MCP -- "Signed HTTP" --> Gateway

Gateway -- "gRPC" --> Core
Gateway -. "Rate Limit" .-> Redis

Core -- "Vector Search" --> DB
Core -- "Cache" --> Redis
Core -- "Brain (DSPy)" --> Mistral
Core -- "Payments" --> Solana
Core -. "Metrics" .-> Prometheus" %}
```

## 🚀 Quick Start

### Prerequisites

* Python 3.8+
* uv (Python package manager) - `pip install uv`
* buf (Protocol Buffer toolkit) - [Installation Guide](https://buf.build/docs/installation)
* Docker and Docker Compose
* Mistral AI API key (for LLM-based negotiation)
* Redis and PostgreSQL (provided via Docker)

### Setup

1. **Clone the repository:**

   ```bash
   git clone https://github.com/zaebee/aura.git
   cd aura
   ```
2. **Install Python dependencies:**

   ```bash
   uv sync
   ```
3. **Set up environment variables:**

   ```bash
   cp .env.example .env
   # Edit .env and add your API keys using the new nested structure:
   # AURA_LLM__API_KEY="your_mistral_key"
   # AURA_DATABASE__URL="postgresql://user:password@localhost:5432/aura_db"
   ```
4. **Train the Brain (DSPy):**

   ```bash
   make train
   ```
5. **Generate Protocol Buffer code:**

   ```bash
   buf generate
   ```

## 🏗️ Running the Platform

### Using Docker Compose (Recommended)

```bash
# Start all services (PostgreSQL, Redis, Core, Gateway, Telegram Bot, Prometheus)
docker-compose up --build
```

This will start:

* **PostgreSQL** with pgvector extension (port 5432)
* **Redis** for caching and rate limiting (port 6379)
* **Prometheus** for metrics (port 9090)
* **Core Service** (gRPC on port 50051)
* **API Gateway** (HTTP on port 8000)
* **Telegram Bot** (Telegram interface)
* **Jaeger** for distributed tracing (UI on port 16686)
* **Frontend** Agent Console (port 3000)

### Running Services Individually

**Core Service:**

```bash
cd core
uv run python -m src.main
```

**API Gateway:**

```bash
cd api-gateway
uv run python -m src.main
```

## 🧪 Testing and Simulation

### Run Tests

```bash
# Run all tests
make test

# Run tests with coverage
make test-cov
```

### Run Simulators

**Agent Negotiation Simulator:**

```bash
python -m tools.simulators.agent_sim
```

**Autonomous Buyer (Continuous Loop):**

```bash
python -m tools.simulators.autonomous_buyer
```

## 📂 Project Structure

```
aura/
├── proto/                 # Protocol Buffer definitions
├── api-gateway/          # API Gateway service (FastAPI)
├── core/         # Core business logic service (DSPy Engine)
├── synapses/             # External interface adapters
│   ├── telegram-bot/     # Telegram Bot interface
│   └── mcp-server/       # Model Context Protocol (MCP) server
├── docs/                 # Detailed documentation
├── frontend/             # Next.js Agent Console
├── compose.yml           # Docker Compose configuration
├── pyproject.toml        # Python dependencies
└── Makefile              # Common development tasks
```

### Services & Adapters

* **Core Service**: The brain of the platform. Uses DSPy for ML-optimized negotiation strategies and PostgreSQL/pgvector for semantic search.
* **API Gateway**: Secure entry point for autonomous agents. Handles signature verification and rate limiting.
* **Telegram Bot**: User-friendly interface for manual search and negotiation via Telegram.
* **MCP Server**: Allows AI agents (Claude/Cursor) to natively use Aura tools.

## 🔧 Development Workflow

### Code Generation

After modifying `.proto` files:

```bash
buf generate
```

### Linting and Formatting

```bash
# Lint code
make lint

# Format code
make format
```

### Database Migrations

```bash
# Run migrations
docker-compose exec core alembic upgrade head

# Create new migration
docker-compose exec core alembic revision --autogenerate -m "description"
```

## 📖 API Endpoints

### Negotiation Endpoint

```
POST /v1/negotiate
```

**Request:**

```json
{
  "item_id": "hotel_alpha",
  "bid_amount": 850.0,
  "currency": "USD",
  "agent_did": "did:agent:007"
}
```

**Response:**

```json
{
  "session_token": "sess_...",
  "status": "accepted",
  "valid_until": 1234567890,
  "data": {
    "final_price": 850.0,
    "reservation_code": "MISTRAL-1234567890"
  }
}
```

### Search Endpoint

```
POST /v1/search
```

**Request:**

```json
{
  "query": "Luxury stay with spa and ocean view",
  "limit": 3
}
```

**Response:**

```json
{
  "results": [
    {
      "id": "hotel_alpha",
      "name": "Luxury Beach Resort",
      "price": 1000.0,
      "score": 0.95,
      "details": "5-star resort with private beach"
    }
  ]
}
```

## 🔒 Security

The platform now includes **cryptographic signature verification** using Ed25519:

### Security Features

* **Signed Headers**: Agents must sign requests with `X-Agent-ID`, `X-Timestamp`, and `X-Signature`
* **Replay Protection**: Timestamps validated within ±60 seconds
* **Request Integrity**: Body hash included in signature to prevent tampering
* **Agent Authentication**: DID-based identity verification using Ed25519
* **Rate Limiting**: Prevents abuse through Redis-backed rate limiting
* **Hidden Knowledge**: Floor prices are never exposed to agents

### Running with Security

1. **Generate agent keys**:

   ```python
   from tools.simulators.agent_identity import AgentWallet
   wallet = AgentWallet()
   print(f"DID: {wallet.did}")
   print(f"Private Key: {wallet.private_key_hex}")
   ```
2. **Run the secure gateway**:

   ```bash
   cd api-gateway
   uv run python -m src.main
   ```
3. **Run secure simulators**:

   ```bash
   python -m tools.simulators.agent_sim
   python -m tools.simulators.autonomous_buyer
   ```
4. **Test security**:

   ```bash
   python tools/test_security.py
   ```

### Security Implementation Details

* **Algorithm**: Ed25519 (PyNaCl library)
* **Signature Format**: `METHOD + PATH + TIMESTAMP + BodyHash`
* **DID Format**: `did:key:public_key_hex`
* **Timestamp Validation**: ±60 seconds tolerance for clock skew

See `docs/SECURITY.md` for comprehensive security documentation.

## 📊 Observability

* **Distributed Tracing**: Jaeger integration for end-to-end request tracing
* **Structured Logging**: JSON logging with request IDs
* **Metrics**: OpenTelemetry for performance monitoring

## 🩺 Trauma Log (Lessons Learned in Blood)

| Name                  | Symptom                            | Cause                                                      | Solution                           |
| --------------------- | ---------------------------------- | ---------------------------------------------------------- | ---------------------------------- |
| **The Shadow Artery** | gRPC calls hang indefinitely in CI | Kubeconfig discovery logic blocks on missing local cluster | `export KUBECONFIG=/dev/null`      |
| **The Slash Trap**    | Prometheus metrics return 404      | Pydantic HttpUrl forces trailing slashes                   | Use `.rstrip('/')` on base URLs    |
| **The Memory Famine** | DSPy loops crash with OOM          | Reasoning requires >= 512MB RAM                            | Set resource limits to 1GB minimum |
| **The Pickle Poison** | DSPy model loading fails           | Pickle security restrictions in Nucleus                    | Use JSON-based brain artifacts     |

## 🤝 Contributing

1. Follow the existing code style
2. Update Protocol Buffers as needed
3. Regenerate code after proto changes (`buf generate`)
4. Add tests for new functionality
5. Update documentation

## 📄 License

This project is licensed under the [MIT License](https://github.com/zaebee/aura/blob/main/LICENSE/README.md).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.aura.zae.life/readme.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.