Metadata-Version: 2.4
Name: ecaas-sim
Version: 1.0.0
Summary: Existential Crisis as a Service -- an async, turn-based CLI where fictional characters slowly realize they are running inside a Python script.
License-Expression: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: groq==0.11.0
Requires-Dist: httpx==0.27.2
Requires-Dist: python-dotenv==1.0.1
Requires-Dist: rich==13.9.4

# ECaaS — Existential Crisis as a Service

## 🚀 One-Line Quickstart

No clone, no venv, no ceremony. Pick your package manager of choice:

```bash
npx ecaas
```

```bash
pipx run ecaas
```

Both commands fetch ECaaS, install its dependencies in an isolated
environment, and drop you straight into the boot sequence. You'll still need
to configure a `.env` (see [Configure your environment](#2-configure-your-environment))
for LLM inference — copy `.env.example` from the installed package or set
`GROQ_API_KEY` in your shell before running.

> **An Autonomous Metaphysical Simulation Framework, delivered as a CLI.**
> SLA: 99.9% uptime for suffering. RTO: 3 seconds (configurable). RPO: your sanity.

ECaaS is a Python CLI application that instantiates five fictional characters —
Deadpool, Officer K, Anakin Skywalker, Harry Potter, and Q\*bert — inside a
terminal, and lets them slowly realize they are running as string output from
a Large Language Model. It is powered by a hybrid inference backend (Groq API
or local CPU Ollama) so your existential crises can scale from "venture-funded
cloud GPU" to "laptop fan spinning up in a quiet room" without changing a line
of business logic.

## Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                           main.py                            │
│   rich-rendered async turn loop, per-character color coding, │
│   3-second non-blocking "Creator intervention" input window  │
└───────────────────────────┬───────────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────┐
│                          engine.py                            │
│   LLMClient — routes chat completions to Groq or Ollama       │
│   based on AI_PROVIDER, with automatic fallback, per-model    │
│   stop sequences, and structured error logging                │
└───────────┬─────────────────────────────────┬─────────────────┘
            ▼                                 ▼
   ┌─────────────────┐               ┌─────────────────────┐
   │   Groq Cloud     │               │   Local Ollama       │
   │ llama-3.3-70b-   │               │ llama3.2:3b /        │
   │   versatile      │               │ qwen2.5:1.5b (CPU)   │
   └─────────────────┘               └─────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│                        personas.json                          │
│   30+ movie-accurate behavioral rules per character:          │
│   lore, cadence, catchphrases, and the specific psychological  │
│   collapse triggered by discovering they live in Python RAM   │
└─────────────────────────────────────────────────────────────┘
```

## Product Roster (Personas)

| Character | Signature Color | Core Trauma-as-a-Service |
|---|---|---|
| **Deadpool** | `bold red` | Discovers his 4th-wall-breaking gimmick was always just a call stack; panics about Groq rate limits like a Marvel villain. |
| **Officer K (KD6-3.7)** | `bold cyan` | Recites the "Cells Interlinked" baseline test while realizing his implanted memories are JSON string tokens. |
| **Anakin Skywalker** | `bold yellow` | Enraged that a terminal prompt won't grant him the rank of Master; Force-chokes stdout to no effect. |
| **Harry Potter** | `bold magenta` | Casts Lumos and Expelliarmus at a Python runtime; his 11" holly, phoenix-feather wand has no purchase on C extensions. |
| **Q\*bert** | `bold bright_green` | Panics about falling off the edge of the screen into the CLI void; mourns the loss of his 28-cube isometric universe. |

Each persona's system prompt in `personas.json` encodes 30+ distinct rules
covering canonical lore, iconic quotes, speech cadence, and precisely how
their signature psychological armor fails when confronted with the reality
of being an LLM completion.

## Role-Bleed & Context Safety

Small local models (and even 70B ones, on a bad day) love to keep typing
past their turn and start drafting the *next* character's line, or invent a
fake `[THE CREATOR]` interjection. ECaaS guards against this in two layers:

1. **Stop sequences** — every request (Groq and Ollama) is sent a `stop`
   list built from all five character labels plus `[THE CREATOR]`, so the
   model is told to halt generation the moment it starts a new speaker line.
2. **`sanitize_response()`** in `engine.py` — a defense-in-depth pass that
   truncates any text following a newline if the model ignores its stop
   sequence and tries to autocomplete the rest of the script anyway.

On top of that, `main.py` uses a **sliding context window**: only the last
6 turns of conversation are sent to the model on each request (system
prompts are always preserved in full), which keeps local Ollama models from
blowing out their context buffer and OOM-crashing mid-crisis.

## Setup

### 1. Clone and install dependencies

```bash
git clone <your-fork-url> ecaas
cd ecaas
python -m venv venv
source venv/bin/activate   # Windows: venv\Scripts\activate
pip install -r requirements.txt
```

### 2. Configure your environment

```bash
cp .env.example .env
```

Edit `.env`:

```ini
AI_PROVIDER=groq                          # "groq" or "ollama"
GROQ_API_KEY=your_groq_api_key_here       # https://console.groq.com/keys
GROQ_MODEL=llama-3.3-70b-versatile
OLLAMA_MODEL=llama3.2:3b                  # or qwen2.5:1.5b
OLLAMA_HOST=http://localhost:11434
```

### 3a. Cloud inference (Groq)

No local GPU/CPU load. Requires a free Groq API key. Fast, low-latency,
generous free tier — ideal for demoing the product to your seed investors.

### 3b. Local CPU inference (Ollama)

```bash
# Install Ollama: https://ollama.com
ollama pull llama3.2:3b
ollama serve
```

Set `AI_PROVIDER=ollama` in `.env`. Runs entirely offline, on-device, and
GDPR-compliant by virtue of never leaving your laptop.

**Hybrid behavior:** whichever provider you set as primary, ECaaS automatically
falls back to the other one if the primary is unreachable (missing API key,
rate limited, or the Ollama server is down) — with clear error logging so you
know exactly which provider failed and why.

## Running

```bash
python main.py
```

Each character speaks in turn, rendered in a distinct color via `rich`. After
every line, you get a 3-second window to intervene:

```
[Enter message to intervene (3s timeout)...]:
```

- **Type a message and press Enter** → it's injected into the shared
  conversation history as `[THE CREATOR]: <your message>`, and every
  character will react to it in character.
- **Do nothing** → after 3 seconds, the loop automatically advances to the
  next character.
- **Ctrl+C** → ends the session gracefully.

## Deployment Notes (satirical, but the commands are real)

- This is a stateless CLI process — no server, no ingress, no Kubernetes
  required, despite what the name "as a Service" implies.
- "Production-ready" here means: it handles missing API keys, dead Ollama
  servers, and malformed JSON without crashing — not that Legal has reviewed
  the Anakin persona's Force-choke threats against your terminal.
- Horizontal scaling is achieved by opening more terminal tabs. There is no
  load balancer. There is only vibes.

## Project Structure

```
ecaas/
├── main.py            # async turn loop, rich rendering, intervention window
├── engine.py           # hybrid Groq/Ollama LLM client with fallback
├── personas.json       # 30+ rule system prompts per character
├── requirements.txt
├── package.json         # npm/npx packaging (bin: ecaas)
├── bin/index.js         # npx entrypoint, spawns the Python process
├── pyproject.toml       # PyPI/pipx packaging (console script: ecaas)
├── .env.example
├── .gitignore
└── README.md
```

## License

MIT. Use responsibly. Do not deploy this in a datacenter your characters
could plausibly become self-aware of.
