catui-agent 1.0.0-beta.0

package/dist/extensions/builtin/browser/agent-workspace/domain-skills/dev-to/scraping.md

@@ -0,0 +1,323 @@
+# DEV Community (dev.to) — Data Extraction
+
+`https://dev.to` — developer blogging platform. Everything useful is available via a public REST API with no auth required. No browser needed for any read task.
+
+## Do this first
+
+**Use the REST API — it returns clean JSON in ~150–250ms with no browser, no login, no JS rendering.**
+
+```python
+import json
+articles = json.loads(http_get("https://dev.to/api/articles?per_page=10&tag=python"))
+# Each article: id, title, description, url, cover_image, tag_list, tags,
+#               published_at, published_timestamp, readable_publish_date,
+#               reading_time_minutes, positive_reactions_count,
+#               public_reactions_count, comments_count, user, organization,
+#               flare_tag, collection_id, slug, path, canonical_url,
+#               social_image, language, subforem_id
+```
+
+The API serves **V0 (beta) by default** and emits a `Warning: 299` header on every response. Suppress it silently with the V1 `Accept` header (same data, no deprecated warning):
+
+```python
+import json
+import urllib.request, gzip
+
+def dev_get(url):
+    h = {
+        "User-Agent": "Mozilla/5.0",
+        "Accept-Encoding": "gzip",
+        "Accept": "application/vnd.forem.api-v1+json",
+    }
+    with urllib.request.urlopen(urllib.request.Request(url, headers=h), timeout=20) as r:
+        data = r.read()
+        if r.headers.get("Content-Encoding") == "gzip":
+            data = gzip.decompress(data)
+        return data.decode()
+
+articles = json.loads(dev_get("https://dev.to/api/articles?per_page=10&tag=python"))
+```
+
+Or just use `http_get` directly if you don't care about the warning header noise.
+
+---
+
+## Common workflows
+
+### Articles by tag
+
+```python
+import json
+articles = json.loads(http_get("https://dev.to/api/articles?per_page=10&tag=python"))
+# Paginate with &page=2, &page=3 etc. (1-indexed)
+for a in articles:
+    print(a['id'], a['positive_reactions_count'], a['title'][:60])
+```
+
+Confirmed working tags: `python`, `javascript`, `typescript`, `rust`, `go`, `webdev`, `tutorial`, `react`, `devops`, `ai`, `beginners`.
+
+### Top articles by time window
+
+```python
+import json
+# top=N means "top articles from the last N days"
+top_day   = json.loads(http_get("https://dev.to/api/articles?per_page=10&top=1"))
+top_week  = json.loads(http_get("https://dev.to/api/articles?per_page=10&top=7"))
+top_month = json.loads(http_get("https://dev.to/api/articles?per_page=10&top=30"))
+top_year  = json.loads(http_get("https://dev.to/api/articles?per_page=10&top=365"))
+```
+
+### Articles by username
+
+```python
+import json
+articles = json.loads(http_get("https://dev.to/api/articles?per_page=10&username=ben"))
+# Paginates cleanly: page=1, page=2 etc. Return distinct IDs, no overlap.
+```
+
+### New and rising articles
+
+```python
+import json
+fresh  = json.loads(http_get("https://dev.to/api/articles?per_page=10&state=fresh"))   # very new
+rising = json.loads(http_get("https://dev.to/api/articles?per_page=10&state=rising"))  # gaining traction
+# state=all returns 0 results (requires auth, not useful unauthenticated)
+```
+
+### Single article by ID (adds body_html and body_markdown)
+
+```python
+import json
+article = json.loads(http_get("https://dev.to/api/articles/3442047"))
+# Full article adds two fields not in list response:
+#   body_html     — rendered HTML (safe to display directly)
+#   body_markdown — raw Markdown source
+print(len(article['body_html']), len(article['body_markdown']))
+```
+
+### Single article by username/slug
+
+```python
+import json
+# path field from list response is "/username/slug"
+article = json.loads(http_get("https://dev.to/api/articles/ben/some-article-slug"))
+```
+
+### Tags — popular list with colors
+
+```python
+import json
+tags = json.loads(http_get("https://dev.to/api/tags?per_page=10"))
+# Fields: id, name, bg_color_hex, text_color_hex, short_summary
+# Sorted by popularity. Paginate with &page=2 etc.
+for t in tags:
+    print(t['name'], t['bg_color_hex'], t['text_color_hex'])
+# e.g. webdev  #562765  #ffffff
+#      javascript  #f7df1e  #000000
+#      ai  #17fd1a  #ffffff
+```
+
+### User profile
+
+```python
+import json
+user = json.loads(http_get("https://dev.to/api/users/by_username?url=ben"))
+# Fields: type_of, id, username, name, twitter_username, github_username,
+#         summary, location, website_url, joined_at, profile_image
+print(user['id'], user['username'], user['summary'])
+# e.g. 1  ben  "A Canadian software developer who thinks he's funny."
+```
+
+`joined_at` is a human string like `"Dec 27, 2015"` — not ISO 8601. Parse with `datetime.strptime(user['joined_at'], "%b %d, %Y")`.
+
+### Comments on an article
+
+```python
+import json
+comments = json.loads(http_get("https://dev.to/api/comments?a_id=3442047"))
+# Returns top-level comments only (replies nested under children key)
+# Fields per comment: id_code (string, not int!), type_of, body_html,
+#                     created_at, user (dict), children (list of same shape)
+for c in comments:
+    print(c['id_code'], c['user']['username'], c['created_at'])
+    for reply in c.get('children', []):
+        print("  reply:", reply['id_code'], reply['user']['username'])
+```
+
+### Single comment by id_code
+
+```python
+import json
+comment = json.loads(http_get("https://dev.to/api/comments/36lnc"))
+# Same fields as above: id_code, body_html, created_at, user, children
+```
+
+### Bulk tag fetch (parallel)
+
+```python
+import json
+from concurrent.futures import ThreadPoolExecutor
+
+tags = ['python', 'javascript', 'typescript', 'rust', 'go',
+        'devops', 'webdev', 'tutorial', 'productivity', 'react']
+
+def fetch_tag(tag):
+    data = json.loads(http_get(f"https://dev.to/api/articles?per_page=5&tag={tag}"))
+    return tag, data
+
+with ThreadPoolExecutor(max_workers=3) as ex:
+    results = dict(ex.map(lambda t: fetch_tag(t), tags))
+# 10 tags × 5 articles each: ~0.67s total with max_workers=3
+```
+
+---
+
+## Endpoint reference
+
+| Endpoint | Auth | Key params | Latency |
+|----------|------|-----------|---------|
+| `GET /api/articles` | None | `tag`, `username`, `top`, `state`, `page`, `per_page` | ~200ms |
+| `GET /api/articles/{id}` | None | — | ~80ms |
+| `GET /api/articles/{username}/{slug}` | None | — | ~200ms |
+| `GET /api/tags` | None | `page`, `per_page` | ~190ms |
+| `GET /api/users/by_username?url={username}` | None | — | ~190ms |
+| `GET /api/comments?a_id={article_id}` | None | — | ~160ms |
+| `GET /api/comments/{id_code}` | None | — | ~150ms |
+| `GET /api/listings` | None | `category`, `page`, `per_page` | ~260ms (returns 0) |
+
+**Listings endpoint returns 0 results.** The `/api/listings` endpoint is documented but returns an empty array for all categories (`jobs`, `forsale`, `education`, `cfp`) without auth. Skip it.
+
+---
+
+## Pagination
+
+All list endpoints paginate with `page=` (1-indexed) and `per_page=`:
+
+```python
+import json
+
+def get_all_articles_by_tag(tag, max_pages=5):
+    results = []
+    for page in range(1, max_pages + 1):
+        batch = json.loads(http_get(
+            f"https://dev.to/api/articles?per_page=30&tag={tag}&page={page}"
+        ))
+        if not batch:
+            break
+        results.extend(batch)
+    return results
+```
+
+- `per_page` supports up to **1000** (confirmed). No documented max, but 1000 works in testing.
+- No `total_count` field in list responses — you paginate until an empty array.
+- Page ordering is consistent — confirmed no ID overlap between page 1 and page 2.
+
+---
+
+## Article field reference
+
+All fields returned in list responses (single article adds `body_html` and `body_markdown`):
+
+```
+id                      int    — article ID, stable, use for single-article fetch
+title                   str
+description             str    — auto-excerpt, never null
+slug                    str    — URL slug component
+path                    str    — "/username/slug"
+url                     str    — full canonical URL
+canonical_url           str    — same as url for native posts; author's site URL for cross-posts
+cover_image             str|null — CDN URL or null (~30% of articles have no cover image)
+social_image            str    — always present (generated if no cover_image)
+tag_list                list   — e.g. ['python', 'ai', 'tutorial']  ← use this for code
+tags                    str    — same tags as comma-separated string "python, ai, tutorial"
+published_at            str    — ISO 8601 UTC e.g. "2026-04-18T03:49:36Z"
+published_timestamp     str    — identical to published_at
+readable_publish_date   str    — human string e.g. "Apr 18"
+reading_time_minutes    int
+positive_reactions_count int   — hearts/likes count
+public_reactions_count  int    — total reactions (usually same as positive_reactions_count)
+comments_count          int
+user                    dict   — name, username, twitter_username, github_username,
+                                 user_id, website_url, profile_image, profile_image_90
+organization            dict|null — present when posted under an org: name, username, slug,
+                                     profile_image, profile_image_90
+flare_tag               dict|null — {name, bg_color_hex, text_color_hex} — discussion/challenge badge
+collection_id           int|null  — series/collection ID if part of a series
+language                str    — e.g. "en"
+subforem_id             int|null
+crossposted_at          str|null — ISO datetime if cross-posted
+edited_at               str|null
+last_comment_at         str|null
+created_at              str    — ISO 8601
+type_of                 str    — always "article"
+```
+
+---
+
+## Rate limits
+
+- **Burst limit: ~6 rapid sequential requests**, then HTTP 429.
+- **Recovery: `Retry-After: 1` second** — wait 1s after a 429 and you're good again.
+- No `X-RateLimit-*` headers in 200 responses — you only see `Retry-After` on the 429 itself.
+- With `ThreadPoolExecutor(max_workers=3)`, 10 concurrent requests succeed without hitting the limit.
+- No difference in limits between V0 (default) and V1 (`Accept` header) — same underlying rate limit.
+- **No auth token tested** — all endpoints above work without `api_key`. Authenticated requests likely have higher limits.
+
+Safe pattern for bulk fetching:
+
+```python
+import json, time
+from concurrent.futures import ThreadPoolExecutor
+
+def safe_fetch(url):
+    for attempt in range(3):
+        try:
+            return json.loads(http_get(url))
+        except Exception as e:
+            if '429' in str(e):
+                time.sleep(1)   # Retry-After is 1s
+                continue
+            raise
+    return []
+
+urls = [
+    f"https://dev.to/api/articles?per_page=10&tag={tag}"
+    for tag in ['python', 'javascript', 'typescript', 'rust']
+]
+with ThreadPoolExecutor(max_workers=3) as ex:
+    results = list(ex.map(safe_fetch, urls))
+```
+
+---
+
+## Gotchas
+
+- **`tag_list` (list) vs `tags` (string)** — both fields always present. `tag_list` is a Python list; `tags` is the same data as a comma-separated string. Use `tag_list` in code.
+
+- **Comments have `id_code`, not `id`** — comment identifiers are alphanumeric strings like `"36lnc"`, not integers. The integer `id` field is absent from comment objects. Use `id_code` to fetch a specific comment via `GET /api/comments/{id_code}`.
+
+- **Comments endpoint returns top-level only** — replies are nested under `children` recursively, not returned as a flat list. A thread with 100 total comments may only show 60 top-level objects; walk `children` recursively to count all.
+
+- **`cover_image` can be null** — ~30% of articles have no cover image. Always guard: `a.get('cover_image') or a['social_image']` for a guaranteed image URL.
+
+- **`flare_tag` is null for most articles** — only discussion/challenge posts carry it. It's a dict `{name, bg_color_hex, text_color_hex}` when present.
+
+- **`published_at` == `published_timestamp`** — both fields contain identical ISO 8601 UTC strings. `readable_publish_date` is human-only (`"Apr 18"`, no year).
+
+- **`joined_at` on user profile is not ISO** — it's `"Dec 27, 2015"`. Parse: `datetime.strptime(u['joined_at'], "%b %d, %Y")`.
+
+- **`state=all` returns 0 results unauthenticated** — it's for the authenticated user's own feed. `state=fresh` and `state=rising` work without auth.
+
+- **`top=N` means last N days** — `top=1` is last 24h, `top=7` is last week, `top=30` is last month, `top=365` is last year. Results differ from the `state=` param.
+
+- **V0 warning header on every response** — `Warning: 299 - This endpoint is part of the V0 (beta) API…` appears on all responses without the `Accept` header. It's harmless but noisy. Suppress with `"Accept": "application/vnd.forem.api-v1+json"`.
+
+- **No `total_count` in list responses** — paginate until an empty array. There is no way to know upfront how many total results exist.
+
+- **Listings endpoint returns empty** — `GET /api/listings` and all category variants return `[]` without auth. Documented but non-functional publicly.
+
+- **`/api/articles/{id}/comments` returns 404** — comments must be fetched via `GET /api/comments?a_id={id}`, not as a sub-resource of articles.
+
+- **`canonical_url` may point off-site** — for cross-posted articles, `canonical_url` is the author's original blog URL, not dev.to. Use `url` for the dev.to link.
+
+- **`organization` field is null for personal posts** — only present when the article was posted under an org account. Check before accessing sub-fields.

package/dist/extensions/builtin/browser/agent-workspace/domain-skills/duckduckgo/scraping.md

@@ -0,0 +1,349 @@
+# DuckDuckGo — Instant Answer API
+
+`https://api.duckduckgo.com` — completely public, no auth, no API key. Returns Wikipedia-sourced abstracts, infoboxes, and instant answers for well-known entities, calculations, and utility queries. Not a search engine — it does not return a list of web results for arbitrary queries.
+
+## Do this first: pick your query type
+
+| Query type | Example | `Type` | Returns |
+|------------|---------|--------|---------|
+| Named entity (specific) | `apple inc` | A | Full abstract + infobox |
+| Ambiguous term | `python` | D | Disambiguation list in `RelatedTopics` |
+| Instant answer | `random number` | E | Direct answer in `Answer` field |
+| No match | `how to cook pasta` | `""` | All fields empty |
+
+**Use `skip_disambig=1` and `no_html=1` in almost every call.** `skip_disambig=1` upgrades D→A when there's an obvious primary result (e.g., `elon musk` goes from disambiguation to full article). `no_html=1` removes `<b>` tags from the `Answer` field and strips bold markup from `Result` HTML strings.
+
+**Never use a browser.** Everything is a single `http_get` JSON call, 183–320ms.
+
+---
+
+## Fastest path: entity lookup
+
+```python
+import json, urllib.parse
+from helpers import http_get
+
+def ddg_instant(query: str) -> dict:
+    q = urllib.parse.quote(query)
+    raw = http_get(
+        f"https://api.duckduckgo.com/?q={q}&format=json&no_html=1&skip_disambig=1"
+    )
+    return json.loads(raw)
+
+# Entity with Wikipedia abstract + infobox
+data = ddg_instant("openai")
+# data['Type'] == 'A'
+print(data['Heading'])        # 'OpenAI'
+print(data['AbstractText'])   # 'OpenAI is an American artificial intelligence research...'
+print(data['AbstractURL'])    # 'https://en.wikipedia.org/wiki/OpenAI'
+print(data['OfficialWebsite'])# 'https://openai.com/'
+print(data['Entity'])         # 'company'
+
+# Person lookup (skip_disambig resolves D→A automatically)
+data = ddg_instant("elon musk")
+print(data['Type'])           # 'A' (was 'D' without skip_disambig)
+print(data['AbstractText'][:100])  # 'Elon Reeve Musk is a businessman...'
+print(data['Image'])          # '/i/be2a8644.jpg' — prepend https://duckduckgo.com
+
+# Full image URL
+img_url = f"https://duckduckgo.com{data['Image']}" if data['Image'] else None
+```
+
+---
+
+## Instant answers (Type = E)
+
+```python
+import json, urllib.parse
+from helpers import http_get
+
+def ddg_answer(query: str) -> tuple[str, str]:
+    """Returns (answer_text, answer_type). answer_text is '' if no result."""
+    q = urllib.parse.quote(query)
+    raw = http_get(
+        f"https://api.duckduckgo.com/?q={q}&format=json&no_html=1&no_redirect=1"
+    )
+    data = json.loads(raw)
+    ans = data.get('Answer', '')
+    # Answer can be a dict when it's a widget (calculator, converter) — only string Answers are usable
+    return (ans if isinstance(ans, str) else '', data.get('AnswerType', ''))
+
+# Confirmed working instant answers:
+text, kind = ddg_answer("random number")
+# text='0.245013228691281 (random number)', kind='rand'
+
+text, kind = ddg_answer("generate password")
+# text='ZCsbe8iY (random password)', kind='pw'
+
+text, kind = ddg_answer("ip address")
+# text='Your IP address is 73.158.74.222 in San Francisco, California, United States (94121)', kind='ip'
+
+text, kind = ddg_answer("base64 encode hello")
+# text='Base64 encode d: aGVsbG8=', kind='base64_conversion'
+
+text, kind = ddg_answer("md5 hash hello")
+# text='5d41402abc4b2a76b9719d911017c592', kind='md5'
+
+text, kind = ddg_answer("pi")
+# text='3.14159', kind='constants'
+
+text, kind = ddg_answer("today date")
+# text='\nS M T W T F S      April 2026\n...|18|...', kind='calendar'
+
+text, kind = ddg_answer("timer 5 minutes")
+# text='300', kind='timer'   — returns raw seconds
+
+text, kind = ddg_answer("lorem ipsum")
+# text='Ea hic quia corporis. Minus consequuntur...', kind='lorem_ipsum'
+
+# Color lookup — must URL-encode the # sign:
+text, kind = ddg_answer("color #FF5733")
+# text='Hex: #FF5733 ~ RGBA(255, 87, 51, 1) ~ RGB(100%, 34%, 20%) ~ HSL(11, 100%, 60%) ~ CMYB(0%, 66%, 80%, ...', kind='color_code'
+```
+
+**Widget answers return a dict, not a string** — `sqrt(144)`, `1 mile in km`, `100 USD in EUR`, and `stopwatch` all return `Answer` as a dict like `{'from': 'calculator', 'id': 'calculator', 'result': '', ...}`. The `result` key is empty — the actual computation happens client-side in a JS widget. Treat dict `Answer` values as "not usable via API".
+
+---
+
+## Full response schema
+
+Every response has exactly these 21 top-level keys (all always present):
+
+```
+Abstract         # same as AbstractText (redundant, use AbstractText)
+AbstractSource   # "Wikipedia" when present, "" otherwise
+AbstractText     # Wikipedia-sourced summary paragraph (up to ~1000 chars)
+AbstractURL      # Wikipedia article URL
+Answer           # string or dict — instant answer result (see above)
+AnswerType       # string key identifying the answer plugin (e.g. "rand", "ip")
+Definition       # almost always "" — not reliably populated
+DefinitionSource # almost always ""
+DefinitionURL    # almost always ""
+Entity           # entity type: "company", "programming language", "person", etc.
+Heading          # entity display name
+Image            # relative path e.g. "/i/4d83768732377cf3.png" — prepend https://duckduckgo.com
+ImageHeight      # int or "" when no image
+ImageIsLogo      # 0 or 1 integer when image present; "" otherwise
+ImageWidth       # int or "" when no image
+Infobox          # dict with "content" and "meta" lists, or "" if no infobox
+OfficialDomain   # e.g. "openai.com" — only for entities with a known website
+OfficialWebsite  # e.g. "https://openai.com/" — only when DDG knows it
+Redirect         # target URL when query is a bang (e.g. !g python) with no_redirect=1
+RelatedTopics    # list — see below
+Results          # list — official site links (usually 0 or 1 item)
+Type             # "A", "D", "C", "N", "E", or ""
+meta             # API plugin metadata — rarely needed
+```
+
+### `RelatedTopics` item structure
+
+Each item is one of two shapes:
+
+**Plain topic** (the common case):
+```python
+{
+    "FirstURL": "https://duckduckgo.com/Deep_learning",
+    "Icon": {"Height": "", "URL": "/i/abc123.png", "Width": ""},  # URL often ""
+    "Result": "<a href=\"...\">Deep learning</a>— branch of ML...",  # HTML
+    "Text": "Deep learning — branch of ML concerned with artificial neural networks."
+}
+```
+
+**Section** (disambiguation pages only — when `Type` is `D` without `skip_disambig`):
+```python
+{
+    "Name": "Science & Technology",   # section heading
+    "Topics": [                        # list of plain topic objects
+        {"FirstURL": "...", "Icon": {...}, "Result": "...", "Text": "..."},
+        ...
+    ]
+}
+```
+
+For A-type results, `RelatedTopics` are Wikipedia category links (e.g. `"American aerospace engineers"` pointing to `https://duckduckgo.com/c/...`). These are not web search results — they are DDG topic pages.
+
+### `Results` item structure
+
+Usually 0 or 1 item. When present, it's the official website:
+```python
+{
+    "FirstURL": "https://www.apple.com/",
+    "Icon": {"Height": 16, "URL": "/i/apple.com.ico", "Width": 16},
+    "Result": "<a href=\"https://www.apple.com/\">Official site</a>...",
+    "Text": "Official site"
+}
+```
+Icon URLs in `Results` are relative — prepend `https://duckduckgo.com`.
+
+### `Infobox` structure
+
+```python
+ib = data['Infobox']  # dict or "" (empty string when absent)
+if isinstance(ib, dict):
+    content = ib['content']  # list of structured fields
+    # Each content item:
+    # {"data_type": "string", "label": "Founded", "value": "December 08, 2015"}
+    # {"data_type": "string", "label": "Founders", "value": "Sam Altman, Elon Musk, ..."}
+    
+    meta = ib['meta']    # list of metadata items
+    # {"data_type": "string", "label": "article_title", "value": "OpenAI"}
+    # {"data_type": "string", "label": "template_name", "value": "infobox company"}
+
+# Extract infobox as flat dict:
+if isinstance(data['Infobox'], dict):
+    fields = {item['label']: item['value'] for item in data['Infobox']['content']}
+    # fields['Founded'] == 'December 08, 2015'
+    # fields['Products'] == 'ChatGPT, GPT-5...'
+```
+
+`Infobox` is `""` (empty string, not `None`, not `{}`) when absent. Always check with `isinstance(data['Infobox'], dict)`.
+
+---
+
+## Query parameters
+
+| Parameter | Values | Effect |
+|-----------|--------|--------|
+| `q` | URL-encoded query | The search query |
+| `format` | `json` | Required — omit for HTML response |
+| `no_redirect` | `1` | Returns redirect URL in `Redirect` field instead of HTTP 302; required for bang queries (`!g`, `!yt`) |
+| `no_html` | `1` | Strips `<b>` from `Answer`; strips bold markup from `Result` HTML; use in almost every call |
+| `skip_disambig` | `1` | Resolves ambiguous D-type queries to the primary result; upgrades D→A when unambiguous |
+| `t` | any string | Source identifier tag (e.g. `t=myapp`); has no effect on results |
+| `callback` | function name | Wraps response in JSONP: `mycallback({...})` |
+
+---
+
+## Type field values
+
+| Type | Meaning | AbstractText | RelatedTopics |
+|------|---------|--------------|---------------|
+| `A` | Article — specific Wikipedia entity | Full paragraph | Category links |
+| `D` | Disambiguation — ambiguous term | Empty `""` | List of possible meanings (may include sections) |
+| `C` | Categories | Varies | Category items |
+| `N` | Name | Varies | Name-related items |
+| `E` | Exclusive — instant answer widget | Empty `""` | Empty `[]` |
+| `""` | No result | Empty `""` | Empty `[]` |
+
+In practice, C and N types are rare. A, D, E, and empty cover nearly all queries.
+
+---
+
+## What returns useful results vs empty
+
+**Returns AbstractText (A type):**
+- Named companies: `apple inc`, `openai`, `google`
+- Specific technologies: `python programming language`, `javascript`, `linux kernel`
+- Well-known people with `skip_disambig=1`: `elon musk`, `ada lovelace`
+- Scientific concepts: `machine learning`, `photosynthesis`, `circumference`
+- Specific software: `vim`, `postgresql`, `nginx`
+
+**Returns RelatedTopics only (D type):**
+- Ambiguous single words: `python`, `linux`, `react`, `programming`
+- Ambiguous names: `apple` (returns empty — too ambiguous even for D), `new york`
+
+**Returns empty (Type = ""):**
+- How-to queries: `how to cook pasta`, `how to learn python`
+- Opinion/listicle: `best laptops 2024`, `top 10 programming languages`
+- Current events: `weather london`, `bitcoin price`
+- Site search operators: `site:example.com`
+- Multi-word specifics not in DDG's dataset: `numpy python library`, `javascript tutorial`
+
+**Returns instant answer (E type):**
+- Random: `random number`, `generate password`, `lorem ipsum`
+- Math: `pi`, `timer 5 minutes`
+- Network: `ip address`
+- Encoding: `base64 encode <text>`, `md5 hash <text>`
+- Color lookup: `color #RRGGBB` (must URL-encode the `#`)
+
+---
+
+## Gotchas
+
+**`Infobox` is `""` not `None` when absent.** Always check with `isinstance(data['Infobox'], dict)` — `if data['Infobox']` also works since `""` is falsy.
+
+**Image and Icon URLs are relative.** `data['Image']` is `/i/abc123.png`. Prepend `https://duckduckgo.com` to make it absolute. Same for Icon URLs in `RelatedTopics` and `Results`.
+
+**`Answer` can be a dict (widget), not a string.** Queries like `1 mile in km`, `100 USD in EUR`, `sqrt(144)`, and `stopwatch` return `Answer` as a dict with `{'from': 'calculator', 'result': '', ...}`. The `result` key is empty — the widget computes client-side. Only string `Answer` values are usable via the API.
+
+**`color #RRGGBB` requires URL encoding of `#`.** Using `q=color+#FF5733` returns an HTML page (HTTP redirect). Use `urllib.parse.quote("color #FF5733")` which encodes to `color+%23FF5733`.
+
+**Bang queries without `no_redirect=1` return HTML, not JSON.** `!g python` (without `no_redirect=1`) causes an HTTP 302 to `google.com/search?q=python`. The `http_get` helper follows the redirect and returns Google's HTML — `json.loads` fails. Always add `no_redirect=1` when the query might contain bangs.
+
+**`skip_disambig=1` can add latency for truly ambiguous terms.** For `apple` (no "inc"), DDG returns Type `""` even with `skip_disambig=1` — it's so ambiguous it gives nothing. For `elon musk`, `skip_disambig=1` switches from D to A and adds `RelatedTopics` (39 items vs 4), which means a larger response (~5x).
+
+**`AbstractText` is empty for D-type results.** When `Type == 'D'`, DDG only returns `RelatedTopics` (the disambiguation list). The abstract is only filled for `Type == 'A'`.
+
+**`RelatedTopics` for A-type are Wikipedia categories, not related searches.** For `openai`, the 4 `RelatedTopics` are `"American artificial intelligence companies"`, `"Companies in San Francisco"`, etc. — these are DDG category page links, not useful web search results.
+
+**`Definition` / `DefinitionSource` / `DefinitionURL` are always empty** in observed responses. These fields are part of the schema but not reliably populated by any current DDG plugin.
+
+**No rate limiting observed.** 15 rapid sequential requests completed in 3.11s (~208ms avg) with no throttling, no 429, and consistent response structure throughout. DDG does not publish rate limits; the API is designed for "reasonable" use with a `t=` source identifier.
+
+**`OfficialWebsite` is only set for a subset of A-type results.** `machine learning` (Type A) has no `OfficialWebsite`. `openai`, `python programming language`, and `linux kernel` all have one. Always check with `data.get('OfficialWebsite', '')`.
+
+**No_html does not affect the `Result` HTML string.** `Results[0]['Result']` still contains `<a href="...">` tags with `no_html=1`. The `no_html` flag only removes `<b>` bold tags. Use `Results[0]['Text']` for the plain-text version, or `Results[0]['FirstURL']` for just the URL.
+
+---
+
+## Complete working example
+
+```python
+import json, urllib.parse
+from helpers import http_get
+
+def ddg_entity(query: str) -> dict | None:
+    """
+    Fetch a DuckDuckGo Instant Answer for a named entity.
+    Returns structured data or None if no result.
+    """
+    q = urllib.parse.quote(query)
+    raw = http_get(
+        f"https://api.duckduckgo.com/?q={q}&format=json&no_html=1&skip_disambig=1"
+    )
+    data = json.loads(raw)
+    if not data.get('AbstractText') and not data.get('Answer'):
+        return None
+
+    result = {
+        'type': data['Type'],
+        'heading': data['Heading'],
+        'abstract': data['AbstractText'],
+        'abstract_url': data['AbstractURL'],
+        'entity': data['Entity'],
+        'official_website': data['OfficialWebsite'],
+        'image': f"https://duckduckgo.com{data['Image']}" if data['Image'] else None,
+        'answer': data['Answer'] if isinstance(data['Answer'], str) else None,
+        'answer_type': data['AnswerType'],
+    }
+
+    # Extract infobox as flat dict
+    if isinstance(data['Infobox'], dict):
+        result['infobox'] = {
+            item['label']: item['value']
+            for item in data['Infobox']['content']
+        }
+
+    # Official site URL (from Results)
+    if data['Results']:
+        result['official_site_url'] = data['Results'][0]['FirstURL']
+
+    return result
+
+# Example outputs (validated 2026-04-18):
+r = ddg_entity("openai")
+# r['type']            == 'A'
+# r['heading']         == 'OpenAI'
+# r['abstract'][:50]   == 'OpenAI is an American artificial intelligence res'
+# r['entity']          == 'company'
+# r['official_website']== 'https://openai.com/'
+# r['image']           == 'https://duckduckgo.com/i/fb410946942ab334.png'
+# r['infobox']['Founded'] == 'December 08, 2015'
+# r['infobox']['Products'] == 'ChatGPT, GPT-5...'
+
+r = ddg_entity("python programming language")
+# r['type']            == 'A'
+# r['entity']          == 'programming language'
+# r['official_website']== 'https://www.python.org/'
+# r['infobox']['Paradigm'] == 'Multi-paradigm: object-oriented,...'
+```