Agentic-GenUI-Tools 0.2.0__tar.gz

agentic_genui_tools-0.2.0/.github/workflows/tests.yml

@@ -0,0 +1,24 @@
+name: tests
+on: [push, pull_request]
+jobs:
+  core:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.10', '3.11', '3.12', '3.13']
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: python -m pip install '.[test]'
+      - run: python -m unittest discover -s tests -v
+  integration:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - run: python -m pip install '.[test,integration]'
+      - run: python -m unittest discover -s tests -v

agentic_genui_tools-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Agentic-GenUI-Tools contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agentic_genui_tools-0.2.0/MANIFEST.in

@@ -0,0 +1,5 @@
+include README.md LICENSE
+recursive-include docs *.md
+recursive-include .github *.yml
+recursive-include examples *.py *.js *.json
+recursive-include tests *.py *.json *.md LICENSE-MICROSOFT

agentic_genui_tools-0.2.0/PKG-INFO

@@ -0,0 +1,284 @@
+Metadata-Version: 2.4
+Name: Agentic-GenUI-Tools
+Version: 0.2.0
+Summary: Modern, deterministic Adaptive Cards from small, forgiving agent tool calls
+License-Expression: MIT
+Keywords: adaptive-cards,agents,tools,google-adk,langchain
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Requires-Dist: jsonschema>=4; extra == "test"
+Provides-Extra: integration
+Requires-Dist: google-adk>=1; extra == "integration"
+Requires-Dist: langchain-core>=0.3; extra == "integration"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: jsonschema>=4; extra == "dev"
+Requires-Dist: build>=1; extra == "dev"
+Requires-Dist: twine>=5; extra == "dev"
+Dynamic: license-file
+
+# adaptive-card-tools
+
+Build modern, deterministic Adaptive Cards from small, forgiving agent tool
+calls. The model describes *what* to show; Python repairs the request,
+applies a consistent visual design, and returns a complete card.
+
+Designed for small models such as GPT-4.1 mini and Gemini 2.5 Flash:
+
+- **Short prompt.** The tool description is ~1,200 tokens of examples, not a
+  schema manual (it was ~8,500 in 0.1.x).
+- **Repair, don't reject.** Wrong type names, Adaptive Card JSON, style keys,
+  aliases, typos, strings for numbers and dates, odd option shapes, wrapped
+  or broken JSON: all are interpreted. Errors are reserved for requests that
+  are unreadable, empty, or over a safety limit.
+- **Accurate.** Repairs change the *form* of a value, never its *facts*. Text
+  is never rewritten or truncated, numbers are parsed but never estimated,
+  missing chart points are not filled with zeros, and anything that can't be
+  read exactly is left out with a warning. Every repair is listed in metadata.
+- **Modern and stable.** The model never chooses styling. Every card gets the
+  same hierarchy (title, status badge, KPI tiles, data bars, shaded table
+  headers, primary/destructive buttons) built from primitives that render on
+  every Adaptive Cards host.
+
+Python 3.10+, no runtime dependencies. Import name: `adaptive_card_tools`.
+
+Rendered with Microsoft's `adaptivecards` JS SDK. 0.2 with `host_config()` and
+`examples/card-theme.css` (the middle card is the deliberately messy call from
+`examples.py`):
+
+![0.2 output](docs/images/after-0.2.png)
+
+<details><summary>0.1 output for comparison</summary>
+
+![0.1 output](docs/images/before-0.1.png)
+
+</details>
+
+## Install and use
+
+```bash
+python -m pip install .
+```
+
+```python
+from adaptive_card_tools import build_adaptive_card
+
+result = build_adaptive_card({
+    "title": "Weekly sales",
+    "subtitle": "Week ending 11 Sep 2026",
+    "status": "On track",
+    "elements": [
+        {"type": "metrics", "items": [
+            {"label": "Revenue", "value": "$48,200", "change": "+12%"},
+            {"label": "Orders", "value": "312", "change": "-3%"}]},
+        {"type": "chart", "chart_type": "bar", "title": "Revenue by region",
+         "data": {"North": 18200, "South": 12100, "West": 17900}},
+    ],
+})
+result["status"]          # "successful"
+result["response"]        # the Adaptive Card JSON for your frontend
+result["message"]         # a short instruction for the model
+```
+
+## Add to an agent
+
+The function is a plain Python tool; its docstring is the model's prompt
+(see [docs/TOOL_DOCSTRING.md](docs/TOOL_DOCSTRING.md)).
+
+```python
+# Google ADK
+from google.adk.agents import Agent
+from adaptive_card_tools import build_adaptive_card
+
+agent = Agent(name="card_assistant", model="gemini-2.5-flash", tools=[build_adaptive_card],
+              instruction="When the answer is a form, summary, comparison, dashboard, approval, "
+                          "table or chart, call build_adaptive_card once with the complete content.")
+```
+
+```python
+# LangChain, with the rich schema (element types as an enum, which small models follow well)
+from langchain.agents import create_agent
+from langchain_core.tools import StructuredTool
+from adaptive_card_tools import build_adaptive_card, tool_schema
+
+schema = tool_schema()
+card_tool = StructuredTool.from_function(build_adaptive_card, name=schema["name"],
+                                         description=schema["description"], args_schema=schema["parameters"])
+agent = create_agent(model="openai:gpt-4.1-mini", tools=[card_tool])
+```
+
+If a provider rejects a free-form object parameter (some Gemini setups and
+strict tool modes do), use `build_adaptive_card_json(request_json: str)`. Its
+parser also repairs single quotes, trailing commas, comments, Python
+`True/None`, code fences, prose around the JSON, and unclosed brackets.
+
+`make_adaptive_card_tool(BuilderConfig(...), json_input=False)` returns a tool
+bound to your settings. `describe_adaptive_card(type)` is an optional helper
+tool; small models rarely need it.
+
+## What the model writes
+
+```json
+{"title": "Book a demo", "elements": [
+  {"type": "text", "text": "Pick a time that suits you."},
+  {"type": "text_input", "id": "name", "label": "Full name", "required": true},
+  {"type": "date_input", "id": "day", "label": "Preferred day"},
+  {"type": "choice", "id": "size", "label": "Team size", "options": ["1-10", "11-50", "51+"]}],
+ "submit_label": "Request demo"}
+```
+
+| Group | Types |
+|---|---|
+| Content | `heading`, `text` (markdown), `note`, `list`, `facts`, `table`, `badge`, `image`, `images`, `media` |
+| Data | `metrics` (KPI tiles), `chart` (`bar`, `horizontal_bar`, `line`, `pie`, `donut`, `stacked_bar`, `grouped_bar`, `gauge`), `progress`, `rating` |
+| Layout | `section`, `columns`, `divider`, `buttons` |
+| Inputs | `text_input`, `number_input`, `date_input`, `time_input`, `datetime_input`, `choice`, `checkbox`, `rating_input` |
+
+Card-level fields: `title`, `subtitle`, `status` (a coloured badge next to the
+title), `elements`, `submit_label`, `buttons`. Forms get a Submit button
+automatically; `"buttons": []` suppresses it. Every field name and alias is
+listed in [docs/ELEMENT_REFERENCE.md](docs/ELEMENT_REFERENCE.md).
+
+## Normalization
+
+What small models actually send, and what happens:
+
+| The model sends | The builder does |
+|---|---|
+| `{"request": {...}}`, `{"card": {...}}`, a JSON string, a fenced block, prose around JSON, `{"name":..., "arguments": "..."}` | Unwraps and parses it |
+| Adaptive Card JSON: `AdaptiveCard`, `TextBlock` with `size`/`weight`, `Container`, `ColumnSet`, `FactSet`, `Input.ChoiceSet` + `style: expanded`, `Action.Submit`, `Table` rows/cells, `RichTextBlock` | Translates it; large/bold text becomes a heading, subtle/small text a note |
+| Type names like `Dropdown`, `RadioGroup`, `TextArea`, `EmailField`, `DatePicker`, `Switch`, `kpi`, `hbar`, `RevenueBarGraph`, `chekbox` | Resolves aliases, typos and keywords (and implied settings: radio, multiline, email format…) |
+| No `type`, or an unknown one | Infers it from the fields (`options` → choice, `rows` → table, image URL → image…) |
+| `size`, `color`, `weight`, `spacing`, `width`, `style`… | Ignores styling (reported), but uses it as a hint where it carries meaning |
+| `question`, `prompt`, `isRequired`, `mandatory`, `choices`, `default`, `maxLength`… | Maps field aliases; `name` becomes the id if it looks like one, else the label |
+| `description`, `subtitle`, `caption`, `note` on any element | Shows the text instead of dropping it |
+| `"1,200"`, `"$1.2M"`, `"75%"`, `"(40)"`, `"4.5/5"`, `"12 GB"`; `"yes"`, `"Required"`, `1` | Parses numbers and booleans |
+| `"March 5, 2026"`, `"03/15/2026"`, `"2026/03/05"`; `"9am"`, `"2:30 PM"`, `"21h30"` | Converts to `YYYY-MM-DD` / `HH:MM`; ambiguous dates follow `BuilderConfig(day_first=...)` and warn |
+| Options as strings, `"A, B, C"`, `{title: value}`, `{"s": "Small"}`, `[{"id", "label"}]`, `[[title, value]]` | Normalizes options; defaults match case-insensitively (`"small"` → `Small`) |
+| A dropdown with no options | Asks yes/no for a yes/no question, otherwise shows a text box |
+| Facts as `"Key: Value"` strings, pairs, `{label, value}` objects, or inline keys | Builds a fact set |
+| Tables as records, lists with a header row, ragged rows, `{column: [values]}`, markdown tables | Builds a table; nothing is dropped, blanks show as `—` |
+| Charts as `{label: n}`, `[{label, value}]`, `[[label, n]]`, `labels` + `values`, Chart.js `datasets`, records with numeric fields | Builds series; picks grouped bars for several series, sorts line x values |
+| Line chart over categories, pie with negatives or several series | Switches to a bar chart (reported) |
+| Series with different categories, non-numeric values | Shows a table with blanks rather than inventing zeros |
+| Adjacent single `metric`, `button`, `badge` or `column` elements | Merges them into one row |
+| `www.example.com`, `//cdn…`, spaces in URLs | Normalizes to https; `javascript:`, `data:`, `file:` and relative URLs are dropped with a warning |
+| Buttons without data | Adds `{"action": "<label slug>"}` so the app can tell them apart; data keys that would overwrite answers are removed |
+| Duplicate or invalid ids | Sanitizes and de-duplicates (reported in `metadata.inputIds`) |
+
+Nothing is guessed that would change meaning: an unmatched default, an
+unreadable date ("next Tuesday", "March 5" with no year), an out-of-range
+value, or a bad URL is left out and reported in `metadata.warnings`, which
+is also summarized in `message` so the model can decide whether to retry.
+
+## Visual design
+
+The design lives in [src/adaptive_card_tools/theme.py](src/adaptive_card_tools/theme.py). Meaning is carried by
+typography, text colour and separators, which every host renders:
+
+- Header: large title, subtle subtitle, status badge aligned right.
+- `metrics`: big-number tiles with ▲/▼ changes in green/red (`lower_is_better` flips colours).
+- Charts in the portable profile: label | bar | value rows drawn with block
+  glyphs, with exact values and pie percentages as text. Progress bars have a
+  track. Ratings show stars plus the exact value.
+- Tables: shaded bold header row, numeric columns right-aligned, content-based column widths.
+- Sections: bold title, a separator at the top level. Columns: tiles.
+- Buttons: the primary action is `positive`; reject/delete/decline are `destructive`.
+
+Container backgrounds (tiles, table header shading) depend on the host config.
+They show in Teams and with the recommended config, and fall back to plain
+columns elsewhere, so nothing is lost. For the JS SDK, pass
+`adaptive_card_tools.host_config()` to `new AdaptiveCards.HostConfig(...)` and
+include [examples/card-theme.css](examples/card-theme.css) for buttons and inputs; see
+[examples/frontend.js](examples/frontend.js).
+
+## Renderer profiles
+
+`portable` (default) emits core Adaptive Cards 1.5 only. `microsoft` emits
+native extensions (charts, `Badge`, `Rating`, `ProgressBar`, `ProgressRing`,
+`Input.Rating`) with a core fallback on each.
+
+```python
+from adaptive_card_tools import BuilderConfig, make_adaptive_card_tool
+
+card_tool = make_adaptive_card_tool(BuilderConfig(
+    profile="microsoft",
+    native_types=("Badge", "Rating", "Chart.Line"),  # optional allow-list
+    available_width_px=1200,
+    day_first=False,
+))
+```
+
+Native charts are only used when the data can be drawn exactly; series with
+gaps or non-numeric values use the table fallback. The model cannot select
+the profile, styling or schema version.
+
+## Result envelope
+
+```python
+{
+  "status": "successful",          # or "error"
+  "suggestedWidth": "60%",         # 50%, 60%, 80%, 100% or "100%+" (a signal, not CSS)
+  "response": {...},               # the card; forward unchanged to the renderer
+  "message": "Card built and ready to display. ...",  # for the model
+  "metadata": {
+    "profile": "portable", "schemaVersion": "1.5",
+    "inputIds": ["name", "day", "size"],
+    "choiceValues": {"size": [{"title": "1-10", "value": "1-10"}, ...]},
+    "layout": {"widthPercent": 60, "estimatedMinWidthPx": 480, "overflow": "none", ...},
+    "warnings": [],                # content left out or reinterpreted
+    "normalizations": [...]        # every harmless repair
+  }
+}
+```
+
+On error, `response` and `message` explain the problem and `errors` holds
+`{path, code, message}`. Errors happen only for unreadable JSON, a request
+with nothing to display, or configured limits (bytes, depth, nodes,
+elements, output size).
+
+Width is an estimate from structural minima (columns add, stacked content
+takes the widest); the frontend adapter in `examples/frontend.js` applies it
+and scrolls when needed.
+
+## Application responsibilities
+
+- Render `response` unchanged; handle `Action.Submit` and `Action.OpenUrl` in the frontend.
+- Validate and authorize every submission on the server. Generated ids are
+  deterministic for the same request, not stable across edits; give explicit
+  ids when your backend expects particular keys.
+- URLs are validated (http/https, no credentials) but never fetched or allow-listed.
+- No network access, randomness, clock or LLM call happens in the build path.
+
+## Examples
+
+[src/adaptive_card_tools/examples.py](src/adaptive_card_tools/examples.py) has a product comparison, expense form,
+weekly review, approval, questionnaire, KPI dashboard, and a deliberately
+messy small-model call. `python examples/export_examples.py` regenerates
+[examples/generated](examples/generated) (spec, tool call, and both profile outputs) and the docs.
+
+## Test and build
+
+```bash
+PYTHONPATH=src python -m unittest discover -s tests -v       # core suite, stdlib only
+python -m pip install -e '.[test,integration]'                # + official schema, LangChain, ADK
+python -m unittest discover -s tests -v
+python -m pip install -e '.[dev]' && python -m build && python -m twine check dist/*
+```
+
+See [docs/VALIDATION.md](docs/VALIDATION.md) for what has been verified.
+
+## Sources
+
+- [Adaptive Cards documentation and schema explorer](https://adaptivecards.microsoft.com/)
+- [Official core schema](https://adaptivecards.microsoft.com/schemas/adaptive-card.json)
+- [Microsoft host features, ratings and responsive layouts](https://learn.microsoft.com/en-us/microsoftteams/platform/task-modules-and-cards/cards/cards-format)
+- [Google ADK function tools](https://adk.dev/tools-custom/function-tools/)
+- [LangChain tools](https://docs.langchain.com/oss/python/langchain/tools)

agentic_genui_tools-0.2.0/README.md

@@ -0,0 +1,258 @@
+# adaptive-card-tools
+
+Build modern, deterministic Adaptive Cards from small, forgiving agent tool
+calls. The model describes *what* to show; Python repairs the request,
+applies a consistent visual design, and returns a complete card.
+
+Designed for small models such as GPT-4.1 mini and Gemini 2.5 Flash:
+
+- **Short prompt.** The tool description is ~1,200 tokens of examples, not a
+  schema manual (it was ~8,500 in 0.1.x).
+- **Repair, don't reject.** Wrong type names, Adaptive Card JSON, style keys,
+  aliases, typos, strings for numbers and dates, odd option shapes, wrapped
+  or broken JSON: all are interpreted. Errors are reserved for requests that
+  are unreadable, empty, or over a safety limit.
+- **Accurate.** Repairs change the *form* of a value, never its *facts*. Text
+  is never rewritten or truncated, numbers are parsed but never estimated,
+  missing chart points are not filled with zeros, and anything that can't be
+  read exactly is left out with a warning. Every repair is listed in metadata.
+- **Modern and stable.** The model never chooses styling. Every card gets the
+  same hierarchy (title, status badge, KPI tiles, data bars, shaded table
+  headers, primary/destructive buttons) built from primitives that render on
+  every Adaptive Cards host.
+
+Python 3.10+, no runtime dependencies. Import name: `adaptive_card_tools`.
+
+Rendered with Microsoft's `adaptivecards` JS SDK. 0.2 with `host_config()` and
+`examples/card-theme.css` (the middle card is the deliberately messy call from
+`examples.py`):
+
+![0.2 output](docs/images/after-0.2.png)
+
+<details><summary>0.1 output for comparison</summary>
+
+![0.1 output](docs/images/before-0.1.png)
+
+</details>
+
+## Install and use
+
+```bash
+python -m pip install .
+```
+
+```python
+from adaptive_card_tools import build_adaptive_card
+
+result = build_adaptive_card({
+    "title": "Weekly sales",
+    "subtitle": "Week ending 11 Sep 2026",
+    "status": "On track",
+    "elements": [
+        {"type": "metrics", "items": [
+            {"label": "Revenue", "value": "$48,200", "change": "+12%"},
+            {"label": "Orders", "value": "312", "change": "-3%"}]},
+        {"type": "chart", "chart_type": "bar", "title": "Revenue by region",
+         "data": {"North": 18200, "South": 12100, "West": 17900}},
+    ],
+})
+result["status"]          # "successful"
+result["response"]        # the Adaptive Card JSON for your frontend
+result["message"]         # a short instruction for the model
+```
+
+## Add to an agent
+
+The function is a plain Python tool; its docstring is the model's prompt
+(see [docs/TOOL_DOCSTRING.md](docs/TOOL_DOCSTRING.md)).
+
+```python
+# Google ADK
+from google.adk.agents import Agent
+from adaptive_card_tools import build_adaptive_card
+
+agent = Agent(name="card_assistant", model="gemini-2.5-flash", tools=[build_adaptive_card],
+              instruction="When the answer is a form, summary, comparison, dashboard, approval, "
+                          "table or chart, call build_adaptive_card once with the complete content.")
+```
+
+```python
+# LangChain, with the rich schema (element types as an enum, which small models follow well)
+from langchain.agents import create_agent
+from langchain_core.tools import StructuredTool
+from adaptive_card_tools import build_adaptive_card, tool_schema
+
+schema = tool_schema()
+card_tool = StructuredTool.from_function(build_adaptive_card, name=schema["name"],
+                                         description=schema["description"], args_schema=schema["parameters"])
+agent = create_agent(model="openai:gpt-4.1-mini", tools=[card_tool])
+```
+
+If a provider rejects a free-form object parameter (some Gemini setups and
+strict tool modes do), use `build_adaptive_card_json(request_json: str)`. Its
+parser also repairs single quotes, trailing commas, comments, Python
+`True/None`, code fences, prose around the JSON, and unclosed brackets.
+
+`make_adaptive_card_tool(BuilderConfig(...), json_input=False)` returns a tool
+bound to your settings. `describe_adaptive_card(type)` is an optional helper
+tool; small models rarely need it.
+
+## What the model writes
+
+```json
+{"title": "Book a demo", "elements": [
+  {"type": "text", "text": "Pick a time that suits you."},
+  {"type": "text_input", "id": "name", "label": "Full name", "required": true},
+  {"type": "date_input", "id": "day", "label": "Preferred day"},
+  {"type": "choice", "id": "size", "label": "Team size", "options": ["1-10", "11-50", "51+"]}],
+ "submit_label": "Request demo"}
+```
+
+| Group | Types |
+|---|---|
+| Content | `heading`, `text` (markdown), `note`, `list`, `facts`, `table`, `badge`, `image`, `images`, `media` |
+| Data | `metrics` (KPI tiles), `chart` (`bar`, `horizontal_bar`, `line`, `pie`, `donut`, `stacked_bar`, `grouped_bar`, `gauge`), `progress`, `rating` |
+| Layout | `section`, `columns`, `divider`, `buttons` |
+| Inputs | `text_input`, `number_input`, `date_input`, `time_input`, `datetime_input`, `choice`, `checkbox`, `rating_input` |
+
+Card-level fields: `title`, `subtitle`, `status` (a coloured badge next to the
+title), `elements`, `submit_label`, `buttons`. Forms get a Submit button
+automatically; `"buttons": []` suppresses it. Every field name and alias is
+listed in [docs/ELEMENT_REFERENCE.md](docs/ELEMENT_REFERENCE.md).
+
+## Normalization
+
+What small models actually send, and what happens:
+
+| The model sends | The builder does |
+|---|---|
+| `{"request": {...}}`, `{"card": {...}}`, a JSON string, a fenced block, prose around JSON, `{"name":..., "arguments": "..."}` | Unwraps and parses it |
+| Adaptive Card JSON: `AdaptiveCard`, `TextBlock` with `size`/`weight`, `Container`, `ColumnSet`, `FactSet`, `Input.ChoiceSet` + `style: expanded`, `Action.Submit`, `Table` rows/cells, `RichTextBlock` | Translates it; large/bold text becomes a heading, subtle/small text a note |
+| Type names like `Dropdown`, `RadioGroup`, `TextArea`, `EmailField`, `DatePicker`, `Switch`, `kpi`, `hbar`, `RevenueBarGraph`, `chekbox` | Resolves aliases, typos and keywords (and implied settings: radio, multiline, email format…) |
+| No `type`, or an unknown one | Infers it from the fields (`options` → choice, `rows` → table, image URL → image…) |
+| `size`, `color`, `weight`, `spacing`, `width`, `style`… | Ignores styling (reported), but uses it as a hint where it carries meaning |
+| `question`, `prompt`, `isRequired`, `mandatory`, `choices`, `default`, `maxLength`… | Maps field aliases; `name` becomes the id if it looks like one, else the label |
+| `description`, `subtitle`, `caption`, `note` on any element | Shows the text instead of dropping it |
+| `"1,200"`, `"$1.2M"`, `"75%"`, `"(40)"`, `"4.5/5"`, `"12 GB"`; `"yes"`, `"Required"`, `1` | Parses numbers and booleans |
+| `"March 5, 2026"`, `"03/15/2026"`, `"2026/03/05"`; `"9am"`, `"2:30 PM"`, `"21h30"` | Converts to `YYYY-MM-DD` / `HH:MM`; ambiguous dates follow `BuilderConfig(day_first=...)` and warn |
+| Options as strings, `"A, B, C"`, `{title: value}`, `{"s": "Small"}`, `[{"id", "label"}]`, `[[title, value]]` | Normalizes options; defaults match case-insensitively (`"small"` → `Small`) |
+| A dropdown with no options | Asks yes/no for a yes/no question, otherwise shows a text box |
+| Facts as `"Key: Value"` strings, pairs, `{label, value}` objects, or inline keys | Builds a fact set |
+| Tables as records, lists with a header row, ragged rows, `{column: [values]}`, markdown tables | Builds a table; nothing is dropped, blanks show as `—` |
+| Charts as `{label: n}`, `[{label, value}]`, `[[label, n]]`, `labels` + `values`, Chart.js `datasets`, records with numeric fields | Builds series; picks grouped bars for several series, sorts line x values |
+| Line chart over categories, pie with negatives or several series | Switches to a bar chart (reported) |
+| Series with different categories, non-numeric values | Shows a table with blanks rather than inventing zeros |
+| Adjacent single `metric`, `button`, `badge` or `column` elements | Merges them into one row |
+| `www.example.com`, `//cdn…`, spaces in URLs | Normalizes to https; `javascript:`, `data:`, `file:` and relative URLs are dropped with a warning |
+| Buttons without data | Adds `{"action": "<label slug>"}` so the app can tell them apart; data keys that would overwrite answers are removed |
+| Duplicate or invalid ids | Sanitizes and de-duplicates (reported in `metadata.inputIds`) |
+
+Nothing is guessed that would change meaning: an unmatched default, an
+unreadable date ("next Tuesday", "March 5" with no year), an out-of-range
+value, or a bad URL is left out and reported in `metadata.warnings`, which
+is also summarized in `message` so the model can decide whether to retry.
+
+## Visual design
+
+The design lives in [src/adaptive_card_tools/theme.py](src/adaptive_card_tools/theme.py). Meaning is carried by
+typography, text colour and separators, which every host renders:
+
+- Header: large title, subtle subtitle, status badge aligned right.
+- `metrics`: big-number tiles with ▲/▼ changes in green/red (`lower_is_better` flips colours).
+- Charts in the portable profile: label | bar | value rows drawn with block
+  glyphs, with exact values and pie percentages as text. Progress bars have a
+  track. Ratings show stars plus the exact value.
+- Tables: shaded bold header row, numeric columns right-aligned, content-based column widths.
+- Sections: bold title, a separator at the top level. Columns: tiles.
+- Buttons: the primary action is `positive`; reject/delete/decline are `destructive`.
+
+Container backgrounds (tiles, table header shading) depend on the host config.
+They show in Teams and with the recommended config, and fall back to plain
+columns elsewhere, so nothing is lost. For the JS SDK, pass
+`adaptive_card_tools.host_config()` to `new AdaptiveCards.HostConfig(...)` and
+include [examples/card-theme.css](examples/card-theme.css) for buttons and inputs; see
+[examples/frontend.js](examples/frontend.js).
+
+## Renderer profiles
+
+`portable` (default) emits core Adaptive Cards 1.5 only. `microsoft` emits
+native extensions (charts, `Badge`, `Rating`, `ProgressBar`, `ProgressRing`,
+`Input.Rating`) with a core fallback on each.
+
+```python
+from adaptive_card_tools import BuilderConfig, make_adaptive_card_tool
+
+card_tool = make_adaptive_card_tool(BuilderConfig(
+    profile="microsoft",
+    native_types=("Badge", "Rating", "Chart.Line"),  # optional allow-list
+    available_width_px=1200,
+    day_first=False,
+))
+```
+
+Native charts are only used when the data can be drawn exactly; series with
+gaps or non-numeric values use the table fallback. The model cannot select
+the profile, styling or schema version.
+
+## Result envelope
+
+```python
+{
+  "status": "successful",          # or "error"
+  "suggestedWidth": "60%",         # 50%, 60%, 80%, 100% or "100%+" (a signal, not CSS)
+  "response": {...},               # the card; forward unchanged to the renderer
+  "message": "Card built and ready to display. ...",  # for the model
+  "metadata": {
+    "profile": "portable", "schemaVersion": "1.5",
+    "inputIds": ["name", "day", "size"],
+    "choiceValues": {"size": [{"title": "1-10", "value": "1-10"}, ...]},
+    "layout": {"widthPercent": 60, "estimatedMinWidthPx": 480, "overflow": "none", ...},
+    "warnings": [],                # content left out or reinterpreted
+    "normalizations": [...]        # every harmless repair
+  }
+}
+```
+
+On error, `response` and `message` explain the problem and `errors` holds
+`{path, code, message}`. Errors happen only for unreadable JSON, a request
+with nothing to display, or configured limits (bytes, depth, nodes,
+elements, output size).
+
+Width is an estimate from structural minima (columns add, stacked content
+takes the widest); the frontend adapter in `examples/frontend.js` applies it
+and scrolls when needed.
+
+## Application responsibilities
+
+- Render `response` unchanged; handle `Action.Submit` and `Action.OpenUrl` in the frontend.
+- Validate and authorize every submission on the server. Generated ids are
+  deterministic for the same request, not stable across edits; give explicit
+  ids when your backend expects particular keys.
+- URLs are validated (http/https, no credentials) but never fetched or allow-listed.
+- No network access, randomness, clock or LLM call happens in the build path.
+
+## Examples
+
+[src/adaptive_card_tools/examples.py](src/adaptive_card_tools/examples.py) has a product comparison, expense form,
+weekly review, approval, questionnaire, KPI dashboard, and a deliberately
+messy small-model call. `python examples/export_examples.py` regenerates
+[examples/generated](examples/generated) (spec, tool call, and both profile outputs) and the docs.
+
+## Test and build
+
+```bash
+PYTHONPATH=src python -m unittest discover -s tests -v       # core suite, stdlib only
+python -m pip install -e '.[test,integration]'                # + official schema, LangChain, ADK
+python -m unittest discover -s tests -v
+python -m pip install -e '.[dev]' && python -m build && python -m twine check dist/*
+```
+
+See [docs/VALIDATION.md](docs/VALIDATION.md) for what has been verified.
+
+## Sources
+
+- [Adaptive Cards documentation and schema explorer](https://adaptivecards.microsoft.com/)
+- [Official core schema](https://adaptivecards.microsoft.com/schemas/adaptive-card.json)
+- [Microsoft host features, ratings and responsive layouts](https://learn.microsoft.com/en-us/microsoftteams/platform/task-modules-and-cards/cards/cards-format)
+- [Google ADK function tools](https://adk.dev/tools-custom/function-tools/)
+- [LangChain tools](https://docs.langchain.com/oss/python/langchain/tools)