alice-cli 0.2.1

ALiCE — AI research uility for the Johns Hopkins Libraries

alice-cli

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

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:

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

Getting started

1. Authenticate

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

alice status

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

3. Export credentials

# 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

alice auth --profile <PROFILE> --claude

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

alice auth --claude

API key mode

Skip SSO entirely with a Bedrock API key:

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

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.

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

Multi-model commands

# 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

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

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

alice quota
alice quota --jhed someuser

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

Citations

# 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

alice run s3 ls
alice run secretsmanager list-secrets

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

Configuration

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

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

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

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