Metadata-Version: 2.4
Name: ain-research
Version: 1.2.0
Summary: AIN Infinite Research System - Multi-Agent Automated Science DAEMON. Engineered to sit on top of LLMs to autonomously guide research, provide storage, and retrieval functionality. Evolving into a 10x autonomous ecosystem.
Author: That-Tech-Geek
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.9
Requires-Dist: mcp>=1.2.0
Requires-Dist: networkx
Requires-Dist: numba
Requires-Dist: pyvis
Requires-Dist: requests
Requires-Dist: scikit-learn
Requires-Dist: sentence-transformers
Description-Content-Type: text/markdown

# AIN Research Daemon Library

Welcome to the **AIN Infinite Research Daemon** (`ain-research`), an open-source Python library built by **That-Tech-Geek**. This library provides the core infrastructure for an Autonomous Intelligence Network (AIN), sitting seamlessly on top of LLMs to guide, automate, and orchestrate open-ended domain research.

## What is it?

`ain-research` is a sophisticated pipeline for automated research ingestion, storage, and retrieval. It allows LLMs and autonomous agents to asynchronously fetch papers from ArXiv, crawl open-source repositories from GitHub, and store them securely into a local SQLite queue before finally syncing them into a hyper-fast, modular knowledge base (the Vault).

Key capabilities include:
- **Infinite Research Daemon**: Time-boxed, autonomous daemon that fetches domain-specific research using intelligent rate-limiting and rotating APIs.
- **LLM Steering Integration**: It is engineered to sit on top of LLMs. You can use the CLI or built-in **MCP Server** to dynamically add new search queries, refine categorizations, and prioritize processing.
- **Atomic Concurrency Control**: Uses OS-level kernel FileLocks to ensure zero data corruption during heavy concurrent reading/writing by different agents.
- **Model Context Protocol (MCP)**: Directly expose your AIN Second Brain to any MCP-compatible LLM client (like Claude Desktop or other agents), allowing them to queue research, check system health, and compile the wiki on demand.

## Use Cases

1. **Automated Overnight Crawling**
   Let the daemon run overnight (`ain-daemon`). It crawls ArXiv and GitHub based on your configured categories (e.g., Quant Finance, LLMs) and stores the results securely. By the time you wake up, your Vault is packed with fresh, tagged Markdown files.
   
2. **LLM-Guided Research**
   If you have a primary agent researching "Agentic Frameworks", the agent can use the MCP server (`ain-mcp`) to dynamically add "Agentic Frameworks" to the daytime priority ingestion queue. The daemon will immediately fetch relevant papers and repos, syncing them into the Vault for the LLM to read.

3. **Hyper-fast Retrieval**
   The core indexing engine (`ain compile`) resolves thousands of nodes into lightweight Maps of Content (MOCs) and exact tag inversions, enabling LLMs to quickly query specific subjects without context-window bloat.

## Installation

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

## Quick Start

### 1. Configure Workspace
By default, the package uses `~/.ain/` as the root workspace. You can override this using the `AIN_WORKSPACE` environment variable.

### 2. Start the Daemon
```bash
ain-daemon
```
*Runs the overnight crawler. By default, it operates actively between 22:00 and 23:59.*

### 3. Add to Queue via CLI
```bash
ain queue add --arxiv 2305.14314
```

### 4. Configure Themes & Schedule
```bash
ain theme add --name "Quant" --query "cat:q-fin.*" --tags "finance"
ain schedule --start "22:00" --end "23:59:59"
```

### 5. Compile the Knowledge Base
```bash
ain compile
```
*Generates the Maps of Content (MOCs), Mermaid network graphs, and visualizer data.*

### 6. Launch MCP Server
To allow LLMs to natively hook into the daemon's research capabilities:
```bash
ain-mcp
```
*(Configure this in your LLM client's MCP configuration settings).*

## Author
**That-Tech-Geek**

## 10x Evolution Features (v0.2.0+)

`ain-research` has evolved from an assistive background utility into an autonomous, 10x-scale ecosystem. It incorporates several advanced systems:

### 1. Self-Verifying Logic Engine
It actively fights hallucinations using a highly deterministic logic system. 
- **Cross-Examination**: It flags anomalies and invalid assumptions by cross-referencing contradictory data points.
- **Logic Proofs**: Evaluates findings with mathematical and architectural correctness, minimizing the need for human debugging.

### 2. Multi-Agent Swarm Orchestration
Instead of running as a single synchronous loop, it now operates as a background multi-agent network.
- **Division of Labor**: Specialized agents concurrently verify, structure, and peer-review incoming research data.
- **Continuous Execution**: The swarm processes queue items in real-time alongside the daemon's regular horizon scanning.

### 3. Zero-Friction Abstract Interface (`ain intent`)
You can bypass manual tool configurations by simply passing high-level intents.
- Command: `ain intent "Explore sparse autoencoders in LLMs"`
- The system automatically leverages the LLM client to decompose this intent into discrete tasks, builds the search queries, and delegates them to the swarm.

### 4. Traceable Truth Layer
Decisions are no longer a "black box".
- Deterministic trace logs are saved into `truth_logs/`.
- Every LLM judgement, verification step, and data modification is recorded to provide full auditability, turning untrusted guessing into enterprise-grade intelligence.



# AIN Infinite Research CLI Documentation

The AIN Research Engine provides a powerful Command Line Interface (CLI) for managing the knowledge vault, ingestion queues, autonomous intent decomposition, and agent integrations.

This document details the available commands and their usage.

---

## 1. `ain compile`

**Description:**
Compiles the Vault Index and processes tags across all Markdown files in the local AIN vault. It synchronizes and recalibrates the visualizer data, ensuring that the 3D Neural Network Visualizer and the central `INDEX.md` reflect the most recent insights.

**Usage:**
```bash
ain compile
```

---

## 2. `ain queue`

**Description:**
Manages the ingestion queue for academic papers and external data sources. The queue supports automated processing, retries, and tracking.

### `ain queue add`
Adds a specific ArXiv paper to the ingestion queue by its ID.

**Usage:**
```bash
ain queue add --arxiv <arxiv_id>
```
*Example:* `ain queue add --arxiv 2307.09288`

### `ain queue list`
Lists up to 50 pending items in the ingestion queue, displaying their item type, identifier, and current retry count.

**Usage:**
```bash
ain queue list
```

---

## 3. `ain theme`

**Description:**
Manages the active research themes and categories stored in the system. The daemon monitors these topics/themes for incoming literature on ArXiv.

### `ain theme list`
Lists all currently active themes, their corresponding ArXiv queries, and tags.

**Usage:**
```bash
ain theme list
```

### `ain theme add`
Adds a new research theme to the system.

**Usage:**
```bash
ain theme add --name "<theme_name>" --query "<arxiv_query>" [--tags "<tag1,tag2>"]
```
*Example:* `ain theme add --name "LLM Agents" --query "cat:cs.AI AND all:agent" --tags "ai,agents"`

### `ain theme remove`
Removes a specific research theme by its name.

**Usage:**
```bash
ain theme remove --name "<theme_name>"
```
*Example:* `ain theme remove --name "LLM Agents"`

---

## 4. `ain schedule`

**Description:**
Sets the daily time window during which the AIN Research daemon is allowed to autonomously crawl ArXiv and other data sources for the active themes.

**Usage:**
```bash
ain schedule --start "<start_time>" --end "<end_time>"
```
*Example:* `ain schedule --start "22:00" --end "23:59:59"`

---

## 5. `ain intent`

**Description:**
Leverages the local LLM to autonomously decompose a broad research goal into specific, highly-targeted search topics (3 topics by default). It automatically queues these topics for ongoing ArXiv monitoring and processing.

**Usage:**
```bash
ain intent "<research_goal>"
```
*Example:* `ain intent "Find state-of-the-art methods for algorithmic market making using reinforcement learning"`

---

## 6. `ain ui`

**Description:**
Launches the local Truth UI web server to visualize the vault connections (ArXiv Scraps -> First Principles) and interact with the AIN Research Engine graphically.

**Usage:**
```bash
ain ui [--port <port_number>]
```
*Example:* `ain ui` (defaults to port 8000)
*Example:* `ain ui --port 8080`

---

## 7. `ain setup-agents`

**Description:**
Bootstraps the integration between the AIN Research Engine and external AI agents (like Claude Code, Cursor, or Codex) via the Model Context Protocol (MCP).

**What it does:**
1. **Creates `AGENTS.md`**: Generates a standard instruction protocol file that guides agents on how to use the AIN MCP server (queue management, compilation triggers, intent decomposition).
2. **Cursor/Codex Configuration**: Sets up `.cursor/mcp.json` to register the `ain-mcp` command as an active MCP server for the IDE.
3. **Claude Code Configuration**: Generates a `claude.json` configuration file enabling Claude to interface directly with the daemon.

**Usage:**
```bash
ain setup-agents
```
