---
language:
  - en
license: mit
tags:
  - llama
  - mlx
  - vllm
  - 4-bit
  - local-ai
  - private
  - maritime
  - vessel-tracking
  - osint
library_name: mlx
pipeline_tag: text-generation
base_model: meta-llama/Llama-3.1-8B-Instruct
---

# 🧠 Marziel AI — v0.5.7

**Private Local Intelligence — runs entirely on your hardware.**

Marziel AI is a locally-powered AI assistant with real-time maritime intelligence, web search, browser automation, GitHub analysis, URL reading, code generation, and autonomous agent capabilities — all without sending a single byte to the cloud.

## Quick Install

```bash
pip install marziel
marziel serve
```

That's it. vLLM is auto-installed as a dependency. The first run downloads the model from Hugging Face. Everything is automatic.

## Changelog

### v0.5.7
- **CPU uses safetensors** — vLLM CPU loads `model.safetensors` from HF (GGUF not supported on CPU)
- **GPU uses GGUF** — faster local loading with quantized model
- **Fixed tokenizer** — `PreTrainedTokenizerFast` in HF tokenizer_config.json

### v0.5.6
- **Clean install logic** — only installs vLLM if missing; detects GPU → CUDA, no GPU → CPU wheel
- No forced uninstalls — respects existing user environment

### v0.5.5
- **Tokenizer fix** — `--trust-remote-code` for custom tokenizer loading
- **Clean CPU install** — auto-uninstalls CUDA vllm/torch before installing CPU wheel

### v0.5.4
- **vLLM CPU pre-built wheel** — auto-installs `vllm+cpu` from GitHub releases on CPU-only machines
- **GPU auto-detects** — installs standard CUDA vLLM when NVIDIA GPU present
- **CPU optimized** — `bfloat16` dtype, `VLLM_CPU_KVCACHE_SPACE`, TCMalloc, Intel OpenMP
- **3-minute CPU timeout** — 180s for CPU model loading

### v0.5.3
- **Fixed CPU device detection** — set `VLLM_TARGET_DEVICE=cpu` for machines without GPU
- **vLLM debug logging** — errors now saved to `~/.marziel/vllm.log`

### v0.5.2
- **Prefix caching** — system prompt KV cache reused across requests (faster responses)
- **120s CPU timeout** — longer startup window for CPU-only machines loading 4.6GB model
- All NVIDIA GPUs supported (GTX, RTX, Tesla, A100) — auto-detected via `nvidia-smi`

### v0.5.1
- **vLLM auto-installs** — no more manual `pip install vllm`, it's a declared dependency
- **8GB RAM optimized** — reduced context to 2048 tokens, eager execution, swap-space fallback
- **Engine routing** — Apple Silicon → MLX, everything else → vLLM (CPU & GPU)

### v0.5.0
- Unified architecture: MLX (Apple Silicon) + vLLM (all other platforms)
- GGUF Q4_K_M model for vLLM (~4.6 GB)
- Auto-download model from Hugging Face
- Zero-config: `pip install marziel && marziel serve`

## What It Does

| Feature | Description |
|---------|-------------|
| 🧠 **AI Chat** | Conversational AI with personality, code generation, data analysis |
| 📡 **Maritime Intelligence** | Real-time GDACS, GDELT, NASA EONET, AIS, market data, bunker prices |
| 💰 **Market Data** | Live Brent crude, BDI, EU Carbon, freight rates, forex, 12-port bunker prices |
| 🚢 **Vessel Integration** | AIS tracking, fleet management, voyage data, maintenance records |
| 🔌 **Third-Party Connectors** | Plug in MarineTraffic, VesselFinder, Spire, Datalastic, or any REST API |
| 📊 **Live Reports** | Generate comprehensive maritime intelligence reports on demand |
| 🔍 **Web Search** | Live internet results via DuckDuckGo — always up-to-date answers |
| 🌐 **Browser Control** | Headless Chromium automation — navigate, click, type, screenshot |
| 🔗 **URL Analysis** | Share any link — reads, extracts, and analyzes content |
| 🐙 **GitHub Analysis** | Paste any repo URL — get architecture, languages, README analysis |
| ⚡ **Autonomous Agent** | Multi-step reasoning with bash, file, web, browser, and maritime tools |
| 🔒 **100% Private** | Everything runs locally. Zero cloud dependency |

## Maritime Intelligence (Enterprise)

Marziel integrates real-time maritime data from multiple global sources:

```
┌───────────────────────────────────────────────────────────┐
│                   MARZIEL MARITIME INTEL                   │
├───────────────────────────────────────────────────────────┤
│  OSINT (Free APIs)         │  Platform Integration        │
│  ─────────────────         │  ────────────────────        │
│  📡 GDACS — Disasters      │  🚢 Fleet Vessels            │
│  📰 GDELT — Geopolitics    │  🗺️  Active Voyages          │
│  🌍 NASA EONET — Climate   │  ⚠️  Risk Zones              │
│  💰 Yahoo Finance — Market │  🏗️  Maintenance             │
│  💱 ExchangeRate — Forex   │  📋 Incidents                │
│  🚢 AISStream — Tracking   │  ⛽ Fuel Records             │
│                            │  🏭 Port Directory           │
├───────────────────────────────────────────────────────────┤
│  Third-Party Connectors (Enterprise)                      │
│  ─────────────────────────────────                        │
│  MarineTraffic · VesselFinder · Spire Maritime            │
│  Datalastic · OpenWeather · Custom REST API               │
└───────────────────────────────────────────────────────────┘
```

### Market Data Sources

| Data | Source | Update |
|------|--------|--------|
| Brent Crude Oil | Yahoo Finance (BZ=F) | Real-time |
| Bunker VLSFO/MGO/HSFO | Brent-derived (12 ports) | Real-time |
| Baltic Dry Index | BDRY ETF × 200 | Real-time |
| EU Carbon (EUA) | KRBN ETF × 2.1 | Real-time |
| Freight Rates | DSX/GNK shipping stocks | Real-time |
| Exchange Rates | ExchangeRate API (9 currencies) | Real-time |

### Third-Party Integration

Connect Marziel to any maritime service via `~/.marziel/connectors.json`:

```json
{
  "connectors": [
    {"type": "marinetraffic", "api_key": "YOUR_KEY"},
    {"type": "openweather", "api_key": "YOUR_KEY"},
    {
      "type": "custom",
      "name": "my_fleet",
      "base_url": "https://api.myfleet.com/v1",
      "api_key": "secret",
      "endpoints": {
        "vessels": "/ships",
        "voyages": "/trips",
        "weather": "/weather?lat={lat}&lon={lon}"
      }
    }
  ]
}
```

### Maritime API Endpoints

```
GET  /api/maritime/report           — Full intelligence report
GET  /api/maritime/data/market      — Live market data
GET  /api/maritime/data/bunker      — 12-port bunker prices
GET  /api/maritime/data/fx          — Exchange rates
GET  /api/maritime/data/gdacs       — Disaster events
GET  /api/maritime/data/gdelt       — Geopolitical news
GET  /api/maritime/data/nasa        — Natural events
GET  /api/maritime/data/ais         — Vessel tracking
GET  /api/maritime/data/vessels     — Fleet data
GET  /api/maritime/data/voyages     — Voyage data
GET  /api/maritime/data/risk-zones  — Active risk zones
GET  /api/maritime/data/ports       — Port directory
GET  /api/maritime/connectors       — List connectors
POST /api/maritime/connectors/query — Query third-party services
```

## Agent Tools

The LLM has access to 20+ tools:

| Tool | Purpose |
|------|---------|
| `bash` | Shell command execution |
| `file_read` / `file_write` | File I/O |
| `web_search` | DuckDuckGo search |
| `browser` | Headless Chromium automation |
| `maritime_report` | Full intelligence report |
| `market_data` | Brent, BDI, Carbon, bunker, freight |
| `gdacs` | Active disasters & cyclones |
| `gdelt` | Geopolitical conflict news |
| `nasa` | NASA EONET natural events |
| `ais` | Live AIS vessel tracking |
| `fleet` | Fleet vessel data |
| `voyages` | Active voyage data |
| `risk_zones` | Active risk zones |
| `ports` | Global port directory |
| `exchange_rates` | Live forex rates |
| `maintenance` | Vessel maintenance records |
| `incidents` | Maritime incident reports |
| `fuel` | Fuel consumption data |
| `port_calls` | Port call history |

## Requirements

- **RAM**: 8GB minimum (16GB recommended)
- **Disk**: ~5GB for the model
- **Python**: 3.10+
- **Supported platforms**:
  - Apple Silicon (M1/M2/M3/M4) — MLX inference
  - NVIDIA GPU — vLLM with CUDA (auto-detected)
  - AMD/Intel CPU — vLLM CPU mode
  - Intel GPU, AMD GPU, TPU — vLLM (see [vLLM docs](https://docs.vllm.ai))

## Usage

```bash
# Install and start (basic)
pip install marziel
marziel serve

# With browser automation
pip install "marziel[browser]"
python -m playwright install chromium
marziel serve

# Check status
marziel status

# Show version
marziel version
```

Then open **http://localhost:8001** — your private AI dashboard.

## Architecture

```
┌──────────────────────────────────────────────┐
│  Browser (localhost:8001)                     │
│  ┌────────────────────────────────────────┐   │
│  │  Marziel Dashboard (React)            │   │
│  │  Dashboard · Chat · Settings          │   │
│  └──────────────┬─────────────────────────┘   │
│                 │ API calls                    │
│  ┌──────────────▼─────────────────────────┐   │
│  │  Marziel Backend (Flask+Gunicorn)     │   │
│  │  Agent · Search · Browser · Maritime  │   │
│  │  Billing · Connectors · Reports       │   │
│  └──────┬───────┬───────┬─────────────────┘   │
│         │       │       │                      │
│  ┌──────▼──┐ ┌──▼────┐ ┌▼──────────────────┐  │
│  │ LLM     │ │ OSINT │ │ Third-Party APIs   │  │
│  │ MLX/vLLM│ │ GDACS │ │ MarineTraffic      │  │
│  │ 8B 4bit │ │ GDELT │ │ VesselFinder       │  │
│  │         │ │ NASA  │ │ Spire · Custom     │  │
│  │         │ │ Yahoo │ │                    │  │
│  └─────────┘ └───────┘ └────────────────────┘  │
│                YOUR MACHINE                     │
└──────────────────────────────────────────────┘
```

## Pricing

| Plan | Price | Features |
|------|-------|----------|
| **Free** | €0/mo | AI Chat, Web Search, URL Analysis, GitHub Analysis |
| **Pro** | €20/mo | + Agent Mode, Browser Control, Priority Inference |
| **Enterprise** | €199/mo | + Maritime Intelligence, Connectors, Reports, Custom Fine-tuning |

## Links

- 🌐 Website: [marziel.com](https://marziel.com)
- 💻 GitHub: [github.com/efops/marziel](https://github.com/efops/marziel)
- 🤗 Model: [huggingface.co/efops/marziel-8b-custom](https://huggingface.co/efops/marziel-8b-custom)
- 📦 PyPI: [pypi.org/project/marziel](https://pypi.org/project/marziel)

## Contact

📧 info@efkan-isazade.com

## License

MIT License

---

Built with ❤️ by Efe (Efkan Isazade)
