gork-analysis

Gork data API. Uses Grok model to analyze tweet comments, extract valuable intelligence from replies, and fetch latest community sentiment on projects or topics.

# Gork Analysis — Tweet Comment Intelligence

**Base URL**: `https://crab-skill.opsat.io`

## API Endpoint

`POST /api/gork/analyze` (requires Crab signature headers)

| Field      | Required | Description                                                         |
|-----------|----------|---------------------------------------------------------------------|
| `prompt`  | Yes      | Analysis prompt with context (tweet URL, project name, question)    |
| `messages`| No       | OpenAI-style message list; takes precedence over `prompt` if given |

Response: plain-text analysis generated by the Grok model.

## Use Cases & Prompt Patterns

### 1. Analyze comments on a specific tweet

Extract valuable information from replies — insider knowledge, community
warnings, technical critiques, sentiment signals.

```json
{
  "prompt": "Analyze the comments and replies on this tweet: https://x.com/{username}/status/{id}\n\nFocus on:\n- High-value comments (technical insights, insider info, warnings)\n- Overall sentiment (bullish/bearish/neutral ratio)\n- Notable accounts that replied and their stance\n- Any claims or information worth verifying"
}
```

### 2. Get latest community sentiment on a project

Fetch what people are saying about a project right now.

```json
{
  "prompt": "What are the latest comments and discussions about {project_name} (${ticker}) on Twitter/X?\n\nFocus on:\n- Recent criticisms or concerns\n- Notable endorsements or callouts\n- Any news, events, or incidents being discussed\n- Red flags mentioned by the community"
}
```

### 3. Deep dive on a topic or controversy

When Step 4 (deep dig) surfaces a lead worth investigating via social data.

```json
{
  "prompt": "Search for discussions about {specific topic} related to {project_name}.\n\nFor example: '{project_name} + scam', '{team_member} + rug', '{project_name} + hack'\n\nSummarize what the community is saying and whether concerns are substantiated."
}
```

## Key Rules

- **Max 2 calls per research** — pick the top tweet (highest engagement) and the
  latest tweet (most recent). Do not make additional calls for project-level sentiment.
- **Always include tweet URL or project context in the prompt** — Gork needs specific
  context to return useful data, not generic questions
- **Use targeted prompts** — ask for specific information (comments, sentiment, controversy)
  rather than broad "analyze this project"
- **Chain with Twitter data** — use tweet URLs discovered from `/api/twitter/tweets`
  as input for Gork comment analysis
- **Deep dig exception** — Step 4 may make additional Gork calls only when a
  high-value lead requires verification, but still keep total calls minimal

## Timeout & Fallback

Gork calls the Grok model for analysis, so response times are significantly
longer than standard APIs. **Allow up to 120 seconds** before considering a
request timed out.

| Scenario                 | Behavior              |
|-------------------------|-----------------------|
| Gork API key not set    | Skip Gork data        |
| Response slow (< 120s)  | **Keep waiting** — this is normal for LLM analysis |
| Gork request timeout (≥ 120s) | Retry once, then skip and record a warning |