@pencil-agent/nano-pencil 2.0.0-beta.8 → 2.0.0

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

@@ -1,349 +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,...'
-```
+# 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,...'
+```