Agentic-GenUI-Tools 0.2.0__py3-none-any.whl

adaptive_card_tools/theme.py

@@ -0,0 +1,210 @@
+"""The visual design system.
+
+The model never chooses styling. Every card gets the same hierarchy from these
+helpers. Meaning is carried by typography, text colour and separators, which
+render on every Adaptive Cards host. Container backgrounds (tiles) are an
+enhancement: hosts whose config gives "emphasis" a background show tiles;
+others show the same content without a background, and nothing is lost.
+"""
+from __future__ import annotations
+
+BAR_CELLS = 20
+
+TONES = {
+    # tone: (TextBlock color, native Badge style, symbol)
+    "success": ("Good", "good", "●"),
+    "warning": ("Warning", "warning", "●"),
+    "danger": ("Attention", "attention", "●"),
+    "info": ("Accent", "informative", "●"),
+    "neutral": ("Default", "default", "●"),
+}
+
+
+def text(content: str, **props) -> dict:
+    return {"type": "TextBlock", "text": content, "wrap": True, **props}
+
+
+def card_title(content: str) -> dict:
+    return text(content, size="Large", weight="Bolder", style="heading")
+
+
+def subtitle(content: str) -> dict:
+    return text(content, isSubtle=True, spacing="None")
+
+
+def heading(content: str) -> dict:
+    return text(content, size="Medium", weight="Bolder", style="heading")
+
+
+def group_title(content: str) -> dict:
+    """Title of a section, column tile or data element."""
+    return text(content, size="Default", weight="Bolder", style="heading")
+
+
+def body(content: str) -> dict:
+    return text(content)
+
+
+def note(content: str) -> dict:
+    return text(content, size="Small", isSubtle=True)
+
+
+def spaced(element: dict, spacing: str, separator: bool = False) -> dict:
+    out = {**element, "spacing": spacing}
+    if separator:
+        out["separator"] = True
+    return out
+
+
+def row(*columns: dict, spacing: str | None = None) -> dict:
+    result = {"type": "ColumnSet", "columns": list(columns)}
+    if spacing:
+        result["spacing"] = spacing
+    return result
+
+
+def column(items: list[dict], width="stretch", **props) -> dict:
+    return {"type": "Column", "width": width, "items": items, **props}
+
+
+def badge(content: str, tone: str) -> dict:
+    color, _, symbol = TONES[tone]
+    return text(f"{symbol} {content}", size="Small", weight="Bolder", color=color)
+
+
+def badge_row(badges: list[dict]) -> dict:
+    """Several badges side by side, left-aligned."""
+    return row(*[column([b], "auto", spacing="Medium" if i else "Default") for i, b in enumerate(badges)])
+
+
+def tile(items: list[dict]) -> dict:
+    return column(items, "stretch", style="emphasis")
+
+
+def metric_tile(label: str, value: str, change: str | None, change_color: str, footnote: str | None) -> dict:
+    items = [text(label, size="Small", isSubtle=True),
+             text(value, size="ExtraLarge", weight="Bolder", spacing="None")]
+    if change:
+        items.append(text(change, size="Small", color=change_color, spacing="None"))
+    if footnote:
+        items.append(text(footnote, size="Small", isSubtle=True, spacing="None"))
+    return tile(items)
+
+
+def bar(fraction: float, *, track: bool, color: str = "Accent") -> dict:
+    """A horizontal bar drawn with block glyphs; renders on every host."""
+    filled = max(0, min(BAR_CELLS, round(fraction * BAR_CELLS)))
+    if fraction > 0 and filled == 0:
+        filled = 1
+    runs = []
+    if filled:
+        runs.append({"type": "TextRun", "text": "█" * filled, "color": color, "fontType": "Monospace"})
+    if track and BAR_CELLS - filled:
+        runs.append({"type": "TextRun", "text": "█" * (BAR_CELLS - filled), "color": color,
+                     "isSubtle": True, "fontType": "Monospace"})
+    if not runs:
+        runs.append({"type": "TextRun", "text": "▏", "color": color, "isSubtle": True, "fontType": "Monospace"})
+    return {"type": "RichTextBlock", "inlines": runs}
+
+
+def bar_row(label: str, fraction: float, value: str, label_width_px: int) -> dict:
+    return row(column([text(label, size="Small")], f"{label_width_px}px"),
+               column([bar(fraction, track=False)], "auto", verticalContentAlignment="Center"),
+               column([text(value, size="Small", weight="Bolder")], "auto"),
+               spacing="Small")
+
+
+def label_value_row(label: str, value: str) -> dict:
+    return row(column([text(label, size="Small")]), column([text(value, size="Small", weight="Bolder")], "auto"),
+               spacing="Small")
+
+
+def progress(label: str, value_text: str, fraction: float | None, color: str = "Accent") -> list[dict]:
+    items = [label_value_row(label, value_text)]
+    if fraction is not None:
+        items.append({**bar(fraction, track=True, color=color), "spacing": "None"})
+    return items
+
+
+def stars(value: float, maximum: int, caption: str) -> dict:
+    """Rounded stars for scanning; the caption always states the exact value."""
+    full = min(maximum, int(value + 0.5))
+    runs = []
+    if full:
+        runs.append({"type": "TextRun", "text": "★" * full, "color": "Warning"})
+    if maximum - full:
+        runs.append({"type": "TextRun", "text": "☆" * (maximum - full), "color": "Warning", "isSubtle": True})
+    runs.append({"type": "TextRun", "text": "  " + caption, "isSubtle": True})
+    return {"type": "RichTextBlock", "inlines": runs}
+
+
+def bullet_row(marker: str, content: str, marker_width_px: int) -> dict:
+    return row(column([text(marker, isSubtle=True)], f"{marker_width_px}px"),
+               column([text(content)], "stretch", spacing="None"), spacing="Small")
+
+
+def table(headers: list[str], rows: list[list[str]], numeric: list[bool], weights: list[int]) -> dict:
+    def cell(value: str, header=False) -> dict:
+        return {"type": "TableCell", "items": [text(value, weight="Bolder") if header else text(value)]}
+
+    columns = []
+    for is_number, weight in zip(numeric, weights):
+        definition = {"width": weight}
+        if is_number:
+            definition["horizontalCellContentAlignment"] = "Right"
+        columns.append(definition)
+    return {"type": "Table", "columns": columns, "showGridLines": True, "gridStyle": "default",
+            "rows": [{"type": "TableRow", "style": "emphasis", "cells": [cell(h, True) for h in headers]},
+                     *[{"type": "TableRow", "cells": [cell(v) for v in r]} for r in rows]]}
+
+
+def button_style(label: str, explicit: str | None, primary_available: bool) -> str | None:
+    """positive for the primary action, destructive for rejecting/deleting."""
+    if explicit:
+        return None if explicit == "default" else explicit
+    words = label.casefold()
+    if any(w in words for w in ("reject", "decline", "delete", "remove", "deny", "revoke", "terminate", "discard")):
+        return "destructive"
+    if primary_available and any(w in words for w in ("approve", "accept", "confirm", "submit", "save", "send",
+                                                      "book", "register", "sign up", "pay", "complete", "apply")):
+        return "positive"
+    return None
+
+
+def host_config() -> dict:
+    """A recommended modern host config for the Adaptive Cards JS SDK.
+
+    Cards render correctly without it; with it, tiles, tables and badges get
+    soft backgrounds and a cleaner type scale. Pass it to
+    new AdaptiveCards.HostConfig(...) in the frontend.
+    """
+    foreground = {
+        "default": {"default": "#1F2937", "subtle": "#6B7280"},
+        "dark": {"default": "#111827", "subtle": "#4B5563"},
+        "light": {"default": "#FFFFFF", "subtle": "#F3F4F6"},
+        "accent": {"default": "#2563EB", "subtle": "#BFDBFE"},
+        "good": {"default": "#15803D", "subtle": "#BBF7D0"},
+        "warning": {"default": "#B45309", "subtle": "#FDE68A"},
+        "attention": {"default": "#B91C1C", "subtle": "#FECACA"},
+    }
+    styles = {name: {"backgroundColor": color, "foregroundColors": foreground}
+              for name, color in (("default", "#FFFFFF"), ("emphasis", "#F3F4F6"), ("accent", "#EFF6FF"),
+                                  ("good", "#F0FDF4"), ("warning", "#FFFBEB"), ("attention", "#FEF2F2"))}
+    return {
+        "fontFamily": "'Segoe UI', system-ui, -apple-system, Roboto, 'Helvetica Neue', Arial, sans-serif",
+        "fontSizes": {"small": 12, "default": 14, "medium": 16, "large": 20, "extraLarge": 28},
+        "fontWeights": {"lighter": 300, "default": 400, "bolder": 600},
+        "spacing": {"small": 4, "default": 8, "medium": 16, "large": 24, "extraLarge": 32, "padding": 16},
+        "separator": {"lineThickness": 1, "lineColor": "#E5E7EB"},
+        "containerStyles": styles,
+        "imageSizes": {"small": 32, "medium": 64, "large": 160},
+        "actions": {"maxActions": 6, "spacing": "default", "buttonSpacing": 8, "actionsOrientation": "horizontal",
+                    "actionAlignment": "left", "showCard": {"actionMode": "inline", "inlineTopMargin": 16}},
+        "factSet": {"title": {"color": "default", "isSubtle": True, "weight": "default", "wrap": True, "maxWidth": 200},
+                    "value": {"color": "default", "weight": "bolder", "wrap": True}, "spacing": 12},
+        "textStyles": {"heading": {"size": "large", "weight": "bolder", "color": "default"},
+                       "columnHeader": {"size": "default", "weight": "bolder", "color": "default"}},
+        "inputs": {"label": {"inputSpacing": "small", "requiredInputs": {"weight": "bolder", "suffix": " *", "suffixColor": "attention"},
+                             "optionalInputs": {"weight": "bolder"}},
+                   "errorMessage": {"size": "small", "color": "attention"}},
+    }

adaptive_card_tools/tool.py

@@ -0,0 +1,142 @@
+"""Plain Python functions for agent tool registration.
+
+The docstring of build_adaptive_card is the prompt a model sees. It is kept
+short and example-driven for small models (GPT-4.1 mini, Gemini 2.5 Flash):
+the builder is forgiving, so the prompt teaches the happy path only.
+"""
+from typing import Callable
+
+from .builder import render_card
+from .catalog import DOCUMENTED, describe, json_schema, resolve_type
+from .normalize import BuilderConfig, Context
+
+TOOL_DOC = """Show the user a rich card: a form, summary, comparison, dashboard, approval, chart or table.
+
+Describe WHAT to show. The tool does all layout, styling and Adaptive Card JSON;
+never write Adaptive Card JSON yourself.
+
+Args:
+    request: {"title": "...", "subtitle": "...", "status": "...", "elements": [...], "submit_label": "..."}
+        Only "elements" is needed. "status" shows a coloured badge beside the title.
+
+Element types (each element is an object with a "type"):
+    heading       {"type": "heading", "text": "Summary"}
+    text          {"type": "text", "text": "Paragraph. **bold** and [links](https://example.com) work."}
+    note          {"type": "note", "text": "Small grey print."}
+    list          {"type": "list", "items": ["First", "Second"], "numbered": false}
+    facts         {"type": "facts", "facts": {"Owner": "Dana", "Due": "2026-10-01"}}
+    table         {"type": "table", "rows": [{"Item": "Laptop", "Qty": 2}, {"Item": "Mouse", "Qty": 5}]}
+    metrics       {"type": "metrics", "items": [{"label": "Revenue", "value": "$1.2M", "change": "+8%"}]}
+    badge         {"type": "badge", "text": "Approved", "tone": "success"}   tone: success|warning|danger|info|neutral
+    image         {"type": "image", "url": "https://example.com/photo.png", "alt": "Product photo"}
+    chart         {"type": "chart", "chart_type": "bar", "title": "Orders", "data": {"Jan": 120, "Feb": 150}}
+                  chart_type: bar|horizontal_bar|line|pie|donut|stacked_bar|grouped_bar|gauge
+                  several series: "series": [{"name": "2025", "data": {"Q1": 5, "Q2": 7}}, {"name": "2026", "data": {"Q1": 6, "Q2": 9}}]
+                  gauge: {"type": "chart", "chart_type": "gauge", "value": 72, "max": 100}
+    progress      {"type": "progress", "label": "Migration", "value": 70}   (a percent, or add "max")
+    rating        {"type": "rating", "value": 4.5, "count": 120}
+    divider       {"type": "divider"}
+    section       {"type": "section", "title": "Details", "elements": [...]}
+    columns       {"type": "columns", "columns": [{"title": "Basic", "elements": [...]}, {"title": "Pro", "elements": [...]}]}
+    buttons       {"type": "buttons", "buttons": [{"label": "Approve"}, {"label": "Open ticket", "url": "https://example.com/t/1"}]}
+Inputs (a Submit button is added automatically; "submit_label" renames it):
+    text_input    {"type": "text_input", "id": "email", "label": "Email", "required": true}   also: placeholder, multiline, format (email|tel|url|password)
+    number_input  {"type": "number_input", "id": "qty", "label": "Quantity", "min": 1, "max": 10}
+    date_input    {"type": "date_input", "id": "start", "label": "Start date"}   (time_input for a time)
+    choice        {"type": "choice", "id": "plan", "label": "Plan", "options": ["Basic", "Pro"]}   add "multiple": true for several answers
+    checkbox      {"type": "checkbox", "id": "terms", "label": "I agree to the terms", "required": true}
+    rating_input  {"type": "rating_input", "id": "score", "label": "How was it?"}
+
+Rules:
+1. Copy the user's text, numbers, names and options exactly. Never invent data, prices, links or images; leave out anything you don't have.
+2. Only use https links and image URLs that appear in the conversation.
+3. A button with "url" opens that link; a button without "url" submits the card.
+4. Values are flexible: "1,200", "$4.5M", "75%", "March 5, 2026" and "2pm" are all understood.
+5. One call builds the whole card. If status is "successful" the card is shown to the user: do not call again and do not repeat the card as text.
+6. If status is "error", read "message", fix the request and call once more.
+
+Example (form):
+{"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"}
+
+Example (dashboard):
+{"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}},
+  {"type": "table", "title": "Top products", "rows": [{"Product": "Desk", "Units": 84}, {"Product": "Chair", "Units": 61}]}]}
+
+Returns:
+    {"status": "successful" or "error", "message": what to do next, "response": the card for the app, ...}
+"""
+
+JSON_DOC = TOOL_DOC.replace(
+    'Args:\n    request: {', 'Args:\n    request_json: The request object below, encoded as a JSON string:\n        {', 1)
+
+
+def build_adaptive_card(request: dict) -> dict:
+    return render_card(request)
+
+
+def build_adaptive_card_json(request_json: str) -> dict:
+    return render_card(request_json)
+
+
+build_adaptive_card.__doc__ = TOOL_DOC
+build_adaptive_card_json.__doc__ = JSON_DOC
+
+
+def describe_adaptive_card(element_type: str = "") -> dict:
+    """Look up the fields and an example for one card element type (e.g. "chart", "choice").
+
+    Args:
+        element_type: An element type name. Empty returns a one-line summary of every type.
+    """
+    if not element_type:
+        return {"status": "successful", "response": {name: describe(name)["summary"] for name in DOCUMENTED}}
+    resolved = resolve_type(element_type, Context(BuilderConfig()), "$.element_type")
+    if not resolved or resolved[0] not in DOCUMENTED:
+        return {"status": "error", "response": f"Unknown element type '{element_type}'. Known types: {', '.join(DOCUMENTED)}."}
+    return {"status": "successful", "response": describe(resolved[0])}
+
+
+def make_adaptive_card_tool(config: BuilderConfig | None = None, *, json_input: bool = False) -> Callable:
+    """Create a tool function bound to developer settings (profile, width, limits).
+
+    Example: make_adaptive_card_tool(BuilderConfig(profile="microsoft")).
+    Set json_input=True for providers that need a single string parameter.
+    """
+    chosen = config or BuilderConfig()
+    if json_input:
+        def build_adaptive_card_json(request_json: str) -> dict:
+            return render_card(request_json, config=chosen)
+        function = build_adaptive_card_json
+        function.__doc__ = JSON_DOC
+    else:
+        def build_adaptive_card(request: dict) -> dict:
+            return render_card(request, config=chosen)
+        function = build_adaptive_card
+        function.__doc__ = TOOL_DOC
+    return function
+
+
+def tool_schema(*, json_input: bool = False) -> dict:
+    """Provider-neutral name, description and JSON Schema parameters.
+
+    The object form lists element types as an enum, which helps small models
+    choose valid types. It uses $defs/$ref; for providers without $ref support
+    use json_input=True (a single string parameter).
+    """
+    if json_input:
+        return {"name": "build_adaptive_card_json", "description": JSON_DOC,
+                "parameters": {"type": "object", "properties": {"request_json": {
+                    "type": "string", "description": "JSON string of the card request object."}},
+                    "required": ["request_json"], "additionalProperties": False}}
+    return {"name": "build_adaptive_card", "description": TOOL_DOC, "parameters": json_schema()}
+
+
+# Backward-compatible explicit name.
+build_adaptive_card_object = build_adaptive_card

agentic_genui_tools-0.2.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,13 @@
+adaptive_card_tools/__init__.py,sha256=w1w72R4p-fMPurIQB2-LMSRcV2KseSzj7xA6uAveRr0,602
+adaptive_card_tools/builder.py,sha256=ewtHvt4x5T_yrKbK9lYP8zuChKRo2Uu2-tUqR9bl5-8,106753
+adaptive_card_tools/catalog.py,sha256=4F3aTWSm8Fx8ISqFT_6k1c65Ak2fSeM1Ikekq7-dQzY,33678
+adaptive_card_tools/examples.py,sha256=VgA6jtU49eky6-SXvZbImb_pcUXMEjZPimYNFW2KIGM,13660
+adaptive_card_tools/normalize.py,sha256=RK7kKiEdd72n65nuZUMFE2KaiqU8ZQRT7IymhniEx2g,23839
+adaptive_card_tools/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+adaptive_card_tools/theme.py,sha256=bij9s2K84eeVdXzWgQj3d3bY1run0Tbx5pOsLfBf-FA,9427
+adaptive_card_tools/tool.py,sha256=_n7FffRzYuS-KKS5uNTFWRNEJU0UFNMrxuIgQi-BUlQ,8036
+agentic_genui_tools-0.2.0.dist-info/licenses/LICENSE,sha256=yA-1fsPiIyj-pW1akix_jSZLE6UBiO1sN6iDGeV_6oM,1089
+agentic_genui_tools-0.2.0.dist-info/METADATA,sha256=sTUgCrJ5VrSRIu_T_s4bUHiF-MHezr6w_fUmuOdQ73E,14771
+agentic_genui_tools-0.2.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+agentic_genui_tools-0.2.0.dist-info/top_level.txt,sha256=t7F0jO9ANAnHXhXw7KIjVdIle3pl5k9_B3-iJ5peLgw,20
+agentic_genui_tools-0.2.0.dist-info/RECORD,,

agentic_genui_tools-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+