igpt-email-ask

通过 iGPT 上下文引擎 API 进行安全、每个用户隔离的电子邮件推理和分析。 总结线索、提取任务和决策、检测情绪和多个原因 对话——无 shell 访问、无文件系统访问、仅限 API 密钥范围。支持结构化 具有架构验证和流式传输 (SSE) 的 JSON 输出。当用户需要分析时使用， 摘要、结构化数据提取或需要了解电子邮件上下文的答案。 仅对于检索/查找，请使用配套技能 igpt-email-search。

## 概述（中文）

通过 iGPT 上下文引擎 API 进行安全、每个用户隔离的电子邮件推理和分析。
总结线索、提取任务和决策、检测情绪和多个原因
对话——无 shell 访问、无文件系统访问、仅限 API 密钥范围。支持结构化
具有架构验证和流式传输 (SSE) 的 JSON 输出。当用户需要分析时使用，
摘要、结构化数据提取或需要了解电子邮件上下文的答案。
仅对于检索/查找，请使用配套技能 igpt-email-search。

## 原文

# iGPT Email Ask

Ask questions about a user's email and get reasoned, structured answers. Powered by iGPT's Context Engine, which reconstructs conversations, decisions, ownership, and intent across time.

## What This Skill Does

This skill queries iGPT's `recall/ask` endpoint to generate answers grounded in a user's connected email data. Unlike basic retrieval, the Context Engine:

- Reconstructs full conversation threads across replies, forwards, and CCs
- Identifies who decided what, who owns what, and what's still open
- Extracts structured data (tasks, deadlines, contacts, risks) from unstructured email
- Supports multiple quality tiers for different complexity levels
- Returns text, JSON, or schema-validated structured output
- Supports streaming (SSE) for real-time responses

## When to Use This Skill

- Summarize what happened in a thread or across threads
- Extract action items, decisions, or open questions
- Analyze sentiment or risk in deal/customer threads
- Answer questions that require understanding context across multiple emails
- Generate structured data from email content (JSON, schema-validated)
- Prepare briefings before meetings based on recent correspondence

## Prerequisites

1. An iGPT API key (get one at https://igpt.ai/hub/apikeys/)
2. A connected email datasource -- the user must have completed OAuth authorization via `connectors/authorize` before ask will return results. You can check connection status with `datasources.list()`.
3. Python >= 3.8 with the `igptai` package installed

## Setup

```bash
pip install igptai
```

Set your API key as an environment variable:

```bash
export IGPT_API_KEY="your-api-key-here"
```

## Usage

### Basic: Ask a question

```python
from igptai import IGPT
import os

igpt = IGPT(api_key=os.environ["IGPT_API_KEY"], user="user_123")

res = igpt.recall.ask(input="Summarize key risks, decisions, and next steps from this week's meetings.")
if res is not None and res.get("error"):
    print("iGPT error:", res)
else:
    print(res)
```

### Get JSON output

Pass `output_format="json"` for unstructured JSON, or provide a schema for validated structured output:

```python
# Simple JSON output
res = igpt.recall.ask(
    input="What are the open action items from this week?",
    output_format="json"
)

# Schema-validated structured output
res = igpt.recall.ask(
    input="Open action items from this week",
    quality="cef-1-normal",
    output_format={
        "strict": True,
        "schema": {
            "type": "object",
            "required": ["action_items"],
            "additionalProperties": False,
            "properties": {
                "action_items": {
                    "type": "array",
                    "items": {
                        "type": "object",
                        "required": ["title", "owner", "due_date"],
                        "properties": {
                            "title": {"type": "string"},
                            "owner": {"type": "string"},
                            "due_date": {"type": "string"}
                        }
                    }
                }
            }
        }
    }
)
print(res)
```

Example response:

```json
{
    "action_items": [
        {
            "title": "Approve revised Q1 budget allocation",
            "owner": "Dvir Ben-Aroya",
            "due_date": "2026-01-15"
        },
        {
            "title": "Approve final FY2026 strategic priorities",
            "owner": "Board of Directors",
            "due_date": "2026-01-31"
        }
    ]
}
```

### Use quality tiers

iGPT's Context Engine has three quality tiers:

```python
# Normal: fast, good for straightforward questions
res = igpt.recall.ask(
    input="When is my next meeting with Acme Corp?",
    quality="cef-1-normal"
)

# High: deeper reasoning, better for complex multi-thread analysis
res = igpt.recall.ask(
    input="What is the current negotiation status with Acme Corp and what leverage do we have?",
    quality="cef-1-high"
)

# Reasoning: maximum depth, for complex cross-thread synthesis
res = igpt.recall.ask(
    input="Across all communication with Acme over the past quarter, what patterns suggest risk and what should we do about it?",
    quality="cef-1-reasoning"
)
```

### Stream responses

Streaming returns parsed JSON chunks (dicts), not raw text. Extract content from each chunk:

```python
stream = igpt.recall.ask(
    input="Walk me through the timeline of the Acme deal from first contact to now.",
    stream=True
)

for chunk in stream:
    if isinstance(chunk, dict) and chunk.get("error"):
        print("Stream error:", chunk)
        break
    # Each chunk is a parsed JSON dict
    print(chunk)
```

Streaming is resilient: if the connection breaks, the iterator yields an error chunk and finishes rather than throwing.

### Check datasource connection before asking

```python
# Verify user has a connected datasource
status = igpt.datasources.list()
if status is not None and not status.get("error"):
    print("Connected datasources:", status)
else:
    # Connect a datasource first
    auth = igpt.connectors.authorize(service="spike", scope="messages")
    print("Open this URL to authorize:", auth.get("url"))
```

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| input | string | Yes | The prompt or question to ask. |
| user | string | Yes (or set in constructor) | Unique user identifier scoping the query to their connected data. Per-call value overrides constructor default. |
| stream | boolean | No (default: false) | If true, returns a generator yielding parsed JSON dicts via SSE. |
| quality | string | No | Context Engine quality tier: `"cef-1-normal"`, `"cef-1-high"`, or `"cef-1-reasoning"`. |
| output_format | string or object | No | `"text"` (default), `"json"`, or `{"strict": true, "schema": <JSON Schema>}` for validated structured output. |

## Error Handling

The SDK does not throw exceptions. It returns normalized error objects:

```python
res = igpt.recall.ask(input="What happened in yesterday's board meeting?")

if res is not None and res.get("error"):
    error = res["error"]
    if error == "auth":
        print("Check your API key")
    elif error == "params":
        print("Check your request parameters")
    elif error == "network_error":
        print("Network issue -- the SDK retries with exponential backoff (3 attempts by default) before returning this")
else:
    print(res)
```

## External Endpoints

This skill communicates exclusively with:

- `https://api.igpt.ai/v1/recall/ask/` -- the reasoning endpoint
- `https://api.igpt.ai/v1/connectors/authorize/` -- only during initial datasource connection setup
- `https://api.igpt.ai/v1/datasources/list/` -- to check connection status

No other external endpoints are contacted. No data is sent to any third-party service. The `igptai` PyPI package source is available at https://github.com/igptai/igpt-python.

## Security & Privacy

- **API-key scoped**: All requests authenticate via `IGPT_API_KEY` sent as a Bearer token over HTTPS. No shell access, no filesystem access, no system commands.
- **Per-user isolation**: Every query is scoped to a specific `user` identifier. User A cannot access User B's email data. Isolation is enforced at the index and execution level, not as a filter layer.
- **OAuth read-only**: The email datasource connection uses OAuth with read-only scopes. The skill does not send, modify, or delete emails.
- **No data retention**: Prompts are discarded after execution. Memory is reconstructed on-demand, not stored.
- **Transport encryption**: All communication occurs over HTTPS. No plaintext endpoints.
- **No local persistence**: This skill does not write to disk