Metadata-Version: 2.4
Name: aethr
Version: 0.1.1
Summary: A lightweight CLI for explicit, reproducible AI coding workflows.
Project-URL: Homepage, https://github.com/archthegit/Aethr
Project-URL: Repository, https://github.com/archthegit/Aethr
Project-URL: Issues, https://github.com/archthegit/Aethr/issues
Author: Archana Pradeep
License-Expression: MIT
License-File: LICENSE
Keywords: ai,cli,coding,llm,workflow
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development
Classifier: Topic :: Utilities
Requires-Python: >=3.12
Requires-Dist: litellm>=1.60.0
Requires-Dist: pydantic>=2.10.0
Requires-Dist: python-dotenv>=1.0.1
Requires-Dist: pyyaml>=6.0.2
Requires-Dist: rich>=13.9.0
Requires-Dist: typer>=0.15.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# Aethr

A tiny CLI for running explicit AI coding workflows from YAML.

## Core Idea

Coding with LLMs is not one-shot generation.

Real development is:

```text
plan -> implement -> review -> iterate
```

Aethr makes those workflows programmable. A run is just:

```text
task + workflow + explicit context + model routing
```

Aethr is stateless. The only project file it creates is `.aethr.yaml`.

## Install

```bash
pip install aethr
```

For local development:

```bash
pip install -e ".[dev]"
```

## Quickstart

```bash
aethr init review-existing-diff
aethr run "review my current changes before I commit"
```

Aethr copies a YAML preset into `.aethr.yaml`. Edit it like any other project
file.

## How Aethr Works

- **Task**: the instruction passed on the command line.
- **Workflow**: the YAML file that defines ordered steps.
- **Steps**: sequential units of work. Aethr runs them in order.
- **Roles**: named responsibilities such as `planner`, `reviewer`, or `writer`.
- **Context**: explicit repo input declared per step.
- **Model routing**: each role can point at a different LiteLLM model.

Each step receives the task, prior step outputs, and its declared context. The
step result stays in memory, streams to the terminal as it is generated, and
is printed in a Rich panel when complete.

## Example Workflow Config

```yaml
workflow: review-existing-diff

roles:
  reviewer: Review the provided task context as if it were an existing diff.

models:
  reviewer: openai:gpt-5.5

steps:
  - id: review
    role: reviewer
    context:
      - git_diff
```

## Built-In Workflows

- `plan-implement-review`: plan a task, propose an implementation, review it.
- `review-existing-diff`: review the current working tree diff.
- `debug-failing-test`: diagnose a failing test, propose a fix, review it.
- `add-tests`: plan, draft, and review focused test coverage.
- `docs-sync`: update docs from the current diff and README context.
- `custom`: a minimal one-step workflow to edit freely.

List presets:

```bash
aethr init --list
```

Initialize another preset:

```bash
aethr init docs-sync --force
```

## Examples

The `examples/` directory contains small workflow files you can copy from:

- `examples/review-existing-diff.yaml`
- `examples/add-tests.yaml`
- `examples/docs-sync.yaml`

## Explicit Context

Aethr uses explicit context instead of automatic retrieval. That keeps runs easy
to understand: the YAML shows exactly what each step can see.

Supported context sources:

- `git_diff`: runs `git diff --no-ext-diff`.
- `file:<path>`: reads one UTF-8 file relative to the project root.
- `glob:<pattern>`: reads matching UTF-8 files relative to the project root,
  with a small content cap.

Example:

```yaml
steps:
  - id: review-docs
    role: reviewer
    context:
      - git_diff
      - file:README.md
      - glob:docs/**/*.md
```

Missing files, empty diffs, non-git directories, and unreadable files appear as
clear placeholder notes in the prompt.

## Prompt Previewing

Use `--show-prompt` to see exactly what Aethr would send to each model:

```bash
aethr run "review my current changes before I commit" --show-prompt
```

Aethr does not call models in prompt preview mode. For later steps, it uses a
clear placeholder where real previous step output would appear.

## Mock Mode

Aethr works without API keys by returning deterministic mock responses.

Aethr also loads a project-level `.env` automatically before model calls, so
credentials can live alongside the workflow file without extra flags.

Use the models configured in `.aethr.yaml`:

```bash
AETHR_LIVE=1 aethr run "review my current changes"
```

Override every configured model with one LiteLLM model:

```bash
AETHR_MODEL=openai:gpt-5.5 aethr run "review my current changes"
```

## Philosophy

Aethr should feel like:

- `git`
- `pytest`
- `rg`
- `cargo`

It should not feel like:

- an agent framework
- an autonomous coding platform
- an AI operating system

Aethr intentionally avoids persistence, replay systems, caches, plugins, DAGs,
async runtimes, vector search, automatic retrieval, memory systems, and agent
abstractions.

If a workflow fails, Aethr prints a copyable JSON checkpoint for the completed
steps. Pass that back with `--resume-checkpoint` to continue from the next
step without rerunning the earlier ones.

## Future Work

One likely future UX is workflow promotion: take a one-off run that worked and
turn it into an editable `.aethr.yaml` workflow. The idea is to help users go
from ad hoc sessions to repeatable workflows without introducing session
storage, replay systems, or hidden history.

## Architecture

```text
aethr/
  cli.py
  config.py
  context.py
  executor.py
  llm.py
  prompts.py
  workflow.py
```
