Metadata-Version: 2.4
Name: aurora-actr
Version: 0.5.1
Summary: AURORA: Adaptive Unified Reasoning and Orchestration Architecture with MCP Integration
Author-email: AURORA Team <aurora@example.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/hamr/aurora
Project-URL: Documentation, https://github.com/hamr/aurora/blob/main/README.md
Project-URL: Repository, https://github.com/hamr/aurora
Project-URL: Issues, https://github.com/hamr/aurora/issues
Project-URL: Changelog, https://github.com/hamr/aurora/blob/main/CHANGELOG.md
Keywords: aurora,actr,cognitive-architecture,semantic-search,mcp,reasoning,soar
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: pydantic>=2.0.0
Requires-Dist: jsonschema>=4.17.0
Requires-Dist: click>=8.1.0
Requires-Dist: rich>=13.0.0
Requires-Dist: python-frontmatter>=1.0.0
Requires-Dist: jinja2>=3.1.0
Requires-Dist: python-slugify>=8.0.0
Requires-Dist: questionary>=2.0.0
Requires-Dist: pyyaml>=6.0.0
Requires-Dist: tree-sitter>=0.20.0
Requires-Dist: tree-sitter-python>=0.20.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: anthropic>=0.18.0
Requires-Dist: openai>=1.0.0
Requires-Dist: ollama>=0.1.0
Requires-Dist: tenacity>=8.2.0
Requires-Dist: fastmcp>=0.1.0
Provides-Extra: ml
Requires-Dist: sentence-transformers>=2.2.0; extra == "ml"
Requires-Dist: torch>=2.0.0; extra == "ml"
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: pytest-benchmark>=4.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.5.0; extra == "dev"
Requires-Dist: types-jsonschema>=4.0.0; extra == "dev"
Requires-Dist: bandit>=1.7.5; extra == "dev"
Requires-Dist: memory-profiler>=0.61.0; extra == "dev"

# AURORA

**Version 0.5.1** | [PyPI](https://pypi.org/project/aurora-actr/) | [Commands](COMMANDS.md) | [SOAR Reasoning](docs/SOAR.md) | [ML Models](docs/ML_MODELS.md)

Adaptive Unified Reasoning and Orchestration Architecture - Project-based AI memory and reasoning system.

## What It Does

AURORA adds persistent memory and structured reasoning to AI coding tools (Claude Code, Cursor, etc.).

**Three core capabilities:**

1. **Multi-turn SOAR Reasoning** - 9-phase cognitive pipeline for complex queries with automatic escalation
2. **Planning & Agent Discovery** - OpenSpec-adapted workflow orchestration with agent registry
3. **ACT-R Memory** - Tree-sitter AST indexing with activation-based retrieval for code, knowledge, and reasoning patterns

**Retrieval modes:**
- Lightweight: BM25 keyword + Git signals + ACT-R activation (default, ~520KB)
- Enhanced: Add semantic embeddings with optional ML package (~1.9GB)

**Storage:** Project-local `.aurora/` directory (SQLite database, no cloud required).

## Installation

### PyPI (Recommended)

```bash
pip install aurora-actr
```

### With Semantic Search (Optional)

```bash
pip install aurora-actr[ml]  # Adds PyTorch + sentence-transformers (~1.9GB)
```

### Development

```bash
git clone https://github.com/amrhas82/aurora.git
cd aurora
./install.sh
```

## Quick Start

```bash
# Initialize in your project
cd your-project/
aur init

# Index your codebase
aur mem index .

# Search indexed memory
aur mem search "authentication logic"

# Multi-turn SOAR reasoning
aur soar "How does the payment flow work?"

# Create implementation plan
aur plan create "Add user authentication"

# Health check
aur doctor
```

## What Gets Indexed

AURORA indexes three types of chunks:

- **code** - Python functions, classes, methods (tree-sitter AST parsing)
- **kb** - Markdown documentation (README.md, docs/, PRDs)
- **soar** - Reasoning patterns (auto-saved after `aur soar` queries)

**Default exclusions:** `.git/`, `venv/`, `node_modules/`, `tasks/`, `CHANGELOG.md`, `LICENSE*`, `build/`, `dist/`

**Custom exclusions:** Create `.auroraignore` (gitignore-style patterns):

```
# .auroraignore example
tests/**
docs/archive/**
*.tmp
```

## Retrieval Strategy

**Hybrid scoring (default, no ML required):**
- 40% BM25 keyword matching
- 30% ACT-R activation (usage frequency + recency)
- 30% Git signals (modification patterns)

**With ML option (`[ml]`):**
- 30% BM25 keyword matching
- 40% Semantic similarity (sentence-transformers)
- 30% ACT-R activation

**Speed:** Sub-500ms on 10K+ chunks.

## Documentation

- [Commands Reference](COMMANDS.md) - Complete CLI command documentation
- [SOAR Reasoning](docs/SOAR.md) - 9-phase cognitive pipeline details
- [ML Models Guide](docs/ML_MODELS.md) - Custom embedding model configuration
- [MCP Deprecation](docs/MCP_DEPRECATION.md) - Why MCP tools were deprecated
- [Migration Guide](docs/MIGRATION.md) - Migrating from MCP tools to slash commands

## Architecture

**Cognitive Foundations:**
- ACT-R activation-based memory (cognitive science)
- SOAR 9-phase reasoning pipeline (State/Operator/Result)
- Tree-sitter for accurate AST parsing

**Design Principles:**
- Project-local (no cloud, `.aurora/` directory)
- Lightweight by default (BM25 + activation)
- Optional semantic search (ML package)
- No API keys for memory/search operations

## Configuration

**Indexing:** `aur init` or `aur mem index .`

**Excluding files:** Create `.auroraignore` in project root

**Changing ML model:** See [ML Models Guide](docs/ML_MODELS.md)

**MCP integration:** Deprecated in v0.5.0, use slash commands instead

## Requirements

- Python 3.10+
- ~520KB (base install)
- ~1.9GB additional (with ML features)

## License

MIT License

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md)
