# AI Research Intelligence — API Integration Guide
======================================================
Base URL: http://localhost:8002
Swagger UI: http://localhost:8002/docs
OpenAPI JSON: http://localhost:8002/openapi.json
Capabilities: http://localhost:8002/api/v1/agent/capabilities

============================
SECTION 1: FOR AI CODERS
(Cursor, GitHub Copilot, Gemini Code)
============================

When asking an AI assistant to write data pipelines or crawlers that feed this platform,
use the following snippet as context in your system prompt:

## Required Ingestion Schema
```json
{
  "title": "Paper or Article Title",
  "url": "https://source.com/item",
  "abstract": "Brief summary of the content",
  "source_name": "arXiv",
  "content_type": "research_paper",
  "categories": ["llm", "agents", "reasoning"],
  "published_date": "2025-07-01"
}
```

## Submitting Data (Python)
```python
import httpx

payload = {
    "title": "Scaling Reasoning with MCTS",
    "url": "https://arxiv.org/abs/2407.xxxxx",
    "abstract": "We propose a novel approach...",
    "source_name": "arXiv",
    "categories": ["llm", "reasoning"]
}
resp = httpx.post("http://localhost:8002/api/v1/agent/ingest", json=payload)
print(resp.json())
```

## Querying the Analyst (Python)
```python
resp = httpx.post("http://localhost:8002/api/v1/agent/query",
                  json={"question": "What are the latest LLM reasoning advances?", "context_hours": 168})
print(resp.json()["answer"])
```

============================
SECTION 2: FOR AGENT DEVELOPERS
(LangChain, CrewAI, OpenAI Agents, AutoGPT)
============================

## Step 1 — Discover Capabilities on Startup
Run this at agent boot to auto-configure which categories and content types are accepted:
```
GET http://localhost:8002/api/v1/agent/capabilities
```

## Step 2 — Define Tools (LangChain Example)
```python
from langchain.tools import tool
import httpx

BASE = "http://localhost:8002"

@tool
def ingest_research(title: str, url: str, abstract: str, source: str) -> dict:
    """Push a new research finding into the AI Research Intelligence Platform."""
    return httpx.post(f"{BASE}/api/v1/agent/ingest",
                      json={"title": title, "url": url, "abstract": abstract, "source_name": source}).json()

@tool
def query_analyst(question: str) -> str:
    """Ask natural-language questions about AI research. Returns cited, structured answers."""
    return httpx.post(f"{BASE}/api/v1/agent/query",
                      json={"question": question, "context_hours": 168}).json().get("answer")

@tool
def get_active_sources() -> list:
    """Get the current list of active crawling sources."""
    return httpx.get(f"{BASE}/api/v1/agent/sources/active").json()
```

## Step 3 — Subscribe to Webhooks (Real-time Updates)
```python
httpx.post(f"{BASE}/api/v1/agent/webhook/subscribe", json={
    "callback_url": "https://your-agent.example.com/hook",
    "events": ["new_item", "high_priority", "emerging_trend"]
})
```

============================
SECTION 3: COMPLETE API REFERENCE
============================

### Agent APIs
| Method | Endpoint                        | Description                      |
|--------|---------------------------------|----------------------------------|
| GET    | /api/v1/agent/capabilities      | Platform capabilities manifest   |
| POST   | /api/v1/agent/ingest            | Ingest a research item           |
| POST   | /api/v1/agent/ingest/batch      | Bulk ingest up to 100 items      |
| POST   | /api/v1/agent/query             | RAG analyst natural language Q&A |
| GET    | /api/v1/agent/sources/active    | Active source list for crawlers  |
| POST   | /api/v1/agent/webhook/subscribe | Subscribe to real-time events    |
| GET    | /api/v1/agent/webhook           | List your subscriptions          |

### Sources APIs
| Method | Endpoint                                  | Description             |
|--------|-------------------------------------------|-------------------------|
| GET    | /api/v1/sources                           | List all sources        |
| POST   | /api/v1/sources                           | Add a new source        |
| GET    | /api/v1/sources/{id}                      | Get source by ID        |
| PATCH  | /api/v1/sources/{id}                      | Update source fields    |
| DELETE | /api/v1/sources/{id}                      | Remove a source         |
| POST   | /api/v1/sources/{id}/activate             | Enable a source         |
| POST   | /api/v1/sources/{id}/deactivate           | Disable a source        |

### Research APIs
| Method | Endpoint                        | Description                      |
|--------|---------------------------------|----------------------------------|
| GET    | /api/v1/research/items          | List all research items          |
| GET    | /api/v1/research/trends         | Trend detection results          |
| GET    | /api/v1/research/sources        | Research source metadata         |

============================
SECTION 4: EXAMPLE AGENT WORKFLOW
============================

1. Agent boots → calls GET /api/v1/agent/capabilities
2. Crawler scrapes arXiv → calls POST /api/v1/agent/ingest for each paper
3. Agent calls GET /api/v1/research/trends to detect emerging topics
4. Agent calls POST /api/v1/agent/query with business question
5. Webhook fires when high-priority item detected → agent takes action