# Installation Guide

This guide will help you install AtomIngest and its dependencies.

## Prerequisites

Before installing AtomIngest, ensure you have:

- **Python 3.12 or higher**
- **pip** or **uv** package manager
- A supported database:
  - SQLite (included with Python)
  - PostgreSQL 12+ (optional)

## Installation Methods

### Option 1: Install from PyPI (Recommended)

```bash
pip install atomingest
```

This will automatically install:
- `atomsql` - The underlying ORM
- Required dependencies (PyYAML, etc.)

### Option 2: Install from Source

For development or the latest features:

```bash
# Clone the repository
git clone https://github.com/prashant-fintech/atomingest.git
cd atomingest

# Install in development mode
pip install -e .

# Or using uv (faster)
uv pip install -e .
```

### Option 3: Install with Optional Dependencies

For additional features:

```bash
# PostgreSQL support
pip install atomingest[postgres]

# All optional dependencies
pip install atomingest[all]
```

## Verify Installation

Check that AtomIngest is installed correctly:

```bash
# Check version
atomingest --version

# View help
atomingest --help
```

Expected output:
```
atomingest, version 0.1.0
Usage: atomingest [OPTIONS] COMMAND [ARGS]...
```

### Test Python Import

```python
from atomingest.core import Ingester
from atomsql import Database

print("✅ AtomIngest installed successfully!")
```

## Database Setup

### SQLite (Default)

No additional setup required! SQLite comes with Python.

```python
from atomsql import Database

# Creates a file-based database
db = Database("sqlite:///mydata.db")

# Or use in-memory for testing
db = Database("sqlite:///:memory:")
```

### PostgreSQL

1. **Install PostgreSQL** (if not already installed):
   - Download from [postgresql.org](https://www.postgresql.org/download/)
   - Or use Docker:
     ```bash
     docker run -d \
       --name postgres \
       -e POSTGRES_PASSWORD=mysecret \
       -e POSTGRES_DB=fintech \
       -p 5432:5432 \
       postgres:16
     ```

2. **Install Python driver**:
   ```bash
   pip install psycopg2-binary
   ```

3. **Connect from AtomIngest**:
   ```python
   from atomsql import Database

   db = Database("postgresql://user:password@localhost:5432/fintech")
   ```

## Environment Setup

### Create a Virtual Environment

Recommended for project isolation:

```bash
# Create virtual environment
python -m venv venv

# Activate (Windows)
venv\Scripts\activate

# Activate (Linux/Mac)
source venv/bin/activate

# Install AtomIngest
pip install atomingest
```

### Using uv (Modern Alternative)

`uv` is a faster package manager:

```bash
# Install uv
pip install uv

# Create project
uv venv
source .venv/bin/activate  # or .venv\Scripts\activate on Windows

# Install AtomIngest
uv pip install atomingest
```

## Project Structure

Recommended directory layout for AtomIngest projects:

```
my-ingestion-project/
├── pipelines/          # YAML pipeline configurations
│   ├── trades.yaml
│   ├── customers.yaml
│   └── transactions.yaml
├── data/              # Input data files
│   ├── raw/
│   └── processed/
├── hooks/             # Custom Python hooks
│   └── custom_logic.py
├── logs/              # Application logs
├── config.py          # Database and app config
└── main.py           # Entry point
```

## Configuration File

Create a `config.py` for database settings:

```python
import os
from atomsql import Database

# Database configuration
DATABASE_URI = os.getenv(
    "DATABASE_URI",
    "sqlite:///data/ingestion.db"
)

# Create database instance
db = Database(DATABASE_URI)

# Logging configuration
LOG_LEVEL = os.getenv("LOG_LEVEL", "INFO")
LOG_FILE = "logs/atomingest.log"
```

## Troubleshooting

### Common Issues

**Problem: `ModuleNotFoundError: No module named 'atomingest'`**

Solution:
```bash
pip install atomingest
# Or if using venv, make sure it's activated
```

**Problem: Database connection errors with PostgreSQL**

Solution:
```bash
# Install PostgreSQL driver
pip install psycopg2-binary

# Test connection
python -c "import psycopg2; print('OK')"
```

**Problem: Permission errors on Windows**

Solution:
```bash
# Run as administrator or use --user flag
pip install --user atomingest
```

### Version Compatibility

| AtomIngest | Python | AtomSQL | PostgreSQL |
|-----------|--------|---------|------------|
| 0.1.x     | 3.12+  | 0.1.x   | 12+        |

## Next Steps

Now that AtomIngest is installed:

1. **[Quick Start Guide](quickstart.md)** - Build your first pipeline
2. **[Core Concepts](concepts.md)** - Understand the architecture
3. **[Pipeline Configuration](pipeline_configuration.md)** - Learn YAML syntax

## Getting Help

- **Documentation**: [Full docs](README.md)
- **Examples**: Check `examples/` directory
- **Issues**: [GitHub Issues](https://github.com/prashant-fintech/atomingest/issues)
