Metadata-Version: 2.4
Name: garuda-setup
Version: 1.0.2
Summary: Interactive setup wizard for Garuda System — entity-aware web intelligence platform (Closed Alpha)
Author-email: Garuda Intelligence <h.lorenzen@nxs.solutions>
License-Expression: MIT
Project-URL: Homepage, https://garuda.nxs.solutions
Project-URL: Repository, https://git.nxs.solutions/garuda/Garuda
Project-URL: Issue Tracker, https://git.nxs.solutions/garuda/Garuda/issues
Project-URL: Docker Registry, https://docker.nxs.solutions
Project-URL: Package Registry, https://pypi.nxs.solutions/api/packages/garuda/pypi/simple
Keywords: garuda,intelligence,OSINT,docker,setup,wizard,crawler,LLM,RAG
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: System :: Installation/Setup
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# Garuda Setup

> ⚠️ **Closed Alpha** — Garuda Intelligence is currently in closed alpha.
> Access requires registration at **[garuda.nxs.solutions](https://garuda.nxs.solutions)**
> and a Gitea account on **[git.nxs.solutions](https://git.nxs.solutions)**.
> Docker image pulls require authentication against `docker.nxs.solutions`.

Interactive cross-platform setup wizard for **[Garuda System](https://garuda.nxs.solutions)** —
the all-in-one intelligence platform by Garuda Intelligence.

Creates a self-contained install directory with `docker-compose.yml`,
`.env`, data directories, and platform-native launcher scripts.
No source checkout needed — just install, run the wizard, and go.

---

## About Garuda

**Garuda** is an advanced, entity-focused intelligence gathering and analysis platform
that combines **web crawling**, **LLM-powered extraction**, **semantic search**, and
**adaptive learning** to build comprehensive knowledge graphs. Named after the mythical
eagle with omniscient vision, Garuda provides deep insights into entities — companies,
people, organizations, products — through intelligent, gap-aware data collection.

### Key Capabilities

| | Feature | Description |
|---|---------|-------------|
| 🧠 | **Intelligent Crawling** | Analyzes what it already knows and automatically fills knowledge gaps through targeted searches |
| 🔍 | **RAG-First Hybrid Search** | SQL keyword + semantic vector search with automatic retry using paraphrased queries (4-phase search) |
| 🕸️ | **Knowledge Graph** | Tracks entities, relationships, and temporal changes with full provenance |
| 🎬 | **Multi-Modal Processing** | Extracts intelligence from text, images (OCR), video (transcription), and audio |
| 📁 | **Local Data Ingestion** | Upload files or watch directories — PDF, CSV, JSON, media — processed through the same extraction pipeline |
| 🗄️ | **Multi-Database** | Create isolated databases per domain, instant switching, merging, and cross-database global search |
| 📊 | **Adaptive Learning** | Learns from crawl results to improve future discovery strategies |
| 🔧 | **Production-Ready UI** | Web UI with 16 specialized panels, REST API, and Chrome extension |

### Built-in Components

The Garuda System container ships everything in a single image:

- **Web UI** — 16-panel Flask interface (Agent, Chat, Crawl, Entities Graph, Intel, Search, Media, and more)
- **IDE & REPL** — Browser-based development environment with [GLang](https://git.nxs.solutions/garuda/Garuda/src/branch/master/docs) (Garuda-Lang) scripting
- **Ollama** — Local LLM inference (llama3.2, granite, mistral, and others)
- **Qdrant** — Vector database for semantic/embedding search
- **PostgreSQL** — Structured data storage
- **Chrome Extension** — Record pages and elements directly from your browser
- **CLI Tools** — `garuda`, `garuda-search`, `garuda-agent`, `garuda-db`, `garuda-explorer`, and more

### Use Cases

- 🎯 **OSINT** — Gather structured intelligence on companies, individuals, infrastructure
- 🏢 **Corporate Research** — Entity profiles with automated gap analysis and competitive intelligence
- 🚨 **Threat Intelligence** — Track actors, infrastructure, and tactics from public sources
- 📚 **Academic Research** — Build domain-specific knowledge graphs from scholarly and news sources
- 📡 **Brand Monitoring** — Monitor mentions, sentiment, and relationships across the web

### Tech Stack

Python 3.10+ · Flask · SQLAlchemy · Qdrant · Ollama · Selenium · Tesseract OCR ·
sentence-transformers · Docker · Typer/Rich CLI

> For full documentation, architecture diagrams, and API reference, see the
> [main repository on Gitea](https://git.nxs.solutions/garuda/Garuda).

---

## Installation

### From PyPI (recommended)

```bash
pip install garuda-setup
```

### From Garuda Package Registry

```bash
pip install garuda-setup \
  --index-url https://pypi.nxs.solutions/api/packages/garuda/pypi/simple
```

### From Source

```bash
git clone https://git.nxs.solutions/garuda/Garuda.git
cd Garuda/setup
pip install .
```

### Run the Wizard

```bash
garuda-setup
```

Or without installing:

```bash
python -m garuda_setup
```

## Platform Support

| Platform | Docker Runtime | GPU Passthrough | Launcher |
|----------|---------------|-----------------|----------|
| **Linux** | Docker Engine | ✅ NVIDIA (via nvidia-container-toolkit) | `garuda.sh` |
| **macOS** | Docker Desktop / Colima | ❌ (CPU-only; use Garuda Cloud for GPU) | `Garuda.command` |
| **Windows** | Docker Desktop (WSL 2) | ✅ NVIDIA (via WSL 2) | `garuda.bat` / `garuda.ps1` |

### macOS Prerequisites

```bash
# Docker Desktop (recommended)
brew install --cask docker

# Or Colima (lightweight alternative)
brew install colima && colima start
```

> **Apple Silicon (M1–M4)**: Fully supported. The container image is multi-arch.
> GPU passthrough is not available in Docker on macOS —
> connect a remote GPU via [Garuda Cloud](https://garuda.nxs.solutions) instead.

## What It Does

The wizard walks you through a guided setup and generates everything needed
to run Garuda System on your machine:

1. **Detects your environment** — OS, Docker runtime, GPU availability
2. **Asks for configuration** — ports, services, credentials, mount paths
3. **Creates the install directory**:

```
~/garuda/
├── docker-compose.yml    # pulls from docker.nxs.solutions
├── .env                  # all configuration
├── garuda.sh             # launcher (Linux)
├── Garuda.command        # launcher (macOS — double-click in Finder)
├── garuda.ps1            # launcher (Windows PowerShell)
├── garuda.bat            # launcher (Windows CMD)
├── README.md             # quick reference
├── data/
│   ├── garuda/           # databases, indexes, projects
│   ├── qdrant/           # vector search storage
│   ├── postgres/         # PostgreSQL data
│   └── ollama/           # downloaded LLM models
├── home/                 # persistent container home
└── watch/                # drop files here for auto-ingestion
```

4. **Optionally pulls the image** from `docker.nxs.solutions/garuda/garuda-system:latest`
   and starts the container immediately

## Configuration Options

| Option | Description | Default |
|--------|-------------|---------|
| Install directory | Where all data and config live | `~/garuda` |
| API key | Garuda UI access key (auto-generate, custom, or skip) | auto |
| Port | Web UI port | `7331` |
| IDE | Enable the built-in code/intelligence IDE | yes |
| Ollama | Built-in LLM inference engine | yes |
| GPU passthrough | NVIDIA GPU access (Linux/WSL only) | auto-detect |
| Shell access | SSH into the container | no |
| VNC desktop | Remote desktop via browser | no |
| External PostgreSQL | Connect to an existing database | — |
| External Qdrant | Connect to an existing vector DB | — |
| External Ollama | Use a remote Ollama instance | — |
| AI models | LLM and embedding model selection | llama3.2 / nomic-embed-text |
| Cloud | Connect to Garuda Cloud (GPU provisioning, sync) | — |
| Credential mounts | GitHub Copilot config, GH CLI tokens, SSH keys | auto-detect |
| Host mounts | Additional directories to observe/index | — |

## Launcher Commands

After setup, use the generated launcher:

```bash
cd ~/garuda
./garuda.sh up        # start all services
./garuda.sh down      # stop all services
./garuda.sh logs      # follow container logs
./garuda.sh update    # pull latest image & restart
./garuda.sh status    # show container status
./garuda.sh shell     # open a bash shell in the container
./garuda.sh config    # display current configuration
```

**Windows**: use `garuda.bat` or `garuda.ps1` with the same sub-commands.

**macOS**: double-click `Garuda.command` in Finder to start and open your browser,
or use `./garuda.sh` from Terminal.

## Docker Image

The container image is hosted on the **Garuda private Docker registry**:

```
docker.nxs.solutions/garuda/garuda-system:latest
```

During the closed alpha, pulling the image requires authentication with your
[git.nxs.solutions](https://git.nxs.solutions) credentials:

```bash
docker login docker.nxs.solutions
# Username: your git.nxs.solutions username
# Password: your git.nxs.solutions password
```

The setup wizard handles image pulling automatically if Docker is available
and you are already logged in.

## Getting Access (Closed Alpha)

Garuda Intelligence is in **closed alpha**. To get started:

1. **Register** on [git.nxs.solutions](https://git.nxs.solutions/user/sign_up)
   — this gives you access to the source code, package registry, and Docker registry
2. **Register** on [garuda.nxs.solutions](https://garuda.nxs.solutions)
   — this gives you access to Garuda Cloud (remote GPU provisioning, sync, team features)
3. **Login to the Docker registry**:
   ```bash
   docker login docker.nxs.solutions
   ```
4. **Install and run the setup wizard**:
   ```bash
   pip install garuda-setup
   garuda-setup
   ```

If you have trouble accessing any of the services, reach out via the
[issue tracker](https://git.nxs.solutions/garuda/Garuda/issues).

## Links

| Resource | URL |
|----------|-----|
| **Garuda Intelligence** (main site) | [garuda.nxs.solutions](https://garuda.nxs.solutions) |
| **Source Code** (Gitea) | [git.nxs.solutions/garuda/Garuda](https://git.nxs.solutions/garuda/Garuda) |
| **Package Registry** (Gitea PyPI) | [pypi.nxs.solutions](https://pypi.nxs.solutions/api/packages/garuda/pypi/simple) |
| **Docker Registry** | [docker.nxs.solutions](https://docker.nxs.solutions) |
| **PyPI** (public mirror) | [pypi.org/project/garuda-setup](https://pypi.org/project/garuda-setup/) |
| **Issue Tracker** | [git.nxs.solutions/garuda/Garuda/issues](https://git.nxs.solutions/garuda/Garuda/issues) |

## License

MIT — see [LICENSE](../LICENSE) for details.

---

<p align="center">
  <strong>Garuda Intelligence</strong> — Closed Alpha<br>
  <a href="https://garuda.nxs.solutions">garuda.nxs.solutions</a> ·
  <a href="https://git.nxs.solutions">git.nxs.solutions</a> ·
  <a href="https://docker.nxs.solutions">docker.nxs.solutions</a> ·
  <a href="https://pypi.nxs.solutions">pypi.nxs.solutions</a>
</p>
