arp-jarvis 0.3.8
Stack distribution that pins compatible JARVIS components.
Requires Python: >=3.10

<div align="center">
  <a href="https://agent-runtime-protocol.com/">
    <picture>
      <source srcset="./assets/JARVIS_Long_Transparent.png">
      <img alt="ARP Logo" src="./assets/JARVIS_Long_Transparent.png" width="80%">
    </picture>
  </a>
</div>

# JARVIS Release (Stack Distribution)

`JARVIS_Release` is the version-pinned, runnable stack distribution for JARVIS (ARP `spec/v1`).
It ships a lock file + Docker Compose setup that brings up a full local stack with sensible defaults.

## What this repo ships

Core spec-facing services:
- Run Gateway
- Run Coordinator
- Atomic Executor
- Composite Executor
- Node Registry
- Selection Service
- PDP

Internal JARVIS services:
- Run Store
- Event Stream
- Artifact Store

Local dev STS (default profile):
- Keycloak (`dev-secure-keycloak`)

## Version pinning

- `stack.lock.json` is the stack source of truth (component versions, node pack versions, helper libs).
- `pyproject.toml` pins the same component versions for the `arp-jarvis` meta package.

Decision: **Mode B / per-service GHCR images**.
Each JARVIS component repo publishes a GHCR image on `vX.Y.Z` tags. This repo consumes those images
via Docker Compose and pins the references in `stack.lock.json`.

## Quickstart (CLI-first, dev-secure-keycloak)

1) Copy the env template:

Default (dev-secure-keycloak):

```bash
cp compose/.env.example compose/.env.local
```

Dev-insecure (no inbound JWT):

```bash
cp compose/.env.example.insecure compose/.env.local
```

Optional (dev-insecure, macOS/Linux or WSL) one-command bring-up:

```bash
bash ./start_dev.sh \
  --llm-api-key "<your_openai_api_key>" \
  --llm-chat-model "gpt-4.1-mini"
```

2) Configure the LLM (required for Selection Service + Composite Executor):

- Set `ARP_LLM_API_KEY` and `ARP_LLM_CHAT_MODEL` in `compose/.env.local`.
- OpenAI is the default profile; `ARP_LLM_PROFILE=openai` is optional.
- For offline tests, you can opt into `ARP_LLM_PROFILE=dev-mock` (not the default).

3) Install the meta CLI:

```bash
python3 -m pip install -e .
arp-jarvis versions
```

This installs the `arp-jarvis` CLI version from your local checkout, while the Docker images remain pinned separately via `STACK_VERSION` in `compose/.env.local` and `stack.lock.json`.

4) Bring up the stack and verify wiring:

```bash
arp-jarvis stack pull
arp-jarvis stack up -d
arp-jarvis doctor
```

5) If using `dev-secure-keycloak` (default), log in once:

```bash
arp-jarvis auth login
```

This is a browser/device flow. The CLI never asks for your password directly. For the default local realm, a dev user is pre-seeded; the credentials are only for the Keycloak login page during the browser step.

6) Start a run:

```bash
arp-jarvis runs start --goal "Generate a UUID, then return it."
```

Notes:
- Keycloak is exposed on `http://localhost:8080` (issuer default).
- Run Gateway is exposed on `8081`. Run Coordinator is exposed on `8082` (configure via `RUN_COORDINATOR_HOST_PORT`).
- If you change `KEYCLOAK_HOST_PORT`, update `ARP_AUTH_ISSUER` in `compose/profiles/dev-secure-keycloak.env`.
- `dev-insecure` disables inbound JWT checks but still runs Keycloak for service-to-service token exchange.
- Node Registry runs with `ARP_AUTH_MODE=optional` to allow Selection Service calls (current Selection
  client does not attach bearer tokens).

### Docker Compose fallback (no CLI)

```bash
docker compose --env-file compose/.env.local -f compose/docker-compose.yml up -d
curl -s http://localhost:8081/v1/health
```

## Stack profiles

Set `STACK_PROFILE` in `compose/.env.local` to one of:
- `dev-secure-keycloak` (default)
- `dev-insecure`
- `enterprise` (template only)

## Meta CLI (arp-jarvis)

Convenience commands for interacting with the running stack:

```bash
arp-jarvis doctor
arp-jarvis auth login
arp-jarvis nodes list
arp-jarvis runs start --goal "Generate a UUID, then return it."
```

Compose wrapper (does not replace `docker compose`):

```bash
arp-jarvis stack up -d --print-command
```

You can also invoke component CLIs via `arp-jarvis`:

```bash
arp-jarvis run-gateway --help
arp-jarvis run-coordinator --help
arp-jarvis atomic-executor --help
```

## Repo layout

```
JARVIS_Release/
  stack.lock.json
  compose/
    docker-compose.yml
    .env.example
    profiles/
      dev-secure-keycloak.env
      dev-insecure.env
      enterprise.env
    keycloak/
      realm-arp-dev.json
  assets/ (diagrams, logos)
```