aurora-actr 0.3.1__py3-none-any.whl

aurora_actr-0.3.1.dist-info/METADATA

@@ -0,0 +1,480 @@
+Metadata-Version: 2.4
+Name: aurora-actr
+Version: 0.3.1
+Summary: AURORA: Adaptive Unified Reasoning and Orchestration Architecture with MCP Integration
+Home-page: https://github.com/aurora/aurora
+Author: AURORA Team
+Author-email: AURORA Team <aurora@example.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/yourusername/aurora
+Project-URL: Documentation, https://github.com/yourusername/aurora/blob/main/README.md
+Project-URL: Repository, https://github.com/yourusername/aurora
+Project-URL: Issues, https://github.com/yourusername/aurora/issues
+Project-URL: Changelog, https://github.com/yourusername/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: aurora-core
+Requires-Dist: aurora-context-code
+Requires-Dist: aurora-soar
+Requires-Dist: aurora-reasoning
+Requires-Dist: aurora-cli
+Requires-Dist: aurora-testing
+Requires-Dist: aurora-planning
+Provides-Extra: ml
+Requires-Dist: sentence-transformers>=2.2.0; extra == "ml"
+Requires-Dist: torch>=2.0.0; extra == "ml"
+Provides-Extra: mcp
+Requires-Dist: fastmcp>=0.1.0; extra == "mcp"
+Provides-Extra: all
+Requires-Dist: sentence-transformers>=2.2.0; extra == "all"
+Requires-Dist: torch>=2.0.0; extra == "all"
+Requires-Dist: fastmcp>=0.1.0; extra == "all"
+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"
+Requires-Dist: aurora-testing; extra == "dev"
+Dynamic: author
+Dynamic: home-page
+Dynamic: requires-python
+
+# AURORA
+
+**Adaptive Unified Reasoning and Orchestration Architecture**
+
+A cognitive architecture framework that brings intelligent memory, reasoning, and orchestration capabilities to AI systems. Built on cognitive science principles (ACT-R, SOAR), AURORA enables AI agents to maintain persistent context, learn from experience, and coordinate complex tasks efficiently.
+
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+## Features
+
+**MCP Server Integration**
+- Native Claude Code CLI integration via Model Context Protocol
+- 7 powerful tools for seamless codebase search, analysis, and intelligent querying
+- No API key required - MCP tools provide context to Claude Code CLI's built-in LLM
+- Conversation-driven development workflow directly from your terminal
+
+**Cognitive Reasoning**
+- ACT-R activation-based memory (frequency, recency, semantic similarity)
+- SOAR-inspired 9-phase orchestration pipeline for complex reasoning
+- Intelligent query assessment with automatic escalation
+
+**Semantic Memory & Context**
+- Persistent memory with sentence-transformer embeddings
+- Hybrid retrieval (60% activation + 40% semantic similarity)
+- Multi-tier caching for sub-500ms retrieval on 10K+ chunks
+
+**Retrieval Quality Handling**
+- Intelligent detection of no match / weak match / good match scenarios
+- Interactive prompts when retrieval quality is low (give users control)
+- Automatic groundedness scoring (prevents hallucination on weak context)
+- Non-interactive mode for CI/CD and automation (`--non-interactive` flag)
+
+**Decision Matrix**:
+| Scenario | Chunks | Groundedness | Action |
+|----------|--------|--------------|--------|
+| **No match** | 0 | N/A | Auto-proceed with general knowledge |
+| **Weak match** | >0 | <0.7 OR <3 high-quality | Prompt user (interactive) / auto-continue (non-interactive) |
+| **Good match** | >0 | ≥0.7 AND ≥3 high-quality | Auto-proceed with retrieved context |
+
+*See [CLI_USAGE_GUIDE.md](docs/cli/CLI_USAGE_GUIDE.md#retrieval-quality-handling) for detailed examples*
+
+**Agent Orchestration**
+- Discover and coordinate multiple AI agents by capability
+- Parallel and sequential task execution
+- Support for local, remote, and MCP-based agents
+
+**Code Understanding**
+- Tree-sitter powered parsing for Python (extensible to other languages)
+- Intelligent chunking with complexity analysis
+- Dependency tracking and docstring extraction
+
+**Production Ready**
+- Cross-platform support (Windows, macOS, Linux)
+- Cost tracking and budget enforcement
+- Comprehensive error handling with actionable messages
+- Retry logic with exponential backoff
+
+---
+
+## Installation
+
+**From PyPI (Recommended)**
+
+```bash
+# Install with all features
+pip install aurora-actr[all]
+
+# Or minimal installation (no ML dependencies)
+pip install aurora-actr
+
+# Verify installation
+aur --verify
+```
+
+**From Source**
+
+```bash
+git clone https://github.com/aurora-project/aurora.git
+cd aurora
+pip install -e ".[all]"
+```
+
+**Note:** Package is published as `aurora-actr` on PyPI, but import as `from aurora.core import ...`
+
+---
+
+## Quick Start
+
+### MCP Server with Claude Code CLI (Primary Workflow)
+
+AURORA integrates with Claude Code CLI via the Model Context Protocol, enabling you to search and analyze your codebase directly from your development sessions.
+
+#### 1. Install and Initialize AURORA
+
+```bash
+pip install aurora-actr[all]
+cd /path/to/your/project
+aur init
+```
+
+The unified `aur init` command runs 3 steps:
+- **Step 1:** Sets up Git (if needed) and creates project structure
+- **Step 2:** Indexes your codebase for semantic search
+- **Step 3:** Configures AI coding tools (Claude Code, Universal, etc.)
+
+**Note:** No API keys required for initialization. AURORA uses environment variables for standalone CLI commands.
+
+#### 2. Set API Key (For Standalone CLI Only)
+
+MCP tools don't require API keys, but standalone commands do:
+
+```bash
+# Add to ~/.bashrc or ~/.zshrc
+export ANTHROPIC_API_KEY=sk-ant-...
+source ~/.bashrc
+```
+
+#### 3. Use with Claude Code CLI
+
+Restart Claude Code CLI and AURORA's tools are available in your sessions:
+
+- *"Search my codebase for authentication logic"* → `aurora_search`
+- *"Find all usages of the DatabaseConnection class"* → `aurora_search`
+- *"Show me error handling in payment processing"* → `aurora_context`
+- *"What does the UserService module do?"* → `aurora_context`
+- *"Compare our API patterns with best practices"* → `aurora_query` (auto-escalates to SOAR)
+
+Claude Code CLI automatically uses AURORA's tools to search your indexed codebase and provide contextual answers.
+
+**Important:** MCP tools do NOT require API keys. They provide context/search results that Claude Code CLI's built-in LLM processes. No additional API costs beyond your Claude subscription.
+
+**See:** [MCP Setup Guide](docs/MCP_SETUP.md) for detailed configuration and troubleshooting.
+
+---
+
+### Standalone CLI Usage
+
+Use AURORA's CLI directly for queries, memory management, and autonomous reasoning.
+
+**Note:** CLI commands like `aur query` require an `ANTHROPIC_API_KEY` environment variable (they run LLM inference directly). For API-key-free usage, use MCP integration instead.
+
+#### Basic Queries
+
+```bash
+# Simple query (fast direct LLM) - requires API key
+aur query "What is a Python decorator?"
+
+# Complex query (full AURORA pipeline with context) - requires API key
+aur query "How does the authentication system work?"
+
+# Force specific mode - requires API key
+aur query "Explain classes" --force-aurora --verbose
+```
+
+#### Memory Management
+
+```bash
+# Index current directory - no API key required
+aur mem index
+
+# Search indexed code - no API key required
+aur mem search "authentication"
+
+# View statistics - no API key required
+aur mem stats
+
+# Advanced search - no API key required
+aur mem search "database" --limit 10 --show-content --format json
+```
+
+#### Headless Mode (Autonomous Reasoning)
+
+```bash
+# Run autonomous experiment
+aur headless experiment.md
+
+# Custom budget and iterations
+aur headless experiment.md --budget 10.0 --max-iter 20
+
+# Dry run (validation only)
+aur headless experiment.md --dry-run
+```
+
+**Safety features:** Git branch enforcement, budget limits, iteration caps
+
+#### Verification and Diagnostics
+
+```bash
+# Check installation health
+aur --verify
+
+# Check MCP server status
+aurora-mcp status
+
+# View help
+aur --help
+```
+
+**CLI Features:**
+- Automatic escalation (direct LLM vs AURORA pipeline)
+- Hybrid search (activation + semantic)
+- Configuration management (env vars, config files)
+- Rich terminal output with progress bars
+- Installation verification and diagnostics
+
+---
+
+## Usage Examples
+
+### Example 1: Codebase Q&A with Claude Desktop
+
+**Scenario:** You're working on a large codebase and need to quickly understand authentication logic.
+
+1. Initialize AURORA in your project: `aur init`
+2. Open Claude Desktop
+3. Ask: *"Find all authentication-related functions and explain the flow"*
+4. Claude uses AURORA to search, retrieve relevant code, and explain the implementation
+
+**Benefits:** No manual file hunting, contextual understanding, instant answers
+
+### Example 2: Autonomous Code Analysis
+
+**Scenario:** You want to analyze code quality across your project autonomously.
+
+1. Create experiment file: `analyze_code_quality.md`
+2. Run: `aur headless analyze_code_quality.md`
+3. AURORA executes reasoning loop, analyzes code, generates report
+4. Safety controls prevent unwanted changes
+
+**Benefits:** Hands-free analysis, systematic coverage, safety guarantees
+
+### Example 3: Multi-Agent Orchestration
+
+**Scenario:** Complex task requiring multiple AI capabilities (code generation, review, testing).
+
+```python
+from aurora_soar import SOAROrchestrator, AgentRegistry
+from aurora_reasoning import AnthropicClient
+
+# Initialize orchestrator with agent registry
+orchestrator = SOAROrchestrator(
+    store=store,
+    agent_registry=AgentRegistry(),
+    reasoning_llm=AnthropicClient()
+)
+
+# Execute complex query - AURORA decomposes, routes to agents, synthesizes
+result = orchestrator.execute(
+    query="Implement JWT authentication with tests and security review"
+)
+
+print(f"Agents used: {result['metadata']['agents_used']}")
+print(f"Confidence: {result['confidence']:.2f}")
+```
+
+**Benefits:** Coordinated multi-agent execution, automatic routing, cost tracking
+
+---
+
+## Python API
+
+Quick examples for programmatic use:
+
+**Parse and Store Code**
+
+```python
+from aurora_core.store import SQLiteStore
+from aurora_context_code import PythonParser
+
+store = SQLiteStore("aurora.db")
+parser = PythonParser()
+chunks = parser.parse_file("example.py")
+
+for chunk in chunks:
+    store.save_chunk(chunk)
+```
+
+**Context Retrieval with Scoring**
+
+```python
+from aurora_core.context import CodeContextProvider
+
+provider = CodeContextProvider(store, parser_registry)
+results = provider.retrieve("authentication logic", max_results=5)
+
+for chunk in results:
+    print(f"{chunk.metadata['name']} (score: {chunk.metadata['_score']:.2f})")
+```
+
+**SOAR Orchestrator**
+
+```python
+from aurora_soar import SOAROrchestrator
+
+orchestrator = SOAROrchestrator(store, agent_registry, reasoning_llm)
+result = orchestrator.execute(query="Analyze security vulnerabilities")
+```
+
+**Full API documentation:** [API Reference](docs/architecture/API_CONTRACTS_v1.0.md)
+
+---
+
+## Architecture
+
+AURORA is organized as a Python monorepo with modular packages:
+
+**Core Packages:**
+
+- **aurora-core** - Storage, chunks, configuration, context providers, cost tracking
+- **aurora-context-code** - Code parsing (Python via tree-sitter, extensible)
+- **aurora-soar** - Agent registry, 9-phase orchestration pipeline
+- **aurora-reasoning** - LLM integration (Anthropic, OpenAI, Ollama), reasoning logic
+- **aurora-testing** - Testing utilities, fixtures, mocks, benchmarks
+
+**Key Architecture Patterns:**
+
+- **9-Phase SOAR Pipeline:** Assess → Retrieve → Decompose → Verify → Route → Collect → Synthesize → Record → Respond
+- **ACT-R Memory Activation:** Frequency, recency, semantic similarity, context boost
+- **Hybrid Retrieval:** 60% activation scoring + 40% semantic similarity
+- **Multi-Tier Caching:** Hot cache (LRU) + persistent cache + activation scores (10min TTL)
+- **Cost Optimization:** Keyword-based assessment bypasses LLM for 60-70% of simple queries
+
+**Performance:**
+
+- Simple query latency: <2s (achieved: 0.002s)
+- Complex query latency: <10s
+- Memory usage: <100MB for 10K chunks (achieved: 39MB)
+- Retrieval: <500ms for 10K chunks
+
+**Detailed architecture:** [SOAR Architecture](docs/architecture/SOAR_ARCHITECTURE.md), [Verification Checkpoints](docs/reports/quality/VERIFICATION_CHECKPOINTS.md)
+
+---
+
+## Documentation
+
+**Getting Started**
+- [MCP Setup Guide](docs/MCP_SETUP.md) - Claude Desktop integration
+- [Quick Start](docs/cli/QUICK_START.md) - Get started in 5 minutes
+- [CLI Usage Guide](docs/cli/CLI_USAGE_GUIDE.md) - Comprehensive command reference
+- [Troubleshooting Guide](docs/TROUBLESHOOTING.md) - Common issues and solutions
+
+**Architecture & Design**
+- [SOAR Architecture](docs/architecture/SOAR_ARCHITECTURE.md) - 9-phase pipeline details
+- [Verification Checkpoints](docs/reports/quality/VERIFICATION_CHECKPOINTS.md) - Scoring and thresholds
+- [Agent Integration Guide](docs/architecture/AGENT_INTEGRATION.md) - Agent formats and execution
+- [Cost Tracking Guide](docs/guides/COST_TRACKING_GUIDE.md) - Budget management
+- [Prompt Engineering Guide](docs/development/PROMPT_ENGINEERING_GUIDE.md) - Template design
+
+**Development**
+- [Pre-Push Validation](docs/development/PRE_PUSH_VALIDATION.md) - Local CI/CD checks before pushing
+- [API Contracts](docs/architecture/API_CONTRACTS_v1.0.md) - API reference
+- [Migration Guide](docs/development/PHASE4_MIGRATION_GUIDE.md) - Upgrade guide
+- [Code Review Report](docs/reports/quality/CODE_REVIEW_REPORT_v1.0.0-phase3.md) - Quality analysis
+- [Security Audit](docs/reports/security/SECURITY_AUDIT_REPORT_v1.0.0-phase3.md) - Security review
+
+**Project History**
+- [Release Notes](RELEASE_NOTES_v1.0.0-phase3.md) - Version history
+- [Phase Archives](docs/phases/phase3/PHASE3_ARCHIVE_MANIFEST.md) - Development phases
+
+---
+
+## Development
+
+**Setup Development Environment**
+
+```bash
+# Clone and install with dev dependencies
+git clone https://github.com/aurora-project/aurora.git
+cd aurora
+make install-dev
+
+# Run quality checks
+make quality-check
+```
+
+**Common Commands**
+
+```bash
+make test              # Run all tests (1,766+ tests, 97% pass rate)
+make test-unit         # Unit tests only
+make lint              # Ruff linter
+make format            # Format code
+make type-check        # MyPy type checker (100% type safety)
+make benchmark         # Performance benchmarks
+make coverage          # HTML coverage report (81%+ coverage)
+```
+
+**Code Quality Standards**
+
+- **Linting:** Ruff with comprehensive rules
+- **Type Checking:** MyPy strict mode (zero type errors)
+- **Test Coverage:** 81%+ coverage maintained
+- **Security:** Bandit security scanning
+- **Performance:** Benchmarks for critical operations
+
+**Contributing**
+
+Contributions welcome! Please ensure:
+
+1. All tests pass (`make test`)
+2. Code is formatted (`make format`)
+3. Type checking passes (`make type-check`)
+4. New features include tests
+5. Documentation updated
+
+---
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+---
+
+## Contact
+
+For questions, issues, or discussions:
+- **GitHub Issues:** [aurora-project/aurora/issues](https://github.com/aurora-project/aurora/issues)
+- **Discussions:** [aurora-project/aurora/discussions](https://github.com/aurora-project/aurora/discussions)
+
+---
+
+**AURORA** - Intelligent AI systems with persistent memory and cognitive reasoning

aurora_actr-0.3.1.dist-info/RECORD

@@ -0,0 +1,24 @@
+aurora/__init__.py,sha256=iIXCyE3IT7Yb6Jtw4x-_LCN2HHE865LBsu4_0wRrdCY,362
+aurora/cli/__init__.py,sha256=L8lJ1sJsPVTuWGN4LmNVeVlzt0VVcVcVsXKASVaqHXA,1345
+aurora/cli/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+aurora/context_code/__init__.py,sha256=Avco79Ql15oDXM6qVpuL--4aPwOzXJaiOWwLswmgjfk,1436
+aurora/context_code/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+aurora/core/__init__.py,sha256=V3GSOUKVG-Ndvh7L5OriwhUFSGEsUIYw2ZHZO9PsXsA,1572
+aurora/core/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+aurora/mcp/__init__.py,sha256=mi0CFxdxMF0H8F9f2JAoEWKhnSTwbewz3z1xVkDzNlU,246
+aurora/mcp/config.py,sha256=xp7AJYgEuIWeNDFTdlBrGIh9XwVQAN7e0QsnF4aJtnk,3133
+aurora/mcp/server.py,sha256=OZcjjIyEpbKXG-h2pC4VhX43tohkdlsH3FLY442Gh7E,14292
+aurora/mcp/tools.py,sha256=EIV_UaPhMEkMibQkwlEb_5n_hMoDPqNq-wnUv7bKMdA,45004
+aurora/reasoning/__init__.py,sha256=zkWd0CPUzLu4i-BEqe1rPLA7xtpLpGI3c_g88WOkGoU,1412
+aurora/reasoning/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+aurora/scripts/__init__.py,sha256=esVwOJ8SzCztBsvHIyzyHCUXNxQQRhd8F-8Yefg1P8s,30
+aurora/scripts/uninstall.py,sha256=uHOQePZ0zoGDJIPSREusMzcP7vBGIDix1MPI8FWXee8,3026
+aurora/soar/__init__.py,sha256=wbIjqeVDbZ-LCvONPoQRz_LXFpaPUacpFnQkHZlDbxo,1359
+aurora/soar/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+aurora/testing/__init__.py,sha256=_V-zLhCIVzDaMPGDu5kxKoyV1wCqLc14Ty944GFL70g,1351
+aurora/testing/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+aurora_actr-0.3.1.dist-info/METADATA,sha256=upDwtNtnYP96771A3NuE8fLQ2cVsQgGxmtk4wBWAUFo,16169
+aurora_actr-0.3.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+aurora_actr-0.3.1.dist-info/entry_points.txt,sha256=6DE9XYGxdB0F_bPtpOaihmzzbW1adfEzdaiMWyUMUoE,129
+aurora_actr-0.3.1.dist-info/top_level.txt,sha256=_VPZyby2U0daT4zxBQyOTduleUKBlGa_eQkjEGBjNyE,7
+aurora_actr-0.3.1.dist-info/RECORD,,

aurora_actr-0.3.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

aurora_actr-0.3.1.dist-info/entry_points.txt

@@ -0,0 +1,4 @@
+[console_scripts]
+aur = aurora_cli.main:cli
+aurora-mcp = aurora.mcp.server:main
+aurora-uninstall = aurora.scripts.uninstall:main

aurora_actr-0.3.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+aurora