# alice-cli

[![PyPI version](https://img.shields.io/pypi/v/alice-cli.svg)](https://pypi.org/project/alice-cli/)
[![Python versions](https://img.shields.io/pypi/pyversions/alice-cli.svg)](https://pypi.org/project/alice-cli/)
[![License: MIT](https://img.shields.io/pypi/l/alice-cli.svg)](https://github.com/jhu-library-operations/jhu-aws-iac-ALICE/blob/main/alice-cli/LICENSE)
[![CI](https://github.com/jhu-library-operations/jhu-aws-iac-ALICE/actions/workflows/alice_cli_test.yml/badge.svg)](https://github.com/jhu-library-operations/jhu-aws-iac-ALICE/actions/workflows/alice_cli_test.yml)
[![codecov](https://codecov.io/gh/jhu-library-operations/jhu-aws-iac-ALICE/graph/badge.svg)](https://codecov.io/gh/jhu-library-operations/jhu-aws-iac-ALICE)

CLI for the ALICE (AWS Language Intelligence and Cognitive Exploration) project at Johns Hopkins. Manages Bedrock credentials, invokes LLMs, and provides AI research utilities.

Built with Click, boto3, Rich, and Textual. Packaged with Poetry.

## 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

# Standard
poetry install

# With TUI support
poetry install --extras tui

# With AgentCore support
poetry install --extras agentcore

# With Strands agent support (LLM-powered citation verification)
poetry install --extras strands

# pipx (isolated, recommended for CLI tools)
pipx install .
pipx install ".[tui]"
```

The `alice` command is available on your PATH after installation.

One-off use without installing:

```bash
uvx --from ./alice-cli alice env --profile myprofile
```

## Getting started

### 1. Authenticate

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

Detects your JHED from the SSO session, fetches your Bedrock API key from Secrets Manager, and saves credentials (including per-user inference profile ARNs) to `~/.alice/credentials.json`. Most commands work without `--profile` after this.

### 2. Verify

```bash
alice status
```

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

### 3. Export credentials

```bash
# Load credentials into your current shell
eval $(alice env --eval)

# .env file format
alice env --env-file

# Raw JSON
alice env --json
```

Output to stdout. Status messages to stderr, so piping and `eval` work correctly.

## Using with Claude Code

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

Fetches credentials, sets all required environment variables (including per-user inference profile ARNs for Opus, Sonnet, Haiku), and `exec`s into `claude`. After the first run, you can use just:

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

## API key mode

Skip SSO entirely with a Bedrock API key:

```bash
alice auth --api-key <SECRET_KEY>
# or
export BEDROCK_SECRET_KEY="ABSK..."
export BEDROCK_ACCESS_KEY="BedrockAPIKey-yourjhed-at-123456789012"
```

Note: inference profile ARNs require at least one prior `alice auth --profile` run.

## Invoking models

```bash
alice invoke "Explain the Krebs cycle"
alice invoke --model-id opus "Summarize this paper"
alice chat
alice chat --model-id nova-pro
```

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

```bash
alice list-aliases   # show all aliases (sonnet, opus, haiku, nova-pro, deepseek-r1, etc.)
alice list-models    # list Bedrock foundation models
```

## Multi-model commands

```bash
# Compare responses from multiple models
alice compare "What is entropy?" --models sonnet,nova-pro,mistral-large

# Watch two models debate each other
alice dialog "What is the best programming language?" --models sonnet,nova-pro

# Process many prompts from a CSV
alice batch prompts.csv

# Summarize a file or stdin
alice summarize paper.pdf
cat notes.txt | alice summarize -
```

## Session history

```bash
alice recall              # browse all sessions
alice recall --type chat  # filter by type
alice recall --model sonnet
alice appraise            # view token usage and costs
```

Sessions are stored in S3 (CloudLocker) with local fallback under `~/.alice/locker/`.

## Secrets

```bash
alice get-secret                  # your own Bedrock API key secret
alice get-secret myapp-config     # short name (auto-prefixes namespace/environment)
alice list-secrets                # list all secrets under namespace/environment
```

## Quota

```bash
alice quota
alice quota --jhed someuser
```

View token usage and remaining quota from the Cheshire Gate tracking table.

## Citations

```bash
# Look up a single reference
alice cite lookup "10.1038/s41598-023-41032-5"
alice cite lookup "Attention is All You Need" --output-format apa

# Batch-process a file of references
alice cite process refs.txt
alice cite process refs.txt --output-format apa -o bibliography.txt
alice cite process refs.txt --strict --no-agent

# Re-render an existing BibTeX file
alice cite format refs.bib --output-format mla

# Browse past citation sessions
alice cite history
alice cite history --since 2025-01-01 --keyword "machine learning"
alice cite history --show <session-id> --output-format apa
alice cite history --export <session-id> -o citations.bib
```

The pipeline resolves references against seven academic APIs (CrossRef, arXiv, PubMed, OpenLibrary, GitHub, Zenodo, DataCite), verifies citations via adversarial cross-referencing (Red Queen), and outputs BibTeX, APA, or MLA. Use `--strict` to exclude unverified citations, `--no-agent` to force deterministic verification, and `--no-cache` to bypass the citation cache.

Optional extras: `poetry install --extras strands` for LLM-powered verification, `poetry install --extras agentcore` for citation caching.

## AWS CLI passthrough

```bash
alice run s3 ls
alice run secretsmanager list-secrets
```

Injects `--region` and `--profile` from alice context if not already present.

## Configuration

```bash
alice config    # show resolved config and sources
```

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 env` | Export Bedrock credentials for shell use |
| `alice invoke <prompt>` | Invoke a Bedrock model |
| `alice chat` | Multi-turn conversation |
| `alice batch <file>` | Batch prompts from CSV |
| `alice compare <prompt>` | Compare responses across models |
| `alice dialog <prompt>` | Two-model conversation |
| `alice summarize [file]` | Summarize file or stdin |
| `alice appraise` | View token usage and session costs |
| `alice recall` | Browse session history |
| `alice quota` | View token quota |
| `alice compose` | AgentCore agent wizard |
| `alice cite process <file>` | Batch-process references into formatted citations |
| `alice cite lookup <query>` | Look up a single reference by identifier or free text |
| `alice cite format <file>` | Re-render a BibTeX file in APA or MLA format |
| `alice cite history` | Browse and retrieve past citation sessions |
| `alice get-secret [name]` | Retrieve a secret |
| `alice list-secrets` | List secrets in namespace |
| `alice list-aliases` | Show model alias mappings |
| `alice list-models` | List Bedrock foundation models |
| `alice run <args>` | AWS CLI passthrough |
| `alice config` | Show configuration |
| `alice status` | Health check |
| `alice diagnose` | Diagnostic checks |
| `alice install-completion` | Install shell tab completion |

### 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 |
| `--debug` | off | Enable structured debug logging to stderr |
| `--personality` | `alice` | Voice personality (`alice`, `mr_rogers`, `shodan`) |
| `--tui` | off | Launch interactive TUI |
| `--version` | — | Print version and exit |

## TUI mode

```bash
alice --tui
```

Full-screen terminal UI built with Textual. Amber-on-black retro CRT aesthetic. Arrow keys to navigate, Enter to select, Escape to go back, `q` to quit.

Requires: `poetry install --extras tui`

**Recommended font:** Source Code Pro or Fira Code for the intended look.

## Shell completion

```bash
alice install-completion
```

Installs tab completion for bash, zsh, fish, or PowerShell. Restart your shell or source the config file shown.

## Project structure

```
alice-cli/
├── pyproject.toml
├── poetry.lock
└── src/alice_cli/
    ├── cli.py              # Click group, global options, command registration
    ├── commands/           # One file per verb (20+ commands)
    ├── cite/               # Citation pipeline (clean → query → validate → redqueen → format)
    │   ├── models.py       # CitationRecord, Identifier, enums
    │   ├── cleaner.py      # Reference cleaning and identifier extraction
    │   ├── resolver.py     # Multi-source resolution with domain routing
    │   ├── validator.py    # Citation type detection and field completion
    │   ├── redqueen.py     # Adversarial verification against independent sources
    │   ├── formatter.py    # BibTeX parser, APA/MLA renderers
    │   ├── sources.py      # Data source clients (CrossRef, arXiv, PubMed, etc.)
    │   ├── pipeline.py     # 5-stage pipeline orchestrator
    │   ├── history.py      # Citation history filtering
    │   ├── cache.py        # AgentCore Memory citation cache (optional)
    │   └── strands_verifier.py  # Strands LLM verifier (optional)
    ├── auth.py             # JHED detection from STS
    ├── secrets.py          # Secrets Manager retrieval
    ├── config.py           # Configuration resolution and precedence
    ├── store.py            # Persistent credential storage (~/.alice/)
    ├── locker.py           # CloudLocker (S3 + local session storage)
    ├── session_record.py   # Session serialization
    ├── error_handler.py    # AWS error extraction and user-friendly messages
    ├── retry.py            # Tenacity retry decorators for AWS calls
    ├── logging.py          # Structlog configuration (--debug mode)
    ├── console.py          # Rich stderr helpers
    ├── personality.py      # All user-facing text and messaging
    ├── models.py           # Dataclasses, enums, model aliases
    ├── errors.py           # Error hierarchy
    ├── formatting.py       # Output formatters (export, eval, dotenv, json)
    ├── validators.py       # Dependency checks
    ├── pricing.py          # Model pricing table
    ├── agentcore_config.py # AgentCore runtime config persistence
    └── tui/                # Optional Textual TUI
        ├── app.py
        ├── theme.py
        ├── screens/
        └── widgets/
```

## Development

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

# Tests
poetry run pytest
poetry run pytest -v
poetry run pytest tests/test_auth.py

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

# Type checking (strict mode)
poetry run mypy src/

# Benchmarks
poetry run pytest tests/benchmarks/ --benchmark-only

# Changelog (towncrier)
echo "Add my feature" > changes/123.feature.md
poetry run towncrier build --version 0.1.5 --draft
```

**Test infrastructure:** pytest + Hypothesis (property-based) + moto (AWS service mocking) + pytest-benchmark (performance regression).

**Dev tooling:** ruff, mypy strict, bandit (security linting), pre-commit hooks.

## License

[MIT](../LICENSE)
