aethr 0.1.0__tar.gz

aethr-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.DS_Store
+dist/

aethr-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Archana Pradeep
+
+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.

aethr-0.1.0/PKG-INFO

@@ -0,0 +1,218 @@
+Metadata-Version: 2.4
+Name: aethr
+Version: 0.1.0
+Summary: A lightweight CLI for explicit, reproducible AI coding workflows.
+Project-URL: Homepage, https://github.com/archthegit/Relay
+Project-URL: Repository, https://github.com/archthegit/Relay
+Project-URL: Issues, https://github.com/archthegit/Relay/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: 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 and is printed to the terminal.
+
+## 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.
+
+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.
+
+## Architecture
+
+```text
+aethr/
+  cli.py
+  config.py
+  context.py
+  executor.py
+  llm.py
+  prompts.py
+  workflow.py
+```

aethr-0.1.0/README.md

@@ -0,0 +1,188 @@
+# 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 and is printed to the terminal.
+
+## 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.
+
+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.
+
+## Architecture
+
+```text
+aethr/
+  cli.py
+  config.py
+  context.py
+  executor.py
+  llm.py
+  prompts.py
+  workflow.py
+```

aethr-0.1.0/aethr/__init__.py

@@ -0,0 +1,3 @@
+"""Aethr: explicit pipelines for AI coding workflows."""
+
+__version__ = "0.1.0"

aethr-0.1.0/aethr/cli.py

@@ -0,0 +1,132 @@
+"""Command-line interface for Aethr."""
+
+from typing import Annotated
+
+import typer
+from rich.console import Console
+from rich.panel import Panel
+
+from aethr import __version__
+from aethr.config import CONFIG_FILE, ConfigError, load_workflow_config
+from aethr.executor import StepPrompt, StepResult, build_workflow_prompts, run_workflow
+from aethr.llm import LLMError
+from aethr.workflow import WorkflowTemplateError, available_workflows, init_workflow
+
+
+app = typer.Typer(help="Explicit, reproducible AI coding workflows.")
+console = Console()
+
+
+@app.callback()
+def main() -> None:
+    """Aethr command group."""
+
+
+@app.command()
+def init(
+    preset: Annotated[str | None, typer.Argument(help="Workflow preset to initialize.")] = None,
+    force: Annotated[bool, typer.Option("--force", "-f", help="Overwrite an existing .aethr.yaml.")] = False,
+    list_only: Annotated[bool, typer.Option("--list", "-l", help="List available workflow presets.")] = False,
+) -> None:
+    """Initialize a workflow config from a built-in YAML preset."""
+
+    workflows = available_workflows()
+    if list_only:
+        for workflow in workflows:
+            console.print(workflow)
+        return
+
+    selected = preset
+    if selected is None:
+        console.print("Available workflows:")
+        for index, workflow in enumerate(workflows, start=1):
+            console.print(f"  {index}. {workflow}")
+        choice = typer.prompt("Select a workflow", default="1")
+        selected = _resolve_workflow_choice(choice, workflows)
+
+    try:
+        path = init_workflow(selected, force=force)
+    except WorkflowTemplateError as exc:
+        raise typer.BadParameter(str(exc)) from exc
+
+    console.print(f"Initialized [bold]{path}[/bold] from [cyan]{selected}[/cyan]")
+
+
+@app.command()
+def run(
+    task: Annotated[str, typer.Argument(help="Coding task to run through the pipeline.")],
+    show_prompt: Annotated[
+        bool,
+        typer.Option("--show-prompt", help="Print exact step prompts without calling models."),
+    ] = False,
+) -> None:
+    """Run the configured sequential workflow."""
+
+    console.print(Panel.fit(task, title="Aethr Task", border_style="cyan"))
+    try:
+        config = load_workflow_config()
+    except ConfigError as exc:
+        raise typer.BadParameter(f"{exc}. Run 'aethr init' to create {CONFIG_FILE}.") from exc
+
+    console.print(f"[bold]Workflow[/bold] {config.workflow}")
+    if show_prompt:
+        console.print("[bold]Mode[/bold] prompt preview")
+        for planned in build_workflow_prompts(task, config):
+            _print_step_prompt(planned)
+        console.print("[green]Prompt preview complete[/green]")
+        return
+
+    try:
+        results = run_workflow(task, config, on_step_result=_print_step_result)
+    except LLMError as exc:
+        raise typer.BadParameter(str(exc)) from exc
+    console.print(f"[green]Workflow complete[/green] ({len(results)} step results)")
+
+
+@app.command()
+def version() -> None:
+    """Print the Aethr version."""
+
+    console.print(f"Aethr {__version__}")
+
+
+def _print_step_result(result: StepResult) -> None:
+    """Print one in-memory step result."""
+
+    title = step_title(result.step_id, result.metadata)
+    console.print()
+    console.print(Panel(result.content, title=title, border_style="green"))
+
+
+def _print_step_prompt(planned: StepPrompt) -> None:
+    """Print one planned prompt."""
+
+    title = step_title(planned.step_id, planned.metadata)
+    console.print()
+    console.print(Panel(planned.prompt, title=title, border_style="yellow"))
+
+
+def step_title(step_id: str, metadata: dict[str, str]) -> str:
+    """Build a compact terminal title for a step."""
+
+    return (
+        f"{step_id} | role={metadata['role']} | "
+        f"model={metadata['model']} | context={metadata['context_sources']}"
+    )
+
+
+def _resolve_workflow_choice(choice: str, workflows: list[str]) -> str:
+    """Resolve an interactive workflow prompt response."""
+
+    if choice.isdigit():
+        index = int(choice)
+        if 1 <= index <= len(workflows):
+            return workflows[index - 1]
+    if choice in workflows:
+        return choice
+    choices = ", ".join(workflows)
+    raise typer.BadParameter(f"Unknown workflow '{choice}'. Available workflows: {choices}")
+
+
+if __name__ == "__main__":
+    app()

aethr-0.1.0/aethr/config.py

@@ -0,0 +1,81 @@
+"""Workflow configuration schema and loader."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import yaml
+from pydantic import BaseModel, ConfigDict, Field, ValidationError, model_validator
+
+
+CONFIG_FILE = ".aethr.yaml"
+
+
+class ConfigError(Exception):
+    """Raised when workflow configuration cannot be loaded."""
+
+
+class WorkflowStep(BaseModel):
+    """One sequential step in an Aethr workflow."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    id: str = Field(min_length=1)
+    role: str = Field(min_length=1)
+    context: list[str] = Field(default_factory=list)
+
+
+class WorkflowConfig(BaseModel):
+    """A YAML-defined Aethr workflow."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    workflow: str = Field(min_length=1)
+    roles: dict[str, str] = Field(default_factory=dict)
+    models: dict[str, str] = Field(default_factory=dict)
+    steps: list[WorkflowStep] = Field(min_length=1)
+
+    @model_validator(mode="after")
+    def validate_roles(self) -> "WorkflowConfig":
+        """Ensure configured steps and model routes reference known roles."""
+
+        known_roles = set(self.roles)
+        step_roles = {step.role for step in self.steps}
+        missing_step_roles = sorted(step_roles - known_roles)
+        if missing_step_roles:
+            joined = ", ".join(missing_step_roles)
+            raise ValueError(f"steps reference undefined roles: {joined}")
+
+        unknown_model_roles = sorted(set(self.models) - known_roles)
+        if unknown_model_roles:
+            joined = ", ".join(unknown_model_roles)
+            raise ValueError(f"models reference undefined roles: {joined}")
+
+        return self
+
+
+def load_workflow_config(path: Path | str = CONFIG_FILE) -> WorkflowConfig:
+    """Load and validate an Aethr workflow config file."""
+
+    config_path = Path(path)
+    if not config_path.exists():
+        raise ConfigError(f"Workflow config not found: {config_path}")
+
+    try:
+        raw = yaml.safe_load(config_path.read_text(encoding="utf-8"))
+    except yaml.YAMLError as exc:
+        raise ConfigError(f"Invalid YAML in {config_path}: {exc}") from exc
+
+    if raw is None:
+        raise ConfigError(f"Workflow config is empty: {config_path}")
+    if not isinstance(raw, dict):
+        raise ConfigError(f"Workflow config must be a YAML mapping: {config_path}")
+
+    try:
+        return WorkflowConfig.model_validate(raw)
+    except ValidationError as exc:
+        details = "; ".join(
+            f"{'.'.join(str(part) for part in error['loc'])}: {error['msg']}"
+            for error in exc.errors()
+        )
+        raise ConfigError(f"Invalid workflow config in {config_path}: {details}") from exc