alice-cli 0.1.0__tar.gz

alice_cli-0.1.0/PKG-INFO

@@ -0,0 +1,309 @@
+Metadata-Version: 2.4
+Name: alice-cli
+Version: 0.1.0
+Summary: ALiCE — Your AI research companion at Johns Hopkins
+Author: JH DRCC
+Requires-Python: >=3.12,<4.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+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 .
+
+# With TUI support
+poetry install --extras 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)
+

alice_cli-0.1.0/README.md

@@ -0,0 +1,289 @@
+# 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 .
+
+# With TUI support
+poetry install --extras 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)

alice_cli-0.1.0/pyproject.toml

@@ -0,0 +1,49 @@
+[tool.poetry]
+name = "alice-cli"
+version = "0.1.0"
+description = "ALiCE — Your AI research companion at Johns Hopkins"
+authors = ["JH DRCC"]
+readme = "README.md"
+packages = [{include = "alice_cli", from = "src", format = ["sdist", "wheel"]}]
+
+[tool.poetry.dependencies]
+python = "^3.12"
+click = "^8.1"
+boto3 = "^1.35"
+rich = "^13.0"
+prompt-toolkit = "^3.0"
+filelock = "^3.0"
+textual = {version = "^1.0", optional = true}
+
+[tool.poetry.extras]
+tui = ["textual"]
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^8.0"
+hypothesis = "^6.0"
+pytest-mock = "^3.0"
+ruff = "^0.8"
+mypy = "^1.13"
+boto3-stubs = {extras = ["sts", "secretsmanager", "bedrock", "bedrock-runtime"], version = "^1.35"}
+textual-dev = "^1.0"
+
+[tool.poetry.scripts]
+alice = "alice_cli.cli:cli"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.ruff]
+target-version = "py312"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "UP", "B", "SIM", "TCH"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+
+[tool.mypy]
+python_version = "3.12"
+strict = true