Metadata-Version: 2.4
Name: ain-research-engine
Version: 0.4.0
Summary: Autonomous Intelligence Network - Research & Knowledge Compilation Engine. Ingests scientific literature from ArXiv, OpenAlex, and Crossref with automatic source routing.
Project-URL: Homepage, https://pypi.org/project/ain-research/
Project-URL: Repository, https://pypi.org/project/ain-research/
Author-email: Sambit Mishra <sambit1912@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: ai,arxiv,autonomous,crossref,knowledge-management,llm,machine-learning,mcp,openalex,research,scientific-papers
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.10
Requires-Dist: duckduckgo-search>=7.0.0
Requires-Dist: fastapi
Requires-Dist: firebase-admin>=6.0.0
Requires-Dist: markdown
Requires-Dist: mcp>=1.2.0
Requires-Dist: networkx
Requires-Dist: numba
Requires-Dist: pygments
Requires-Dist: pyvis
Requires-Dist: requests
Requires-Dist: scikit-learn
Requires-Dist: sentence-transformers
Requires-Dist: torch
Requires-Dist: uvicorn
Provides-Extra: test
Requires-Dist: mypy>=1.0; extra == 'test'
Requires-Dist: pytest>=7.0; extra == 'test'
Requires-Dist: ruff>=0.4.0; extra == 'test'
Description-Content-Type: text/markdown

# ain-research

<p align="center">
  <strong>Autonomous Intelligence Network — Research & Knowledge Compilation Engine</strong>
</p>

<p align="center">
  <a href="https://pypi.org/project/ain-research/"><img src="https://img.shields.io/pypi/v/ain-research.svg" alt="PyPI"></a>
  <a href="https://pypi.org/project/ain-research/"><img src="https://img.shields.io/pypi/pyversions/ain-research.svg" alt="Python"></a>
  <a href="https://github.com/That-Tech-Geek/ain-research/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License"></a>
</p>

---

`ain-research` is the core orchestration engine powering the **Autonomous Intelligence Network (AIN)** — a self-organizing research system that autonomously ingests scientific literature, detects contradictions between knowledge nodes, and evolves credibility scores for every research concept it tracks.

Built on top of LLMs, it guides, automates, and orchestrates open-ended domain research across **115+ arXiv categories** spanning Physics, Mathematics, Computer Science, Statistics, Quantitative Biology, Quantitative Finance, Economics, and Electrical Engineering.

---

## Features

| Feature | Description |
|---------|-------------|
| **Infinite Research Daemon** | Time-boxed, autonomous daemon that fetches domain-specific research with intelligent rate-limiting |
| **115+ arXiv Topics** | Pre-configured categories across 9 scientific domains with fuzzy search |
| **Firebase Authentication** | Role-based access control with library field permissions |
| **LLM Steering** | MCP server for dynamic research queue management |
| **Atomic Concurrency** | OS-level FileLocks for zero data corruption during concurrent access |
| **Vault Viewer** | Minimalist SPA for browsing your knowledge base |
| **MCP Integration** | Direct integration with Claude, Cursor, and other MCP-compatible clients |

---

## Installation

### Recommended: uv

```bash
uv tool install ain-research
```

This installs the `ain`, `ain-research`, and `ain-mcp` commands globally.

### Alternative: pip

```bash
pip install ain-research
```

> **Note**: Ensure your Python Scripts folder is in your system PATH to use the `ain` command.

### Development Install

```bash
git clone https://github.com/That-Tech-Geek/ain-research.git
cd ain-research
pip install -e .
```

---

## Quick Start

### 1. Configure Workspace

By default, ain-research uses `~/.ain/` as the workspace root. Override with:

```bash
export AIN_WORKSPACE=/path/to/custom/workspace
```

### 2. Setup Firebase Authentication (Optional)

```bash
ain auth setup --cred-file /path/to/firebase-adminsdk.json
```

### 3. Check User Access

```bash
ain auth check --email user@example.com
```

### 4. Set Crawl Schedule

```bash
ain schedule --start "09:00" --end "21:00"
```

### 5. List Available Topics

```bash
ain topics              # List all 115+ topics
ain topics --count      # Show domain breakdown
ain search "quantum"    # Fuzzy search topics
```

### 6. Start the Daemon

```bash
ain-research            # Start the ingestion daemon
ain-research --force    # Run outside active time window
```

### 7. Add to Queue

```bash
ain queue add --arxiv 2305.14314    # Queue specific paper
ain queue list                      # View pending items
```

### 8. Compile the Vault

```bash
ain compile
```

### 9. Launch the UI

```bash
ain ui --port 8000
```

---

## CLI Reference

### Core Commands

| Command | Description | Example |
|---------|-------------|---------|
| `ain compile` | Compile the Vault Index and Tags | `ain compile` |
| `ain queue add` | Add paper to ingestion queue | `ain queue add --arxiv 2305.14314` |
| `ain queue list` | List pending queue items | `ain queue list` |
| `ain intent` | Decompose research goal into topics | `ain intent "agentic frameworks"` |
| `ain schedule` | Set daily crawl schedule | `ain schedule --start "09:00" --end "21:00"` |
| `ain ui` | Launch Vault Viewer | `ain ui --port 8000` |
| `ain setup-agents` | Setup MCP config for Claude/Cursor | `ain setup-agents` |

### Topic Management

| Command | Description | Example |
|---------|-------------|---------|
| `ain topics` | List all arXiv topics | `ain topics` |
| `ain topics --count` | Show topic count by domain | `ain topics --count` |
| `ain search` | Fuzzy search topics | `ain search "neural"` |
| `ain theme list` | List active themes | `ain theme list` |
| `ain theme add` | Add custom theme | `ain theme add --name "MyTheme" --query "cat:cs.AI" --tags "ai,ml"` |
| `ain theme remove` | Remove theme | `ain theme remove --name "MyTheme"` |

### Authentication

| Command | Description | Example |
|---------|-------------|---------|
| `ain auth check` | Check user library access | `ain auth check --email user@example.com` |
| `ain auth setup` | Setup Firebase credentials | `ain auth setup --cred-file path/to/sdk.json` |

### Notifications

| Command | Description | Example |
|---------|-------------|---------|
| `ain telegram setup` | Setup Telegram notifications | `ain telegram setup --token BOT_TOKEN` |

---

## Python API

### Authentication

```python
from ain_research.auth import check_library_access, require_library_access, authenticate_user

# Check access
result = check_library_access("user@example.com")
if result["allowed"]:
    print("Access granted")

# Boolean check
if authenticate_user("user@example.com"):
    proceed()

# Decorator
@require_library_access
def my_function(email):
    # Only runs if user has library=True
    pass
```

### Topic Search

```python
from ain_research.config import fuzzy_search_topics, get_topic_list

# Fuzzy search
results = fuzzy_search_topics("quantum", threshold=0.3)
for name, score, data in results:
    print(f"{name}: {score:.0%} - {data['query']}")

# Get all topics
topics = get_topic_list()
```

### Configuration

```python
from ain_research.config import (
    get_arxiv_categories,
    save_arxiv_categories,
    get_schedule,
    save_schedule
)

# Get all categories
categories = get_arxiv_categories()

# Add custom category
categories["MyTopic"] = {
    "query": "cat:cs.AI",
    "tags": ["ai", "custom"]
}
save_arxiv_categories(categories)

# Update schedule
save_schedule("09:00", "21:00")
```

---

## MCP Integration

### Claude Desktop / Cursor

Add to your MCP configuration:

```json
{
  "mcpServers": {
    "ain-research": {
      "command": "uv",
      "args": ["run", "ain-mcp"]
    }
  }
}
```

### Available MCP Tools

| Tool | Description |
|------|-------------|
| `queue_arxiv(arxiv_id)` | Queue a specific ArXiv paper |
| `get_queue_status()` | Get current ingestion queue status |
| `trigger_compile()` | Re-compile the Vault Index |
| `add_arxiv_category(name, query, tags)` | Add new research trajectory |

---

## Workspace Structure

```
~/.ain/
├── arxiv_categories.json      # Topic configuration
├── schedule_config.json       # Crawl schedule
├── telegram_config.json       # Telegram notifications
├── firebase-adminsdk.json     # Firebase credentials
├── daemon_state.json          # Daemon state
├── data/                      # SQLite database
└── vault/
    └── wiki/
        ├── 01_Inbox/
        ├── 02_Physics/
        ├── 03_Mathematics/
        ├── 04_Computer_Science/
        ├── 05_Statistics/
        ├── 06_Quantitative_Biology/
        ├── 07_Quantitative_Finance/
        ├── 08_Economics/
        ├── 09_Electrical_Engineering/
        └── 10_Publications/
```

---

## Supported Topics (115+)

### Physics (17)
`physics.gen-ph`, `physics.atom-ph`, `physics.chem-ph`, `physics.bio-ph`, `physics.comp-ph`, `physics.data-an`, `physics.flu-dyn`, `physics.geo-ph`, `physics.optics`, `physics.plasma-ph`, `physics.space-ph`, `physics.med-ph`, `physics.hist-ph`, `physics.ed-ph`, `physics.soc-ph`, `physics.ins-det`, `quant-ph`

### Mathematics (28)
`math.AG`, `math.AT`, `math.CA`, `math.CO`, `math.CT`, `math.DG`, `math.DS`, `math.FA`, `math.GM`, `math.GN`, `math.GR`, `math.HO`, `math.IT`, `math.KT`, `math.LO`, `math.MG`, `math.MP`, `math.NA`, `math.NT`, `math.OA`, `math.OC`, `math.PR`, `math.QA`, `math.RA`, `math.RT`, `math.SG`, `math.SP`, `math.ST`

### Computer Science (40)
`cs.AI`, `cs.AR`, `cs.CC`, `cs.CE`, `cs.CG`, `cs.CL`, `cs.CR`, `cs.CV`, `cs.CY`, `cs.DB`, `cs.DC`, `cs.DL`, `cs.DM`, `cs.DS`, `cs.ET`, `cs.FL`, `cs.GL`, `cs.GR`, `cs.GT`, `cs.HC`, `cs.IR`, `cs.IT`, `cs.LG`, `cs.LO`, `cs.MA`, `cs.MM`, `cs.MS`, `cs.NA`, `cs.NE`, `cs.NI`, `cs.OH`, `cs.OS`, `cs.PF`, `cs.PL`, `cs.RO`, `cs.SC`, `cs.SD`, `cs.SE`, `cs.SI`, `cs.SY`

### Statistics (6)
`stat.AP`, `stat.CO`, `stat.ME`, `stat.ML`, `stat.OT`, `stat.TH`

### Quantitative Biology (9)
`q-bio.BM`, `q-bio.CB`, `q-bio.GN`, `q-bio.MN`, `q-bio.NC`, `q-bio.OT`, `q-bio.PE`, `q-bio.QM`, `q-bio.TO`

### Quantitative Finance (9)
`q-fin.CP`, `q-fin.EC`, `q-fin.GN`, `q-fin.MF`, `q-fin.PM`, `q-fin.PR`, `q-fin.RM`, `q-fin.ST`, `q-fin.TR`

### Economics (2)
`econ.GN`, `econ.TH`

### Electrical Engineering (4)
`eess.AS`, `eess.IV`, `eess.SP`, `eess.SY`

---

## Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `AIN_WORKSPACE` | `~/.ain/` | Workspace root directory |
| `FIREBASE_CRED_PATH` | `~/.ain/firebase-adminsdk.json` | Firebase credentials path |
| `CRAWL_START_TIME` | `09:00` | Daemon start time |
| `CRAWL_END_TIME` | `21:00` | Daemon end time |

---

## License

MIT License - see [LICENSE](LICENSE)

---

## Author

**That-Tech-Geek** / **Sambit Mishra**

- GitHub: [@That-Tech-Geek](https://github.com/That-Tech-Geek)
- Email: sambit1912@gmail.com

---

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

---

## Support

If you find this project useful, please consider giving it a star on GitHub.
