astra-cli-agent 0.1.0__tar.gz → 0.1.2__tar.gz

astra_cli_agent-0.1.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Astra CLI contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

astra_cli_agent-0.1.2/PKG-INFO

@@ -0,0 +1,207 @@
+Metadata-Version: 2.4
+Name: astra-cli-agent
+Version: 0.1.2
+Summary: Astra — a terminal AI assistant that understands natural language and drives your dev tools.
+Project-URL: Homepage, https://github.com/Subharjun/astra-cli-agent
+Project-URL: Issues, https://github.com/Subharjun/astra-cli-agent/issues
+Author: Astra CLI contributors
+License: MIT
+License-File: LICENSE
+Keywords: agent,ai,cli,developer-tools,langgraph
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.12
+Requires-Dist: faiss-cpu>=1.8
+Requires-Dist: httpx>=0.27
+Requires-Dist: langgraph>=0.2
+Requires-Dist: litellm>=1.44
+Requires-Dist: mcp>=1.0
+Requires-Dist: prompt-toolkit>=3.0
+Requires-Dist: pydantic-settings>=2.3
+Requires-Dist: pydantic>=2.7
+Requires-Dist: pyfiglet>=1.0
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.7
+Requires-Dist: sentence-transformers>=3.0
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Astra CLI
+
+**A terminal AI assistant that understands natural language and drives your developer
+tools** — git, docker, kubernetes, filesystem, code, shell, web research, and MCP plugins
+— through a multi-agent LangGraph pipeline with local memory, RAG, and multi-provider LLM
+fallback.
+
+```
+$ astra "what's the git status here, and run the linter"
+```
+
+[![PyPI](https://img.shields.io/pypi/v/astra-cli-agent.svg)](https://pypi.org/project/astra-cli-agent/)
+[![Python](https://img.shields.io/pypi/pyversions/astra-cli-agent.svg)](https://pypi.org/project/astra-cli-agent/)
+[![CI](https://github.com/Subharjun/astra-cli-agent/actions/workflows/ci.yml/badge.svg)](https://github.com/Subharjun/astra-cli-agent/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+---
+
+## What it does
+
+Every request goes through a real multi-agent pipeline — a router+planner picks the right
+agent(s) and breaks the request into steps, worker agents execute them against real tools,
+a reviewer agent checks the output and can loop back for a revision — not a single prompt
+wrapping a shell call.
+
+| Domain | Agent | Capabilities |
+|---|---|---|
+| Git | `GitAgent` | status, diff, log, blame, branch, commit (auto-generates messages), push, merge, checkout, stash |
+| Filesystem & code | `FileAgent` | read/write/move/delete files, lint & format (`ruff`), run tests (`pytest`), symbol search |
+| Shell | `FileAgent` | runs arbitrary commands behind a hard denylist + confirmation gate |
+| Docker | `DockerAgent` | ps, images, build, run, logs, exec, inspect, rm/rmi, prune |
+| Kubernetes | `KubernetesAgent` | get/describe pods, deployments, services, nodes; apply, scale, rollout restart, delete, exec |
+| Web research | `ResearchAgent` | GitHub repo/issue search, Stack Overflow search, general web search, fetch-with-citation |
+| Debugging | `DebugAgent` | root-causes errors and stack traces, proposes concrete fixes |
+| Documentation | `DocumentationAgent` | writes docstrings, README sections, usage guides |
+| MCP | `MCPAgent` | connects to any configured MCP server (stdio, HTTP, or SSE) and discovers/calls its tools |
+
+Also included:
+
+- **Safety by default** — risky operations (`git push`, file delete, shell, container/exec
+  commands) require interactive confirmation unless you pass `--yes`; a shell denylist
+  blocks obviously destructive commands (`rm -rf /`, fork bombs, `curl | sh`, etc.)
+  regardless of confirmation.
+- **Local memory + RAG** — `astra ingest .` indexes a codebase (SQLite + FAISS); relevant
+  chunks are pulled into the planner's context automatically on later requests.
+- **Multi-provider LLM fallback** — Groq → Anthropic → OpenAI → local Ollama, tries each in
+  order and falls through on failure.
+- **`astra chat`** — an interactive REPL with real token-level streaming, tab-completion,
+  and persistent history.
+- **Cost/token tracking** — `astra memory costs` shows a real per-provider/per-model
+  breakdown and daily spend trend, no external service required.
+- **First-run onboarding** — `astra setup` walks you through picking a provider and tests
+  your key with a real request before saving it.
+
+See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the full design and
+[HANDOFF.md](HANDOFF.md) for exactly what's built, what's tested, and what's left.
+
+## Install
+
+```bash
+pip install astra-cli-agent
+```
+
+or with [uv](https://docs.astral.sh/uv/) / [pipx](https://pipx.pypa.io/) (recommended —
+installs it in an isolated environment while still putting `astra` on your PATH):
+
+```bash
+uv tool install astra-cli-agent
+# or
+pipx install astra-cli-agent
+```
+
+This installs the `astra` command — the PyPI distribution name (`astra-cli-agent`) is
+different from the command you actually run, since `astra-cli` was already taken by an
+unrelated project.
+
+Requires Python 3.12+.
+
+## Quickstart
+
+Astra needs at least one LLM provider before it can answer anything. Run the setup wizard
+once:
+
+```bash
+astra setup
+```
+
+Pick a provider (Groq, Anthropic, OpenAI, or a local Ollama server) and paste a key — it's
+tested with one real, cheap request before being saved to `~/.astra/.env` (never logged,
+never committed). Don't have a key yet? [Groq's free tier](https://console.groq.com/keys)
+is the fastest way to try Astra.
+
+If you skip this step, the first command that actually needs an LLM (`ask`, a bare prompt,
+or `chat`) will offer to run the wizard for you automatically.
+
+Then just talk to it — **from inside whatever project directory you want it to act on**,
+since every tool call is scoped to your current working directory:
+
+```bash
+astra hello                                   # sanity check: install, config, provider status
+astra ask "what's 12 * 8"                     # one-shot LLM call, no agent pipeline
+astra "what's the git status here"            # routes to GitAgent
+astra "create a file called notes.md with a todo list"
+astra "run the linter on this project"
+astra ingest .                                # index this codebase for retrieval
+astra "which file implements the fallback router"   # answer grounded in the ingested code
+astra chat                                    # interactive REPL, streaming + history
+astra memory costs                            # real cost/token breakdown for this session
+```
+
+Risky operations prompt for confirmation by default:
+
+```bash
+astra "delete the file scratch.txt"           # asks first
+astra "delete the file scratch.txt" --yes     # skips the prompt
+```
+
+> Astra performs real actions when you approve them — it's not a dry-run tool. Try it in a
+> throwaway directory first if you want to get a feel for it before pointing it at
+> something you care about.
+
+## Configuration
+
+Astra reads settings in order (each layer overrides the previous):
+
+1. packaged defaults (`src/astra/config/defaults.yaml`)
+2. `~/.astra/config.yaml` (user overrides)
+3. environment variables, e.g. `ASTRA_APP__LOG_LEVEL=DEBUG`
+
+Provider API keys and other secrets live in `~/.astra/.env` (written by `astra setup`) —
+global, not tied to any one project. Conversation history and cost tracking live in
+`~/.astra/astra.db`.
+
+## MCP servers
+
+Add entries under `mcp.servers` in `~/.astra/config.yaml` to give Astra access to any MCP
+server's tools/resources/prompts — same shape as Claude Desktop's `mcpServers` config for
+stdio transport, plus `http`/`sse` for already-running remote servers:
+
+```yaml
+mcp:
+  servers:
+    - name: my-server
+      command: npx
+      args: ["-y", "@some/mcp-server"]
+```
+
+`astra mcp tools` lists everything discovered from your configured servers.
+
+## Contributing / development
+
+```bash
+git clone https://github.com/Subharjun/astra-cli-agent.git
+cd astra-cli-agent
+uv venv && source .venv/bin/activate
+uv pip install -e ".[dev]"
+
+pytest
+ruff check .
+mypy src
+```
+
+CI (`.github/workflows/ci.yml`) runs the same three commands on every push and PR to
+`main`. Releases (`.github/workflows/release.yml`) publish to PyPI via trusted publishing
+(OIDC) when a GitHub Release is published — no token stored in this repo.
+
+## License
+
+[MIT](LICENSE)

astra_cli_agent-0.1.2/README.md

@@ -0,0 +1,169 @@
+# Astra CLI
+
+**A terminal AI assistant that understands natural language and drives your developer
+tools** — git, docker, kubernetes, filesystem, code, shell, web research, and MCP plugins
+— through a multi-agent LangGraph pipeline with local memory, RAG, and multi-provider LLM
+fallback.
+
+```
+$ astra "what's the git status here, and run the linter"
+```
+
+[![PyPI](https://img.shields.io/pypi/v/astra-cli-agent.svg)](https://pypi.org/project/astra-cli-agent/)
+[![Python](https://img.shields.io/pypi/pyversions/astra-cli-agent.svg)](https://pypi.org/project/astra-cli-agent/)
+[![CI](https://github.com/Subharjun/astra-cli-agent/actions/workflows/ci.yml/badge.svg)](https://github.com/Subharjun/astra-cli-agent/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+---
+
+## What it does
+
+Every request goes through a real multi-agent pipeline — a router+planner picks the right
+agent(s) and breaks the request into steps, worker agents execute them against real tools,
+a reviewer agent checks the output and can loop back for a revision — not a single prompt
+wrapping a shell call.
+
+| Domain | Agent | Capabilities |
+|---|---|---|
+| Git | `GitAgent` | status, diff, log, blame, branch, commit (auto-generates messages), push, merge, checkout, stash |
+| Filesystem & code | `FileAgent` | read/write/move/delete files, lint & format (`ruff`), run tests (`pytest`), symbol search |
+| Shell | `FileAgent` | runs arbitrary commands behind a hard denylist + confirmation gate |
+| Docker | `DockerAgent` | ps, images, build, run, logs, exec, inspect, rm/rmi, prune |
+| Kubernetes | `KubernetesAgent` | get/describe pods, deployments, services, nodes; apply, scale, rollout restart, delete, exec |
+| Web research | `ResearchAgent` | GitHub repo/issue search, Stack Overflow search, general web search, fetch-with-citation |
+| Debugging | `DebugAgent` | root-causes errors and stack traces, proposes concrete fixes |
+| Documentation | `DocumentationAgent` | writes docstrings, README sections, usage guides |
+| MCP | `MCPAgent` | connects to any configured MCP server (stdio, HTTP, or SSE) and discovers/calls its tools |
+
+Also included:
+
+- **Safety by default** — risky operations (`git push`, file delete, shell, container/exec
+  commands) require interactive confirmation unless you pass `--yes`; a shell denylist
+  blocks obviously destructive commands (`rm -rf /`, fork bombs, `curl | sh`, etc.)
+  regardless of confirmation.
+- **Local memory + RAG** — `astra ingest .` indexes a codebase (SQLite + FAISS); relevant
+  chunks are pulled into the planner's context automatically on later requests.
+- **Multi-provider LLM fallback** — Groq → Anthropic → OpenAI → local Ollama, tries each in
+  order and falls through on failure.
+- **`astra chat`** — an interactive REPL with real token-level streaming, tab-completion,
+  and persistent history.
+- **Cost/token tracking** — `astra memory costs` shows a real per-provider/per-model
+  breakdown and daily spend trend, no external service required.
+- **First-run onboarding** — `astra setup` walks you through picking a provider and tests
+  your key with a real request before saving it.
+
+See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the full design and
+[HANDOFF.md](HANDOFF.md) for exactly what's built, what's tested, and what's left.
+
+## Install
+
+```bash
+pip install astra-cli-agent
+```
+
+or with [uv](https://docs.astral.sh/uv/) / [pipx](https://pipx.pypa.io/) (recommended —
+installs it in an isolated environment while still putting `astra` on your PATH):
+
+```bash
+uv tool install astra-cli-agent
+# or
+pipx install astra-cli-agent
+```
+
+This installs the `astra` command — the PyPI distribution name (`astra-cli-agent`) is
+different from the command you actually run, since `astra-cli` was already taken by an
+unrelated project.
+
+Requires Python 3.12+.
+
+## Quickstart
+
+Astra needs at least one LLM provider before it can answer anything. Run the setup wizard
+once:
+
+```bash
+astra setup
+```
+
+Pick a provider (Groq, Anthropic, OpenAI, or a local Ollama server) and paste a key — it's
+tested with one real, cheap request before being saved to `~/.astra/.env` (never logged,
+never committed). Don't have a key yet? [Groq's free tier](https://console.groq.com/keys)
+is the fastest way to try Astra.
+
+If you skip this step, the first command that actually needs an LLM (`ask`, a bare prompt,
+or `chat`) will offer to run the wizard for you automatically.
+
+Then just talk to it — **from inside whatever project directory you want it to act on**,
+since every tool call is scoped to your current working directory:
+
+```bash
+astra hello                                   # sanity check: install, config, provider status
+astra ask "what's 12 * 8"                     # one-shot LLM call, no agent pipeline
+astra "what's the git status here"            # routes to GitAgent
+astra "create a file called notes.md with a todo list"
+astra "run the linter on this project"
+astra ingest .                                # index this codebase for retrieval
+astra "which file implements the fallback router"   # answer grounded in the ingested code
+astra chat                                    # interactive REPL, streaming + history
+astra memory costs                            # real cost/token breakdown for this session
+```
+
+Risky operations prompt for confirmation by default:
+
+```bash
+astra "delete the file scratch.txt"           # asks first
+astra "delete the file scratch.txt" --yes     # skips the prompt
+```
+
+> Astra performs real actions when you approve them — it's not a dry-run tool. Try it in a
+> throwaway directory first if you want to get a feel for it before pointing it at
+> something you care about.
+
+## Configuration
+
+Astra reads settings in order (each layer overrides the previous):
+
+1. packaged defaults (`src/astra/config/defaults.yaml`)
+2. `~/.astra/config.yaml` (user overrides)
+3. environment variables, e.g. `ASTRA_APP__LOG_LEVEL=DEBUG`
+
+Provider API keys and other secrets live in `~/.astra/.env` (written by `astra setup`) —
+global, not tied to any one project. Conversation history and cost tracking live in
+`~/.astra/astra.db`.
+
+## MCP servers
+
+Add entries under `mcp.servers` in `~/.astra/config.yaml` to give Astra access to any MCP
+server's tools/resources/prompts — same shape as Claude Desktop's `mcpServers` config for
+stdio transport, plus `http`/`sse` for already-running remote servers:
+
+```yaml
+mcp:
+  servers:
+    - name: my-server
+      command: npx
+      args: ["-y", "@some/mcp-server"]
+```
+
+`astra mcp tools` lists everything discovered from your configured servers.
+
+## Contributing / development
+
+```bash
+git clone https://github.com/Subharjun/astra-cli-agent.git
+cd astra-cli-agent
+uv venv && source .venv/bin/activate
+uv pip install -e ".[dev]"
+
+pytest
+ruff check .
+mypy src
+```
+
+CI (`.github/workflows/ci.yml`) runs the same three commands on every push and PR to
+`main`. Releases (`.github/workflows/release.yml`) publish to PyPI via trusted publishing
+(OIDC) when a GitHub Release is published — no token stored in this repo.
+
+## License
+
+[MIT](LICENSE)

{astra_cli_agent-0.1.0 → astra_cli_agent-0.1.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "astra-cli-agent"
-version = "0.1.0"
+version = "0.1.2"
 description = "Astra — a terminal AI assistant that understands natural language and drives your dev tools."
 readme = "README.md"
 requires-python = ">=3.12"
@@ -18,6 +18,7 @@ classifiers = [
     "Environment :: Console",
     "Intended Audience :: Developers",
 ]
+
 dependencies = [
     "typer>=0.12",
     "rich>=13.7",
@@ -32,6 +33,7 @@ dependencies = [
     "sentence-transformers>=3.0",
     "mcp>=1.0",
     "prompt-toolkit>=3.0",
+    "pyfiglet>=1.0",
 ]
 
 [project.optional-dependencies]
@@ -43,6 +45,10 @@ dev = [
     "types-PyYAML>=6.0",
 ]
 
+[project.urls]
+Homepage = "https://github.com/Subharjun/astra-cli-agent"
+Issues = "https://github.com/Subharjun/astra-cli-agent/issues"
+
 [project.scripts]
 astra = "astra.cli.app:main"
 

astra_cli_agent-0.1.2/src/astra/__init__.py

@@ -0,0 +1,8 @@
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("astra-cli-agent")
+except PackageNotFoundError:
+    # Editable/source checkout with no installed distribution metadata yet (e.g. before the
+    # first `pip install -e .`) — matches pyproject.toml's version so it's never stale.
+    __version__ = "0.1.2"

{astra_cli_agent-0.1.0 → astra_cli_agent-0.1.2}/src/astra/cli/chat.py

@@ -17,7 +17,7 @@ from prompt_toolkit import PromptSession
 from prompt_toolkit.completion import WordCompleter
 from prompt_toolkit.history import FileHistory
 
-from astra.cli.rendering import console, make_stream_printer, print_error
+from astra.cli.rendering import console, make_stream_printer, print_banner, print_error
 from astra.core.graph import AstraGraph, build_default_graph
 from astra.core.settings import Settings
 from astra.memory.store import MemoryStore
@@ -89,7 +89,8 @@ def run_chat(settings: Settings, assume_yes: bool = False) -> None:
 
     graph = build_default_graph(settings, on_reviewer_chunk=_dispatch)
 
-    console.print("[bold cyan]Astra chat[/bold cyan] — type /help for commands, /exit to leave.")
+    print_banner()
+    console.print("type /help for commands, /exit to leave.\n")
 
     while True:
         try:

{astra_cli_agent-0.1.0 → astra_cli_agent-0.1.2}/src/astra/cli/rendering.py

@@ -5,20 +5,32 @@ from __future__ import annotations
 from collections.abc import Callable
 
 from rich.console import Console
-from rich.panel import Panel
 from rich.status import Status
 
 console = Console()
 error_console = Console(stderr=True, style="bold red")
 
+# Top-to-bottom gradient applied to the figlet banner's lines, cyan through violet — purely
+# cosmetic, no meaning attached to the specific stops.
+_BANNER_GRADIENT = ["#22d3ee", "#38bdf8", "#818cf8", "#a78bfa", "#e879f9"]
+
 
 def print_banner() -> None:
-    console.print(
-        Panel.fit(
-            "[bold cyan]Astra[/bold cyan] — your terminal AI developer assistant",
-            border_style="cyan",
-        )
-    )
+    """Big, colored "ASTRA" wordmark shown at the start of the commands a human actually
+    reads interactively (`hello`, `setup`, `chat`) — not on every invocation, since `ask`/
+    `run` are also used non-interactively/scripted and shouldn't pay for it or clutter
+    piped output."""
+    import pyfiglet  # lazy: only the three banner-printing commands need this at all
+    from rich.text import Text
+
+    banner = Text()
+    art_lines = pyfiglet.figlet_format("ASTRA", font="slant").split("\n")
+    for i, line in enumerate(art_lines):
+        if not line.strip():
+            continue
+        banner.append(line + "\n", style=f"bold {_BANNER_GRADIENT[i % len(_BANNER_GRADIENT)]}")
+    console.print(banner, no_wrap=True)
+    console.print("  [dim italic]your terminal AI developer assistant[/dim italic]\n")
 
 
 def print_error(message: str) -> None:

astra_cli_agent-0.1.0/PKG-INFO

@@ -1,130 +0,0 @@
-Metadata-Version: 2.4
-Name: astra-cli-agent
-Version: 0.1.0
-Summary: Astra — a terminal AI assistant that understands natural language and drives your dev tools.
-Author: Astra CLI contributors
-License: MIT
-Keywords: agent,ai,cli,developer-tools,langgraph
-Classifier: Environment :: Console
-Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.12
-Requires-Python: >=3.12
-Requires-Dist: faiss-cpu>=1.8
-Requires-Dist: httpx>=0.27
-Requires-Dist: langgraph>=0.2
-Requires-Dist: litellm>=1.44
-Requires-Dist: mcp>=1.0
-Requires-Dist: prompt-toolkit>=3.0
-Requires-Dist: pydantic-settings>=2.3
-Requires-Dist: pydantic>=2.7
-Requires-Dist: python-dotenv>=1.0
-Requires-Dist: pyyaml>=6.0
-Requires-Dist: rich>=13.7
-Requires-Dist: sentence-transformers>=3.0
-Requires-Dist: typer>=0.12
-Provides-Extra: dev
-Requires-Dist: mypy>=1.10; extra == 'dev'
-Requires-Dist: pytest-cov>=5.0; extra == 'dev'
-Requires-Dist: pytest>=8.0; extra == 'dev'
-Requires-Dist: ruff>=0.5; extra == 'dev'
-Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
-Description-Content-Type: text/markdown
-
-# Astra CLI
-
-A terminal-based AI assistant that understands natural language and drives your
-developer tools — git, docker, kubernetes, code, and more — through a multi-agent
-LangGraph pipeline with local memory and RAG.
-
-> All 18 build phases are complete. See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for
-> the full design and [HANDOFF.md](HANDOFF.md) for exactly what's done and what's left
-> (mostly external setup — PyPI trusted publishing, a working LangSmith key, a local k8s
-> cluster).
-
-## Install
-
-Once published, install with:
-
-```bash
-pip install astra-cli-agent    # or: uv tool install astra-cli-agent
-```
-
-This installs the `astra` command on your PATH — the PyPI distribution name
-(`astra-cli-agent`) is different from the command you actually run.
-
-### Install (development)
-
-```bash
-uv venv
-source .venv/bin/activate
-uv pip install -e ".[dev]"
-```
-
-or with plain pip:
-
-```bash
-python -m venv .venv
-source .venv/bin/activate
-pip install -e ".[dev]"
-```
-
-## Getting started
-
-Astra needs at least one LLM provider before it can answer anything. The first time you
-run a command that needs one (`astra ask`, `astra "<prompt>"`, `astra chat`) with none
-configured, it offers to walk you through setup right there — same as most terminal AI
-tools do on first run. You can also trigger it directly:
-
-```bash
-astra setup
-```
-
-This walks you through picking a provider (Groq, Anthropic, OpenAI, or a local Ollama
-server), pastes-and-tests your API key with one real, cheap request before saving it, and
-writes it to `~/.astra/.env` — never logged, never committed. Run it again any time to
-add more providers (recommended, so `FallbackRouter` has something to fall back to).
-
-```bash
-astra hello     # sanity check: confirms install + config + whether a provider is set up
-astra version   # print installed version
-astra ask "..."  # one-shot LLM call, no agent pipeline
-astra "explain this code"   # full natural-language agent pipeline
-astra chat       # interactive REPL with streaming, history, autocomplete
-```
-
-## Configuration
-
-Astra reads, in order (each layer overrides the previous):
-
-1. packaged defaults (`src/astra/config/defaults.yaml`)
-2. `~/.astra/config.yaml` (user overrides)
-3. environment variables, e.g. `ASTRA_APP__LOG_LEVEL=DEBUG`
-
-Provider API keys live in `~/.astra/.env` (written by `astra setup`) or a project-local
-`.env` (copy `.env.example` to get started by hand instead of the wizard).
-
-## Releasing (maintainers)
-
-CI (`.github/workflows/ci.yml`) runs ruff/mypy/pytest on every push and PR to `main`.
-
-Publishing to PyPI (`.github/workflows/release.yml`) uses PyPI's trusted-publishing (OIDC)
-flow — no token stored in this repo. One-time setup required on PyPI, done once by
-whoever owns the `astra-cli-agent` project there:
-
-1. Register the `astra-cli-agent` project on PyPI (or claim it if unclaimed).
-2. In that project's PyPI settings → Publishing, add a trusted publisher: this GitHub repo,
-   workflow file `release.yml`, environment name `pypi`.
-3. In this repo's GitHub settings → Environments, create an environment named `pypi`
-   (ideally with a required-reviewer rule, so a published Release doesn't auto-publish
-   without a human glance).
-4. Cut a GitHub Release (tag + "Publish release" in the UI) — that triggers the workflow.
-
-## Development
-
-```bash
-pytest
-ruff check .
-mypy src
-```