Metadata-Version: 2.3
Name: alice-cli
Version: 0.1.3
Summary: ALiCE — AI research uility for the Johns Hopkins Libraries
Author: Steven J Miklovic,Johns Hopkins DRCC
Requires-Python: >=3.12,<4.0
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Provides-Extra: tui
Requires-Dist: boto3 (>=1.35,<2.0)
Requires-Dist: click (>=8.1,<9.0)
Requires-Dist: filelock (>=3.0,<4.0)
Requires-Dist: prompt-toolkit (>=3.0,<4.0)
Requires-Dist: rich (>=13.0,<14.0)
Requires-Dist: textual (>=1.0,<2.0) ; extra == "tui"
Description-Content-Type: text/markdown

# alice-cli

Python CLI for the ALICE (Artificial Language Intelligence and Cognitive Exploration) project at Johns Hopkins. A unified tool for Bedrock credential management, model invocation, secrets operations, and AWS passthrough.

Built with Click, boto3, and Rich. Packaged with Poetry. Runs with `uv`/`uvx`.

## Prerequisites

- Python 3.12+
- AWS CLI configured with an SSO profile (e.g. `drcc-ai`)
- Active SSO session: `aws sso login --profile <PROFILE>`

## Installation

```bash
cd alice-cli

# Poetry (standard)
poetry install

# uv
uv pip install .

# pipx (isolated environment, recommended for CLI tools)
pipx install .

# With TUI support
poetry install --extras tui
# or with pipx
pipx install ".[tui]"
```

After installation, the `alice` command is available on your PATH.

For one-off usage without installing:

```bash
uvx --from ./alice-cli alice get-key --profile myprofile
```

## Getting started

### 1. Authenticate

Run `alice auth` with your AWS SSO profile to validate your identity and store your Bedrock API key credentials locally:

```bash
alice auth --profile <PROFILE>
```

This detects your JHED from the SSO session, fetches your Bedrock API key from Secrets Manager, and saves everything (including your per-user inference profile ARNs) to `~/.alice/credentials.json`.

After this initial auth, most commands work without `--profile` because the stored credentials are used automatically.

### 2. Verify your setup

```bash
alice status
```

Shows your SSO session state, identity, region, and namespace.

### 3. Get your Bedrock API key

```bash
# Print export statements (default)
alice get-key

# Load credentials into your current shell
eval $(alice get-key --eval)

# .env file format
alice get-key --env-file

# Raw JSON from Secrets Manager
alice get-key --json
```

Output goes to stdout. Banners and status messages go to stderr, so piping and `eval` work correctly.

The credential set includes: `AWS_BEARER_TOKEN_BEDROCK`, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `BEDROCK_ACCESS_KEY`, `BEDROCK_SECRET_KEY`, `AWS_REGION`, `CLAUDE_CODE_USE_BEDROCK`, `ANTHROPIC_MODEL`, and the `ANTHROPIC_DEFAULT_*_MODEL` inference profile vars.

## Using with Claude Code

```bash
alice auth --profile <PROFILE> --claude
```

This retrieves your credentials, sets all required environment variables (including your per-user application inference profile ARNs for Opus, Sonnet, and Haiku), and `exec`s into `claude`. Requires `claude` on your PATH.

Once you've authenticated with `--profile` at least once, you can launch Claude using just your stored API key:

```bash
alice auth --claude
```

## API key mode

If you have a Bedrock API key but no AWS SSO profile, you can use it directly:

```bash
alice auth --api-key <SECRET_KEY>
```

Or set the environment variables:

```bash
export BEDROCK_ACCESS_KEY="BedrockAPIKey-yourjhed-at-123456789012"
export BEDROCK_SECRET_KEY="ABSK..."
```

API key mode skips SSO and Secrets Manager entirely. Note that inference profile ARNs require at least one prior `alice auth --profile <PROFILE>` run to be stored — the API key alone cannot fetch them from Secrets Manager.

## Invoking models

```bash
alice invoke "Explain the Krebs cycle"

# Specify a model by alias
alice invoke --model-id claude-opus-4.6 "Hello"

# Or by full model ID
alice invoke --model-id us.anthropic.claude-sonnet-4-6 "Hello"
```

Default model: `sonnet` → `us.anthropic.claude-sonnet-4-6`.

### Model aliases

```bash
alice list-aliases
```

Shows all available short names (e.g. `sonnet`, `opus`, `haiku`, `nova-pro`, `deepseek-r1`) and their corresponding Bedrock model IDs.

### List foundation models

```bash
alice list-models
```

Lists all available foundation models from the Bedrock API.

## Secrets operations

```bash
# Get your own Bedrock API key secret
alice get-secret

# Get a secret by short name (auto-prefixes namespace/environment)
alice get-secret myapp-config

# List all secrets under the namespace/environment prefix
alice list-secrets
```

## AWS CLI passthrough

```bash
alice run s3 ls
```

Forwards arguments to `aws` and injects `--region` and `--profile` from the alice context if not already present.

## Configuration

```bash
# Show resolved config values and their sources
alice config
```

Defaults can be overridden with CLI flags, environment variables, or stored credentials. Precedence: CLI flag > environment variable > stored credentials > default.

| Setting | Default | Env var | CLI flag |
|---|---|---|---|
| Profile | — | `AWS_PROFILE` | `--profile` |
| Region | `us-east-1` | — | `--region` |
| Namespace | `drcc` | `ALICE_NAMESPACE` | `--namespace` |
| Environment | `ai` | `ALICE_ENVIRONMENT` | `--environment` |
| API key | — | `BEDROCK_SECRET_KEY` | `--api-key` |

## Command reference

| Command | Description |
|---|---|
| `alice auth` | Authenticate and store credentials |
| `alice auth --claude` | Authenticate and launch Claude Code |
| `alice get-key` | Print Bedrock credentials for shell export |
| `alice get-secret [name]` | Retrieve a secret (defaults to your own) |
| `alice list-secrets` | List secrets under your namespace |
| `alice invoke <prompt>` | Invoke a Bedrock model |
| `alice list-aliases` | Show model alias → model ID mappings |
| `alice list-models` | List available Bedrock foundation models |
| `alice run <args>` | AWS CLI passthrough |
| `alice config` | Show resolved configuration |
| `alice status` | Health check (SSO, identity, region) |

### Global options

| Option | Default | Description |
|---|---|---|
| `--profile` | `$AWS_PROFILE` | AWS CLI profile |
| `--region` | `us-east-1` | AWS region |
| `--namespace` | `drcc` | Resource namespace |
| `--environment` | `ai` | Deployment environment |
| `--api-key` | `$BEDROCK_SECRET_KEY` | Bedrock API key (skips SSO) |
| `--quiet` | off | Suppress banner and status messages |
| `--tui` | off | Launch interactive TUI mode |
| `--version` | — | Print version and exit |

## TUI mode

```bash
alice --tui
```

Launches a full-screen terminal interface built with Textual. Amber-on-black retro CRT aesthetic. Keyboard-driven: arrow keys to navigate, Enter to select, Escape to go back, `q` to quit.

Requires the `tui` extra: `poetry install --extras tui`

### Recommended terminal font

For the intended look, set your terminal emulator's font to **Source Code Pro** or **Fira Code**. Both are free, open-source monospace fonts that pair well with the JHU brand palette. The TUI will display a hint on startup if it detects a different font (macOS only).

- [Source Code Pro](https://github.com/adobe-fonts/source-code-pro) — Adobe's monospace companion to Source Sans/Serif
- [Fira Code](https://github.com/tonsky/FiraCode) — monospace with programming ligatures

## How JHED detection works

The CLI detects your JHED automatically from your active SSO session. It calls `sts get-caller-identity`, parses the assumed-role ARN to extract the session name (an email address), and takes the portion before `@` as your JHED.

Secrets are keyed by `{namespace}/{environment}/bedrock-api-keys/{jhed}@jhu.edu`.

## Project structure

```
alice-cli/
├── pyproject.toml
├── poetry.lock
└── src/alice_cli/
    ├── cli.py              # Click group, global options, command registration
    ├── commands/
    │   ├── auth.py         # alice auth [--claude]
    │   ├── get_key.py      # alice get-key [--eval|--env-file|--json]
    │   ├── invoke.py       # alice invoke
    │   ├── list_models.py  # alice list-models
    │   ├── list_aliases.py # alice list-aliases
    │   ├── get_secret.py   # alice get-secret [name]
    │   ├── list_secrets.py # alice list-secrets
    │   ├── run.py          # alice run <aws args...>
    │   ├── config_cmd.py   # alice config
    │   └── status.py       # alice status
    ├── auth.py             # JHED detection from STS
    ├── secrets.py          # Secrets Manager retrieval and validation
    ├── formatting.py       # Output formatters (export, eval, dotenv, json)
    ├── config.py           # Configuration resolution and precedence
    ├── store.py            # Persistent credential storage (~/.alice/)
    ├── console.py          # Rich console helpers (stderr output)
    ├── personality.py      # All user-facing text and messaging
    ├── validators.py       # Dependency checks (aws, jq, python version)
    ├── models.py           # Dataclasses, enums, model aliases
    ├── errors.py           # Error hierarchy (AuthError, SecretError, DependencyError)
    └── tui/                # Optional Textual TUI (requires extras)
        ├── app.py
        ├── theme.py
        ├── theme.tcss
        ├── screens/
        └── widgets/
```

## Development

```bash
cd alice-cli
poetry install --extras tui

# Run tests
poetry run pytest

# Lint and format
poetry run ruff check .
poetry run ruff format .

# Type checking
poetry run mypy src/
```

Dev dependencies: pytest, hypothesis, pytest-mock, ruff, mypy, boto3-stubs.

Tests use Hypothesis for property-based testing (format correctness, config precedence, JHED extraction, secret path construction, AWS passthrough argument forwarding) alongside standard unit tests for error conditions and edge cases.

## License

[MIT](../LICENSE)

