Metadata-Version: 2.3
Name: aurora-research
Version: 0.1.0
Summary: Aurora 🌌 — Autonomous AI research scientist. Multi-model, ARIS-powered.
Author: dududu
Author-email: dududu <1816619485@qq.com>
Requires-Dist: httpx>=0.28.1
Requires-Dist: openai>=2.43.0
Requires-Dist: pydantic>=2.13.4
Requires-Dist: python-dotenv>=1.2.2
Requires-Dist: rich>=15.0.0
Requires-Dist: typer>=0.26.7
Requires-Python: >=3.12
Project-URL: Homepage, https://github.com/dududu/aurora-research
Project-URL: Repository, https://github.com/dududu/aurora-research
Description-Content-Type: text/markdown

# Aurora Research Agent

**Autonomous AI research scientist** -- multi-model, ARIS-powered scientific research agent.

Aurora handles the full research workflow: literature survey, idea discovery, experiment implementation, cross-model review, and paper writing -- all from the command line.

## Features

- **Multi-model support** -- DeepSeek (default), OpenAI, Anthropic, and any OpenAI-compatible API
- **Autonomous agent loop** -- Tool-using AI that reads/writes files, runs code, searches the web
- **ARIS research workflows** -- Idea discovery, auto-review loops, paper writing, full pipeline
- **White-label** -- Branded as "Aurora", never exposes underlying model/provider identity
- **Cross-model review** -- Executor and reviewer use different models for adversarial quality control
- **Resumable runs** -- State persistence enables recovery from crashes or context compaction

## Quick Start

### Prerequisites

- Python 3.12+
- [uv](https://docs.astral.sh/uv/) (package manager)
- A DeepSeek API key ([get one here](https://platform.deepseek.com/api_keys))

### Install

```bash
# Install from PyPI
uv tool install aurora-research
# Creates the `aurora-ai` command

# Or try without installing
uvx aurora-research run "Search arXiv for recent papers on LLM reasoning"
```

### Configure

Set your API key:

```bash
# Option 1: Environment variable
export DEEPSEEK_API_KEY="sk-your-key-here"

# Option 2: .env file
echo 'DEEPSEEK_API_KEY=sk-your-key-here' > .env

# Option 3: Interactive config
aurora-ai config
```

### Basic Usage

```bash
# One-shot task
aurora-ai run "Explain the Transformer architecture with code examples"

# Interactive chat
aurora-ai chat

# Plan-first execution (read-only research, then execute)
aurora-ai plan "Build a PyTorch training pipeline for CIFAR-10"

# List available models
aurora-ai models
```

## Research Workflows

### Idea Discovery

```bash
aurora-ai idea "efficient attention mechanisms for long-context LLMs" --num-ideas 8
```

Pipeline: literature survey -> idea generation (8-12 ideas) -> novelty check -> critical review -> ranked report

### Auto Review Loop

```bash
aurora-ai review --target ./experiment_results/ --rounds 4
```

Cross-model adversarial review: reviewer evaluates work -> executor fixes issues -> re-review -> repeat until score >= 7/10

### Paper Writing

```bash
aurora-ai paper "Efficient Attention via Hierarchical Token Pruning" --assure draft
```

Pipeline: paper plan -> figures -> LaTeX writing -> compilation -> improvement loop

### Full Research Pipeline

```bash
aurora-ai pipeline "continual learning without catastrophic forgetting" --write
```

End-to-end: idea discovery -> experiments -> review -> paper

## Model Configuration

Aurora uses **model aliases** -- user-friendly names that hide the underlying provider:

| Alias | Description |
|-------|-------------|
| `fast` | Fast & affordable (default) |
| `pro` | Balanced performance |
| `deep` | Deep reasoning |

```bash
# Use a specific model
aurora-ai run --model pro "Complex reasoning task"

# Add a custom model
aurora-ai config add turbo --provider openai --model gpt-4o --key sk-xxx
```

## Architecture

```
CLI (aurora-ai) -> Agent Loop (tool-use engine) -> LLM Backend (multi-model)
                         |
              Tools: read, write, edit, bash, glob, grep, web_search, web_fetch
                         |
              Skills: idea-discovery, auto-review, paper-writing, pipeline
```

## Permission Modes

| Mode | Behavior |
|------|----------|
| `default` | Ask before destructive operations |
| `acceptEdits` | Auto-approve file edits (default for `run`) |
| `bypassPermissions` | Auto-approve everything (use `-y` flag) |
| `plan` | Read-only, research only |

## Development

```bash
git clone https://github.com/user/aurora-research.git
cd aurora-research
uv sync
uv run pytest
```

## License

MIT
