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