nyne-deep-research

Research any person using the Nyne Deep Research API. Submit an email, phone, social URL, or name and receive a comprehensive intelligence dossier with psychographic profile, social graph, career analysis, conversation starters, and approach strategy. Async with 2-5 min processing.

# Nyne Deep Research Skill

Research any person by email, phone, social URL, or name. Returns a comprehensive intelligence dossier with psychographic profile, social graph, career analysis, conversation starters, and approach strategy.

**Important:** This API is async with high latency (2-5 min processing). You submit a request, get a `request_id`, then poll until complete.

## Agent Instructions

When presenting results to the user, show **maximum depth** — display every section of the dossier in full. Do not summarize or truncate. Walk through each section sequentially:

1. **Identity Snapshot** — who they are
2. **Career DNA** — trajectory and superpower
3. **Psychographic Profile** — values, motivations, archetypes
4. **Personal Life & Hobbies** — interests outside work
5. **Social Graph Analysis** — inner circle, professional network, interest graph
6. **Interest Cluster Deep Dive** — all 9 clusters with detail
7. **Content & Voice Analysis** — topics, tone, opinions, quotes
8. **Key Relationships** — full list with relationship nature and importance
9. **Conversation Starters** — all 4 hook categories
10. **Recommendations / How Others See Them** — reputation signals
11. **Warnings & Landmines** — topics to avoid, sensitivities
12. **Creepy-Good Insights** — non-obvious findings with evidence
13. **Approach Strategy** — best angle, topics, what not to do

Also include `enrichment` data (contact info, work history, education) and note whether `following` and `articles` sections have data.

If `dossier` is null, present the `enrichment` data and let the user know the full dossier was not generated (this can happen with duplicate or cached requests — resubmit with a different identifier).

If `following` or `articles` are null, simply note they were not available for this person.

## Setup

**Required environment variables:**
- `NYNE_API_KEY` — your Nyne API key
- `NYNE_API_SECRET` — your Nyne API secret

Get credentials at [https://api.nyne.ai](https://api.nyne.ai).

Set these in your shell before running any commands:
```bash
export NYNE_API_KEY="your-api-key"
export NYNE_API_SECRET="your-api-secret"
```

To persist across sessions, add the exports to your shell profile (`~/.zshrc`, `~/.bashrc`, etc.) or create a `.env` file and source it:
```bash
# Create .env file (keep out of version control)
echo 'export NYNE_API_KEY="your-api-key"' >> ~/.nyne_env
echo 'export NYNE_API_SECRET="your-api-secret"' >> ~/.nyne_env
source ~/.nyne_env
```

Verify they're set:
```bash
echo "Key: ${NYNE_API_KEY:0:8}... Secret: ${NYNE_API_SECRET:0:6}..."
```

## Important: JSON Handling

The API response can contain control characters in JSON string values that break `jq`. All examples below use a `nyne_parse` helper that pipes through `python3` to clean and re-encode the JSON before passing to `jq`. Define it once per session:

```bash
nyne_parse() {
  python3 -c "
import sys, json, re
raw = sys.stdin.read()
clean = re.sub(r'[\x00-\x1f]+', ' ', raw)
data = json.loads(clean)
json.dump(data, sys.stdout)
"
}
```

## Quick Start

Submit a research request by email and poll until complete:

```bash
# Define helper (strips control chars, re-encodes clean JSON)
nyne_parse() {
  python3 -c "
import sys, json, re
raw = sys.stdin.read()
clean = re.sub(r'[\x00-\x1f]+', ' ', raw)
data = json.loads(clean)
json.dump(data, sys.stdout)
"
}

# Submit research request
REQUEST_ID=$(curl -s -X POST "https://api.nyne.ai/person/deep-research" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $NYNE_API_KEY" \
  -H "X-API-Secret: $NYNE_API_SECRET" \
  -d '{"email": "someone@example.com"}' | nyne_parse | jq -r '.data.request_id')

echo "Request submitted: $REQUEST_ID"

# Poll until complete (checks every 5s, times out after 10 min)
SECONDS_WAITED=0
while [ $SECONDS_WAITED -lt 600 ]; do
  curl -s "https://api.nyne.ai/person/deep-research?request_id=$REQUEST_ID" \
    -H "X-API-Key: $NYNE_API_KEY" \
    -H "X-API-Secret: $NYNE_API_SECRET" | nyne_parse > /tmp/nyne_response.json
  STATUS=$(jq -r '.data.status' /tmp/nyne_response.json)
  echo "Status: $STATUS ($SECONDS_WAITED seconds elapsed)"
  if [ "$STATUS" = "completed" ]; then
    jq '.data.result' /tmp/nyne_response.json
    break
  elif [ "$STATUS" = "failed" ]; then
    echo "Research failed."
    jq . /tmp/nyne_response.json
    break
  fi
  sleep 5
  SECONDS_WAITED=$((SECONDS_WAITED + 5))
done

if [ $SECONDS_WAITED -ge 600 ]; then
  echo "Timed out after 10 minutes. Try polling manually with request_id: $REQUEST_ID"
fi
```

## Submit Research (POST)

**Endpoint:** `POST https://api.nyne.ai/person/deep-research`

**Headers:**
```
Content-Type: application/json
X-API-Key: $NYNE_API_KEY
X-API-Secret: $NYNE_API_SECRET
```

**Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `email` | string | Email address |
| `phone` | string | Phone number |
| `social_media_url` | string or array | Social profile URL(s), up to 3 |
| `name` | string | Full name (use with `company` or `city` for disambiguation) |
| `company` | string | Company name (helps disambiguate `name`) |
| `city` | string | City (helps disambiguate `name`) |
| `callback_url` | string | Webhook URL to POST results when complete |

At least one identifier is required: `email`, `phone`, `social_media_url`, or `name` with `company`/`city`.

### Examples

**By email:**
```bash
curl -s -X POST "https://api.nyne.ai/person/deep-research" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $NYNE_API_KEY" \
  -H "X-API-Secret: $NYNE_API_SECRET" \
  -d '{"email": "someone@example.com"}' | nyne_parse | jq .
```

**By social media URL:**
```bash
curl -s -X POST "https://api.nyne.ai/person/deep-research" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $NYNE_API_KEY" \
  -H "X-API-Secret: $NYNE_API_SECRET" \
  -d '{"social_media_url": "https://twitter.com/elonmusk"}' | nyne_parse | jq .
```

**By multiple social URLs:**
```bash
curl -s -X POST "https://api.nyne.ai/person/deep-research" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $NYNE_API_KEY" \
  -H "X-API-Secret: $NYNE_API_SECRET" \
  -d '{"social_media_url": ["https://twitter.com/elonmusk", "https://linkedin.com/in/elonmusk"]}' | nyne_parse | jq .
```

**By name + company:**
```bash
curl -s -X POST "https://api.nyne.ai/person/deep-research" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $NYNE_API_KEY" \
  -H "X-API-Secret: $NYNE_API_SECRET" \
  -d '{"name": "Jane Smith", "company": "Acme Corp"}' | nyne_parse | jq .
```

**By phone:**
```bash
curl -s -X POST "https://api.nyne.ai/person/deep-research" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $NYNE_API_KEY" \
  -H "X-API-Secret: $NYNE_API_SECRET" \
  -d '{"phone": "+14155551234"}' | nyne_parse | jq .
```

**Submit response (HTTP 202):**
```json
{
  "success": true,
  "data": {
    "request_id": "abc123-def456-...",
    "status": "pending"
  }
}
```

## Poll for Results (GET)

**Endpoint:** `GET https://api.nyne.ai/person/deep-research?request_id={id}`

**Headers:** Same `X-API-Key` and `X-API-Secret` as above.

**Status progression:** `pending` → `enriching` → `gathering` → `analyzing` → `completed` (or `failed`)

This typically takes 2-3 minutes.

### Check status once
```bash
curl -s "https://api.nyne.ai/person/deep-research?request_id=$REQUEST_ID" \
  -H "X-API-Key: $NYNE_API_KEY" \
  -H "X-API-Secret: $NYNE_API_SECRET" | nyne_parse | jq '{status: .data.status, completed: .data.completed}'
```

### Full polling loop

```bash
SECONDS_WAITED=0
TIMEOUT=600  # 10 minutes

while [ $SECONDS_WAITED -lt $TIMEOUT ]; do
  curl -s "https://api.nyne.ai/person/deep-research?request_id=$REQUEST_ID" \
    -H "X-API-Key: $NYNE_API_KEY" \
    -H "X-API-Secret: $NYNE_API_SECRET" | nyne_parse > /tmp/nyne_response.json
  STATUS=$(jq -r '.data.status' /tmp/nyne_response.json)

  echo "[$(date +%H:%M:%S)] Status: $STATUS ($SECONDS_WAITED s)"

  case "$STATUS" in
    completed)
      jq '.data.result' /tmp/n