diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index 8c6de83..9400675 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -1,6 +1,6 @@ --- name: Bug report -about: Something in Open AURA is broken +about: Something in OpenAURA is broken labels: [bug] --- diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md index 785a5fc..d171a94 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.md +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -1,6 +1,6 @@ --- name: Feature request -about: Suggest an addition or change to Open AURA +about: Suggest an addition or change to OpenAURA labels: [enhancement] --- @@ -14,9 +14,9 @@ labels: [enhancement] ## Alternatives considered -## Does it fit Open AURA's scope? +## Does it fit OpenAURA's scope? -Open AURA is **stateless, CI-native, agent-generated weekly briefs**. It is not a +OpenAURA is **stateless, CI-native, agent-generated weekly briefs**. It is not a dashboard, not a server, not a SaaS. Features that require persistent state, a UI, or a hosted service are unlikely to land. diff --git a/.github/scorecard.yml b/.github/scorecard.yml index 60fa196..b14b386 100644 --- a/.github/scorecard.yml +++ b/.github/scorecard.yml @@ -6,7 +6,7 @@ annotations: - checks: - pinned-dependencies reasons: - - reason: not-applicable # Open AURA is a Python library; CI intentionally resolves package metadata across supported Python versions. + - reason: not-applicable # OpenAURA is a Python library; CI intentionally resolves package metadata across supported Python versions. - checks: - fuzzing reasons: diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1d31dcf..53137e6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,6 @@ -# Contributing to Open AURA +# Contributing to OpenAURA -Thanks for your interest in contributing! Open AURA is small and opinionated — the rules +Thanks for your interest in contributing! OpenAURA is small and opinionated — the rules below keep it that way. ## Ground rules diff --git a/PYPI.md b/PYPI.md new file mode 100644 index 0000000..21679a9 --- /dev/null +++ b/PYPI.md @@ -0,0 +1,142 @@ +

+ OpenAURA logo +

+ +[![PyPI](https://img.shields.io/pypi/v/open-aura?logo=pypi&logoColor=white)](https://pypi.org/project/open-aura/) +[![Python](https://img.shields.io/pypi/pyversions/open-aura?logo=python&logoColor=white)](https://pypi.org/project/open-aura/) +[![CI](https://github.com/pradelgorithm/openaura/actions/workflows/ci.yml/badge.svg)](https://github.com/pradelgorithm/openaura/actions/workflows/ci.yml) +[![CodeQL](https://github.com/pradelgorithm/openaura/actions/workflows/codeql.yml/badge.svg)](https://github.com/pradelgorithm/openaura/actions/workflows/codeql.yml) +[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/pradelgorithm/openaura/badge)](https://securityscorecards.dev/viewer/?uri=github.com/pradelgorithm/openaura) +[![Coverage](https://codecov.io/gh/pradelgorithm/openaura/graph/badge.svg)](https://codecov.io/gh/pradelgorithm/openaura) +[![License](https://img.shields.io/badge/License-Apache_2.0-3b82f6.svg)](https://github.com/pradelgorithm/openaura/blob/main/LICENSE) + +OpenAURA is a CI-native Python CLI that generates recurring project briefs from +delivery signals and writes markdown reports into `aura-docs/`. + +This page is the technical package reference. The human/product README lives in the +[GitHub repository](https://github.com/pradelgorithm/openaura#readme). + +## Requirements + +- Python 3.11 or newer +- A model provider key for Anthropic or OpenAI +- At least one signal connector, currently GitHub or Azure DevOps + +The project CI verifies Python 3.11, 3.12, 3.13, and 3.14. + +## Installation + +```bash +python -m pip install open-aura +``` + +The package installs the `aura` console command. + +## Configuration + +Create `aura.config.yml` at the root of the repository where briefs should be written: + +```yaml +project: "my-project" +trigger: weekly +schedule: "friday-5pm" +model: "anthropic:claude-sonnet-4-6" + +signals: + github: + repo: "owner/repository" + token_env: GITHUB_TOKEN + default_branch: main + +kpis: + - throughput + - cycle_time + - blockers + - bug_count + +custom_kpis: [] + +output: + folder: "aura-docs" +``` + +Supported `trigger` values are: + +- `weekly` +- `on-merge` +- `both` + +The `schedule` field is documentation for humans. The actual cron schedule belongs +in your CI workflow. + +## Environment Variables + +OpenAURA reads secret values from environment variables. The config file stores only +the variable names. + +| Purpose | Default variable | +|---|---| +| Anthropic models | `ANTHROPIC_API_KEY` | +| OpenAI models | `OPENAI_API_KEY` | +| GitHub connector | `GITHUB_TOKEN` | +| Azure DevOps org | `AZURE_DEVOPS_ORG` | +| Azure DevOps project | `AZURE_DEVOPS_PROJECT` | +| Azure DevOps token | `AZURE_DEVOPS_TOKEN` | + +Model strings beginning with `anthropic:` require `ANTHROPIC_API_KEY`. Model strings +beginning with `openai:` require `OPENAI_API_KEY`. + +## CLI + +```bash +aura validate +aura run +aura run --dry-run +aura run --trigger on-merge +aura manifesto +``` + +`aura validate` checks the config and required environment variables without making +API or LLM calls. + +`aura run` gathers signals, scores the project state, summarizes the brief, and writes +markdown to the configured output folder. + +`aura run --dry-run` prints the structured brief JSON instead of writing a file. + +## GitHub Actions + +Install OpenAURA in a workflow with pip: + +```yaml +- uses: actions/setup-python@v6 + with: + python-version: "3.13" + +- run: python -m pip install open-aura +- run: aura validate +- run: aura run + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} + OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }} +``` + +The repository includes starter workflow templates for weekly, on-merge, and combined +trigger modes. + +## Output + +By default, briefs are written to: + +```text +aura-docs/ +``` + +Each brief is markdown, intended to be committed back to the same repository by CI. + +## Links + +- Source: https://github.com/pradelgorithm/openaura +- Issues: https://github.com/pradelgorithm/openaura/issues +- Security policy: https://github.com/pradelgorithm/openaura/blob/main/SECURITY.md diff --git a/README.md b/README.md index a3b78ed..dc6fb30 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,9 @@
-

AURA

+

+ OpenAURA logo +

Agentic Updates, Reviews, and Accountability.

@@ -209,7 +211,7 @@ outruns manual reporting. ### 1. Install -Open AURA supports Python 3.11 and newer. The CI matrix currently verifies Python +OpenAURA supports Python 3.11 and newer. The CI matrix currently verifies Python 3.11, 3.12, 3.13, and 3.14. ```bash diff --git a/SECURITY.md b/SECURITY.md index 5016ace..2c44126 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -2,7 +2,7 @@ ## Supported versions -Open AURA is pre-1.0. Only the latest minor release receives security patches. +OpenAURA is pre-1.0. Only the latest minor release receives security patches. | Version | Supported | |---------|-----------| @@ -55,7 +55,7 @@ once a fix ships, crediting the reporter unless anonymity is requested. ## Secrets handling expectations -Open AURA runs in CI and reads signals from external APIs. It: +OpenAURA runs in CI and reads signals from external APIs. It: - Accepts secrets only from environment variables (never from config files). - Never logs secret values; tokens are redacted in error messages. diff --git a/brandbook/openaura-logo.svg b/brandbook/openaura-logo.svg new file mode 100644 index 0000000..f0ddeb1 --- /dev/null +++ b/brandbook/openaura-logo.svg @@ -0,0 +1,12 @@ + + OpenAURA + OpenAURA horizontal logo with aperture mark. + + + + + + + + OpenAURA + diff --git a/openaura/__init__.py b/openaura/__init__.py index b822338..53e0125 100644 --- a/openaura/__init__.py +++ b/openaura/__init__.py @@ -1,4 +1,4 @@ -"""Open AURA — Agentic Updates, Reviews, and Accountability.""" +"""OpenAURA — Agentic Updates, Reviews, and Accountability.""" from __future__ import annotations diff --git a/openaura/agents/_core.py b/openaura/agents/_core.py index d1581d2..a38fd3f 100644 --- a/openaura/agents/_core.py +++ b/openaura/agents/_core.py @@ -43,7 +43,7 @@ def model_id(config_model: str) -> str: """Build the Pydantic AI model string. Provider-prefixed strings pass through unchanged. Bare model names remain - Anthropic for backwards compatibility with early Open AURA configs. + Anthropic for backwards compatibility with early OpenAURA configs. """ if ":" in config_model: return config_model @@ -58,6 +58,6 @@ def model_ref(config_model: str | Model) -> str | Model: def model_api_key_env_var(config_model: str) -> str | None: - """Return the API key env var Open AURA can infer from a Pydantic AI model string.""" + """Return the API key env var OpenAURA can infer from a Pydantic AI model string.""" provider = model_id(config_model).split(":", maxsplit=1)[0] return MODEL_PROVIDER_ENV_VARS.get(provider) diff --git a/openaura/instructions/manifesto.md b/openaura/instructions/manifesto.md index 4c2d9a5..cedb77f 100644 --- a/openaura/instructions/manifesto.md +++ b/openaura/instructions/manifesto.md @@ -1,6 +1,6 @@ # AURA Manifesto -Open AURA is not a framework in the heavy sense. It is an update protocol: a small, +OpenAURA is not a framework in the heavy sense. It is an update protocol: a small, repeatable way for any repo to turn delivery signals into accurate project briefs. The protocol exists so teams can stop translating work into status by hand. A repo diff --git a/openaura/main.py b/openaura/main.py index ebfe9a9..fa39313 100644 --- a/openaura/main.py +++ b/openaura/main.py @@ -18,7 +18,7 @@ from openaura.models.config import AuraConfig, Trigger from openaura.output import markdown as md_out -app = typer.Typer(add_completion=False, no_args_is_help=True, help="Open AURA — weekly briefs.") +app = typer.Typer(add_completion=False, no_args_is_help=True, help="OpenAURA — weekly briefs.") log = logging.getLogger("openaura") EXIT_CONFIG = 1 diff --git a/pyproject.toml b/pyproject.toml index c77dfc7..c403ab4 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -6,11 +6,11 @@ build-backend = "hatchling.build" name = "open-aura" version = "0.1.1" description = "Agentic Updates, Reviews, and Accountability — CI-native weekly project briefs powered by Pydantic AI." -readme = "README.md" +readme = "PYPI.md" requires-python = ">=3.11" license = "Apache-2.0" license-files = ["LICENSE"] -authors = [{ name = "Open AURA contributors" }] +authors = [{ name = "OpenAURA contributors" }] keywords = ["ai", "agents", "devops", "pydantic-ai", "ci", "reporting", "openai", "anthropic"] classifiers = [ "Development Status :: 3 - Alpha", @@ -67,6 +67,7 @@ include = [ "openaura", "tests", "README.md", + "PYPI.md", "MANIFESTO.md", "AGENTS.md", "LICENSE",