Metadata-Version: 2.4
Name: insightflow
Version: 0.1.1
Summary: A research automation tool that searches and analyzes web content, papers, blogs, and social media to generate comprehensive reports for given queries
Project-URL: Homepage, https://github.com/sync-dev-org/insightflow
Project-URL: Repository, https://github.com/sync-dev-org/insightflow
Project-URL: Issues, https://github.com/sync-dev-org/insightflow/issues
Project-URL: Documentation, https://github.com/sync-dev-org/insightflow#readme
Author-email: minamikik <mia@sync.dev>
Maintainer-email: minamikik <mia@sync.dev>
License: MIT
License-File: LICENSE
Keywords: ai,analysis,automation,llm,report-generation,research
Classifier: Development Status :: 3 - Alpha
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.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: <3.14,>=3.12
Requires-Dist: pydantic-ai-slim[openrouter]>=1.0
Requires-Dist: pydantic-settings>=2.0
Requires-Dist: pydantic>=2.0
Provides-Extra: all
Requires-Dist: fastapi>=0.115; extra == 'all'
Requires-Dist: jinja2>=3.1; extra == 'all'
Requires-Dist: mcp>=1.0.0; extra == 'all'
Requires-Dist: python-dotenv>=1.0.0; extra == 'all'
Requires-Dist: typer>=0.12; extra == 'all'
Requires-Dist: uvicorn>=0.32; extra == 'all'
Provides-Extra: api
Requires-Dist: fastapi>=0.115; extra == 'api'
Requires-Dist: jinja2>=3.1; extra == 'api'
Requires-Dist: uvicorn>=0.32; extra == 'api'
Provides-Extra: cli
Requires-Dist: typer>=0.12; extra == 'cli'
Provides-Extra: mcp
Requires-Dist: mcp>=1.0.0; extra == 'mcp'
Requires-Dist: python-dotenv>=1.0.0; extra == 'mcp'
Description-Content-Type: text/markdown

# insightflow

[![PyPI version](https://img.shields.io/pypi/v/insightflow)](https://pypi.org/project/insightflow/)
[![Python 3.12+](https://img.shields.io/pypi/pyversions/insightflow)](https://pypi.org/project/insightflow/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

[Japanese / 日本語](README.ja.md)

Automated research tool that searches and analyzes web content, papers, blogs, and social media to generate comprehensive reports for any query.

Leverages multiple LLM providers (OpenAI, Google, Perplexity, xAI) via [OpenRouter](https://openrouter.ai/) to automate multi-perspective research on any topic.

## How It Works

```
Topic
  |
[1] Aspect Extraction (openai/gpt-4.1-mini)
  |
  +-- Aspect A --> [2] Parallel Web Search (perplexity/sonar-reasoning-pro) --> Report A
  +-- Aspect B --> [2] Parallel Web Search                                  --> Report B
  +-- Aspect C --> [2] Parallel Web Search                                  --> Report C
                                                                                 |
                                                            [3] Report Synthesis (google/gemini-3-flash-preview)
                                                                                 |
                                                                    Final Report (Markdown + Citations)
```

1. **Aspect Extraction** - Identifies key perspectives of the topic using an LLM
2. **Parallel Search** - Searches each aspect concurrently via web-connected models
3. **Report Synthesis** - Merges all findings into a single, cited Markdown report

## Prerequisites

- Python 3.12+
- [OpenRouter](https://openrouter.ai/) API key

## Installation

```bash
pip install insightflow
```

### Extras

| Extra | Description | Command |
|-------|-------------|---------|
| `cli` | CLI interface (Typer) | `pip install "insightflow[cli]"` |
| `api` | REST API server (FastAPI) | `pip install "insightflow[api]"` |
| `mcp` | MCP server (Claude Code, etc.) | `pip install "insightflow[mcp]"` |
| `all` | All extras | `pip install "insightflow[all]"` |

## Setup

Set your OpenRouter API key as an environment variable:

```bash
export OPENROUTER_API_KEY="sk-or-v1-..."
```

Or create a `.env` file in your project root:

```bash
OPENROUTER_API_KEY=sk-or-v1-...
```

## Usage

### Python Library

```python
import asyncio
from insightflow.core import research
from insightflow.models import LLMConfig

report = asyncio.run(research(
    topic="Recent trends in quantum computing",
    aspect_model=LLMConfig(model="openai/gpt-4.1-mini"),
    search_model=LLMConfig(model="perplexity/sonar-reasoning-pro"),
    report_model=LLMConfig(model="google/gemini-3-flash-preview"),
))

print(report.content)       # Markdown report
print(report.citations)     # List of citations
print(report.metadata)      # Elapsed time, model used, etc.
```

Individual functions are also available:

```python
from insightflow.core import extract_aspects, search, compose
from insightflow.models import LLMConfig

# Aspect extraction only
aspects = asyncio.run(extract_aspects(
    topic="ML optimization techniques",
    config=LLMConfig(model="openai/gpt-4.1-mini"),
))

# Single search query
result = asyncio.run(search(
    query="Python packaging best practices",
    config=LLMConfig(model="perplexity/sonar-reasoning-pro"),
))
```

### CLI

```bash
pip install "insightflow[cli]"

# Full research
insightflow research "Recent trends in quantum computing"

# Aspect extraction only
insightflow aspects "ML optimization techniques"

# Single search
insightflow search "Python packaging best practices"

# With options
insightflow research "AI safety" \
  --language english \
  --max-aspects 3 \
  --search-model perplexity/sonar-pro \
  --json \
  -o report.json
```

Run `insightflow --help` for all available options.

### REST API Server

```bash
pip install "insightflow[api]"
python -m uvicorn insightflow.interfaces.api:app
```

Swagger UI is available at `http://localhost:8000/docs`.

```bash
curl -X POST http://localhost:8000/research \
  -H "Content-Type: application/json" \
  -d '{"topic": "quantum computing", "language": "english"}'
```

### MCP Server (Claude Code Integration)

Use insightflow as an MCP tool in Claude Code so that Claude can autonomously run research.

**1. Install**

```bash
pip install "insightflow[mcp]"
```

**2. Add to Claude Code config**

Add to `~/.claude.json` (global) or `.mcp.json` in your project root:

```json
{
  "mcpServers": {
    "insightflow": {
      "command": "python",
      "args": ["-m", "insightflow.interfaces.mcp"],
      "env": {
        "OPENROUTER_API_KEY": "sk-or-v1-..."
      }
    }
  }
}
```

> With uvx (no local install required):
> ```json
> {
>   "mcpServers": {
>     "insightflow": {
>       "command": "uvx",
>       "args": ["--from", "insightflow[mcp]", "python", "-m", "insightflow.interfaces.mcp"],
>       "env": {
>         "OPENROUTER_API_KEY": "sk-or-v1-..."
>       }
>     }
>   }
> }
> ```

**3. Use from Claude Code**

Once configured, Claude Code recognizes the `research` tool. Ask Claude to research a topic in conversation and it will call insightflow automatically.

Tool parameters:

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `topic` | string | Yes | - | Research topic |
| `aspect_model` | string | No | `openai/gpt-4.1-mini` | Model for aspect extraction |
| `search_model` | string | No | `perplexity/sonar-reasoning-pro` | Model for search |
| `report_model` | string | No | `google/gemini-3-flash-preview` | Model for report generation |
| `language` | string | No | `japanese` | Output language |
| `max_aspects` | integer | No | `5` | Maximum number of aspects |
| `concurrency` | integer | No | `3` | Maximum concurrent searches |

## Configuration

Configurable via environment variables or `.env` file:

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `OPENROUTER_API_KEY` | Yes | - | OpenRouter API key |
| `DEFAULT_ASPECT_MODEL` | No | `openai/gpt-4.1-mini` | Default aspect extraction model |
| `DEFAULT_SEARCH_MODEL` | No | `perplexity/sonar-reasoning-pro` | Default search model |
| `DEFAULT_REPORT_MODEL` | No | `google/gemini-3-flash-preview` | Default report generation model |
| `DEFAULT_LANGUAGE` | No | `japanese` | Default output language |
| `DEFAULT_MAX_ASPECTS` | No | `5` | Default number of aspects |
| `DEFAULT_CONCURRENCY` | No | `3` | Default concurrent searches |

## Development

```bash
git clone https://github.com/sync-dev-org/insightflow.git
cd insightflow
uv sync --all-extras

# Test
uv run pytest

# Lint
uv run ruff check src/
uv run ruff format src/
```

## License

MIT License - See [LICENSE](LICENSE) for details.
