axiom-coding-agent-setup 1.0.10 → 1.0.11

package/.agents/skills/developing-with-streamlit/skills/using-streamlit-markdown/SKILL.md

@@ -0,0 +1,207 @@
+---
+name: using-streamlit-markdown
+description: Covers all Markdown features in Streamlit including GitHub-flavored syntax plus Streamlit extensions like colored text, badges, Material icons, and LaTeX. Use when formatting text, labels, tooltips, or any text-rendering element.
+license: Apache-2.0
+---
+
+# Using Markdown in Streamlit
+
+Streamlit supports Markdown throughout its API—in `st.markdown()`, widget labels, help tooltips, metrics, `st.table()` cells, and more. Beyond standard GitHub-flavored Markdown, Streamlit adds colored text, badges, icons, and LaTeX.
+
+## Quick reference
+
+| Feature | Syntax | Example | Works in labels |
+|---------|--------|---------|--------|
+| Bold | `**text**` | `**Bold**` | ✓ |
+| Italic | `*text*` | `*Italic*` | ✓ |
+| Strikethrough | `~text~` | `~Strikethrough~` | ✓ |
+| Inline code | `` `code` `` | `` `variable` `` | ✓ |
+| Code block | ` ```lang...``` ` | ` ```python...``` ` | ✗ |
+| Link | `[text](url)` | `[Streamlit](https://streamlit.io)` | ✓ |
+| Image | `![alt](path)` | `![Logo](logo.png)` | ✓ |
+| Heading | `# ` to `###### ` | `## Section` | ✗ |
+| Blockquote | `> text` | `> Note` | ✗ |
+| Horizontal rule | `---` | `---` | ✗ |
+| Unordered list | `- item` | `- First`<br>`- Second` | ✗ |
+| Ordered list | `1. item` | `1. First`<br>`2. Second` | ✗ |
+| Task list | `- [ ]` / `- [x]` | `- [x] Done`<br>`- [ ] Todo` | ✗ |
+| Table | `\| a \| b \|` | `\| H1 \| H2 \|`<br>`\|--\|--\|` | ✗ |
+| Emoji | Direct or shortcode | `🎉` or `:tada:` | ✓ |
+| Streamlit logo | `:streamlit:` | `:streamlit:` | ✓ |
+| Material icon | `:material/icon_name:` | `:material/check_circle:` | ✓ |
+| Colored text | `:color[text]` | `:red[Error]` | ✓ |
+| Colored background | `:color-background[text]` | `:blue-background[Info]` | ✓ |
+| Badge | `:color-badge[text]` | `:green-badge[Success]` | ✓ |
+| Small text | `:small[text]` | `:small[footnote]` | ✓ |
+| LaTeX (inline) | `$formula$` | `$ax^2 + bx + c$` | ✓ |
+| LaTeX (block) | `$$formula$$` | `$$\int_0^1 x^2 dx$$` | ✗ |
+
+## Where Markdown works
+
+Markdown is supported in most places where text is rendered. Streamlit has three levels of markdown support:
+
+**Full Markdown** — All syntax shown in the table above:
+- `st.markdown()`, `st.write()`, `st.caption()`, `st.info()`, `st.warning()`, `st.error()`, `st.success()`, `st.table` cells and headers, tooltips (`help` parameter)
+
+**Label subset** — Inline formatting only (see table above). Block elements (e.g. headings, lists, tables) are silently stripped:
+- Widget and element labels (`st.button`, `st.checkbox`, `st.radio`, `st.expander`, `st.page_link`, etc.), `st.radio` and `st.select_slider` options, `st.tabs` names, `st.metric` label/value/delta, `st.title`, `st.header`, `st.subheader`, `st.image` caption, `st.dialog` title, `st.progress`, `st.spinner`.
+
+**No Markdown** — Text displays literally:
+- `st.text()`, `st.json()`, `st.dataframe()` / `st.data_editor()` cells, `st.selectbox` / `st.multiselect` options, input placeholders, `st.Page` titles, chart/map labels
+
+## GitHub-flavored Markdown
+
+Standard GFM syntax works as expected. Headings automatically get anchor links for navigation.
+
+~~~python
+st.markdown("""
+# Heading
+
+**Bold**, *italic*, ~~strikethrough~~, `inline code`, [links](url)
+
+- Unordered list
+- [x] Task list
+
+| Column | Column |
+|--------|--------|
+| Cell   | Cell   |
+
+> Blockquote
+
+```python
+code_block = "with syntax highlighting"
+```
+""")
+~~~
+
+## Colored text, backgrounds, and badges
+
+```python
+st.markdown(":red[Error] and :green[Success]")  # Colored text
+st.markdown(":blue-background[Highlighted]")     # Colored background
+st.markdown(":green-badge[Active] :red-badge[Inactive]")  # Inline badges
+```
+
+**Available colors:** `red`, `orange`, `yellow`, `green`, `blue`, `violet`, `gray`/`grey`, `rainbow`, `primary`
+
+Note: `rainbow` is not supported for backgrounds or badges. Standalone badges also available via `st.badge()`.
+
+## Material icons
+
+Use Google Material Symbols with `:material/icon_name:` syntax. Find icons at [fonts.google.com/icons](https://fonts.google.com/icons)
+
+```python
+st.markdown(":material/check_circle: Complete")
+```
+
+Material icons also work in `icon` parameters across many elements (`st.button`, `st.expander`, `st.info`, etc.).
+
+## Emojis
+
+Both Unicode emojis (preferred) and shortcodes work.
+
+```python
+st.markdown("Hello! 👋 :+1: :tada: :streamlit:")
+```
+
+**Note:** Material icons are preferred over emojis for a more professional look.
+
+## LaTeX math
+
+Single `$` for inline, double `$$` for display mode. Inline math requires non-whitespace after `$` to avoid conflicts with currency (e.g., "$5" won't be parsed as math).
+
+```python
+# Inline math
+st.markdown("The quadratic formula is $x = \\frac{-b \\pm \\sqrt{b^2-4ac}}{2a}$")
+
+# Display math (centered, larger)
+st.markdown("""
+$$
+\\sum_{i=1}^{n} x_i = x_1 + x_2 + ... + x_n
+$$
+""")
+```
+
+## Images in Markdown
+
+```python
+st.markdown("![Alt text](https://example.com/image.png)")
+st.button("![Logo](app/static/logo.png) Click me")  # Image as icon in label
+```
+
+In labels, images display as icons with max height equal to font height.
+
+## Markdown in element labels
+
+Widgets, containers, and other elements support Markdown in their labels (using the label subset).
+
+```python
+st.radio(":material/palette: Choose **color**", [":red-background[Red]", ":blue-background[Blue]", ":green-background[Green]"])
+tab1, tab2 = st.tabs([":material/home: Home", ":material/settings: Settings"])
+st.metric(label=":material/attach_money: Revenue", value=":green[$1.2M]", delta=":material/trending_up: 12%")
+```
+
+## Escaping special characters
+
+Use backslash to show literal characters: `\\[`, `\\*`, `1\\.`
+
+```python
+st.markdown(":blue[Array: \\[1, 2, 3\\]]")
+st.button("1\\. Not a list")
+```
+
+## Markdown in st.table
+
+`st.table()` renders Markdown in cells and headers.
+
+```python
+st.table({
+    "**Name**": "Alice",
+    "**Status**": ":green-badge[Active]",
+    "**Role**": ":material/shield: Admin"
+})
+```
+
+## Combining features
+
+Mix multiple features for rich formatting.
+
+```python
+st.markdown("""
+### :material/rocket: Launch status
+
+| Phase | Status | Notes |
+|-------|--------|-------|
+| Build | :green-badge[Complete] | All tests passing |
+| Deploy | :orange-badge[In Progress] | ETA: 2 hours |
+| Monitor | :gray-badge[Pending] | Waiting on deploy |
+
+:small[Last updated: just now]
+""")
+```
+
+## st.markdown - text alignment and width
+
+Control layout with `text_alignment` and `width` parameters.
+
+```python
+st.markdown("Centered heading", text_alignment="center")  # left, center, right, justify
+st.markdown("Content width only", width="content")  # stretch, content, or pixels (e.g. 400)
+```
+
+## HTML (use very sparingly!)
+
+Mix Markdown with HTML using `unsafe_allow_html=True`. For pure HTML without markdown processing, use `st.html()` instead.
+
+```python
+st.markdown("**Status:** <span style='color: coral'>Custom styled</span>", unsafe_allow_html=True)
+st.html("<div class='custom'>Pure HTML content</div>")
+```
+
+## References
+
+- [st.markdown](https://docs.streamlit.io/develop/api-reference/text/st.markdown)
+- [st.latex](https://docs.streamlit.io/develop/api-reference/text/st.latex)
+- [GitHub-flavored Markdown spec](https://github.github.com/gfm)
+- [Material Symbols](https://fonts.google.com/icons)
+- [KaTeX supported functions](https://katex.org/docs/supported.html)

package/.agents/skills/developing-with-streamlit/skills/using-streamlit-session-state/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: using-streamlit-session-state
+description: Using st.session_state to manage state across Streamlit reruns. Use when persisting data, handling widget state, implementing callbacks, or debugging state issues. Covers initialization patterns, widget-state association, and common gotchas.
+license: Apache-2.0
+---
+
+# Using Streamlit session state
+
+Streamlit reruns scripts top-to-bottom on every interaction. Without session state, variables reset each time. Use `st.session_state` to persist values across reruns.
+
+## Basic usage
+
+Session state is a dictionary-like object supporting attribute and bracket notation:
+
+```python
+# Initialize with setdefault (preferred)
+st.session_state.setdefault("count", 0)
+
+# Alternative: check before setting
+if "count" not in st.session_state:
+    st.session_state.count = 0
+
+# Read
+current = st.session_state.count
+
+# Update
+st.session_state.count += 1
+st.session_state["count"] = 5  # Bracket notation also works
+
+# Delete
+del st.session_state.count
+```
+
+**Accessing uninitialized keys raises `KeyError`.** Use `st.session_state.get("key", default)` for safe access.
+
+## Widget-state association
+
+Every widget with a `key` parameter automatically syncs to session state:
+
+```python
+name = st.text_input("Name", key="user_name")
+# st.session_state.user_name contains the same value as `name`
+```
+
+## Callbacks
+
+Callbacks execute **before** the script reruns, allowing immediate state changes. Use `on_change` or `on_click` with optional `args` and `kwargs`:
+
+```python
+def increment(amount):
+    st.session_state.count += amount
+
+st.button("Add 5", on_click=increment, args=(5,))
+```
+
+Access a widget's value in its own callback via `st.session_state.key`, not the return variable.
+
+## Initialization patterns
+
+Initialize all state at the top of your app for clarity:
+
+```python
+st.session_state.setdefault("user", None)
+st.session_state.setdefault("page", "home")
+st.session_state.setdefault("filters", {})
+```
+
+## Multipage state
+
+Widgets are NOT stateful across pages. Their values reset when navigating between pages.
+
+### Sharing state
+
+Use session state variables (not widget keys) to share data:
+
+```python
+# Page 1: Store value
+st.session_state.selected_user = st.selectbox("User", users)
+
+# Page 2: Read stored value
+if "selected_user" in st.session_state:
+    st.write(f"Selected: {st.session_state.selected_user}")
+```
+
+### Shared widgets pattern
+
+Put common widgets in the entrypoint file (before `nav.run()`):
+
+```python
+# app.py (entrypoint)
+with st.sidebar:
+    st.session_state.theme = st.selectbox("Theme", ["Light", "Dark"])
+
+nav = st.navigation(pages)
+nav.run()
+```
+
+## Common mistakes
+
+### Module-level mutable state
+
+```python
+# BAD: In imported modules, this is shared across ALL users
+# utils.py
+cache = {}  # Persists across reruns AND users!
+
+# GOOD: Use session state for per-user data
+st.session_state.setdefault("cache", {})
+```
+
+### Modifying state after widget creation
+
+Cannot assign to a widget's state after the widget has rendered:
+
+```python
+st.slider("Value", key="my_slider")
+st.session_state.my_slider = 50  # Raises StreamlitAPIException!
+```
+
+### Mixing `value` parameter and session state
+
+Don't set both—it causes warnings:
+
+```python
+# BAD: Conflicting sources
+st.session_state.setdefault("name", "Alice")
+st.text_input("Name", value="Bob", key="name")  # Warning!
+
+# GOOD: Use one or the other
+st.session_state.setdefault("name", "Alice")
+st.text_input("Name", key="name")
+```
+
+## Session characteristics
+
+- **Per-user, per-tab**: Each browser tab has its own session
+- **Temporary**: Lost when tab closes or server restarts
+- **Not suitable for persistence**: Use databases for permanent storage
+
+## References
+
+- [st.session_state API](https://docs.streamlit.io/develop/api-reference/caching-and-state/st.session_state)
+- [Session State concepts](https://docs.streamlit.io/develop/concepts/architecture/session-state)
+- [Widget behavior](https://docs.streamlit.io/develop/concepts/architecture/widget-behavior)

package/.agents/skills/developing-with-streamlit/templates/.gitattributes

@@ -0,0 +1,3 @@
+# Mark generated/vendored files so they're collapsed in GitHub PR diffs
+**/uv.lock linguist-generated
+**/static/*.ttf linguist-generated

package/.agents/skills/developing-with-streamlit/templates/apps/README.md

@@ -0,0 +1,188 @@
+# Streamlit Dashboard App Templates
+
+This directory contains ready-to-use dashboard templates for Streamlit. Each template demonstrates best practices for building data-driven dashboards with modern UI patterns.
+
+## Available Templates
+
+### Public Demo Templates
+
+These templates are based on official Streamlit demo apps and work out of the box:
+
+| Template | Description | Key Features |
+|----------|-------------|--------------|
+| **dashboard-seattle-weather** | Weather data exploration dashboard | `st.metric`, `st.pills`, `st.altair_chart`, year comparison |
+| **dashboard-stock-peers** | Stock peer analysis and comparison | `st.multiselect`, normalized charts, peer average calculation |
+| **dashboard-stock-peers-snowflake** | Same as above but using Snowflake | `st.connection("snowflake")`, synthetic stock data in SQL |
+
+### Analytics Dashboard Templates
+
+These templates demonstrate common dashboard patterns with synthetic data. Replace the data generation functions with your actual data sources:
+
+| Template | Description | Key Features |
+|----------|-------------|--------------|
+| **dashboard-metrics** | Core metrics dashboard with KPIs | Chart/table toggle, `st.popover` filters, TIME_RANGES (1M/6M/1Y/QTD/YTD/All) |
+| **dashboard-metrics-snowflake** | Same as above but using Snowflake | `st.connection("snowflake")`, SQL-based data generation |
+| **dashboard-feature-usage** | API endpoint usage analytics | Segmented control, starter kits, normalization toggle, rolling averages |
+| **dashboard-companies** | Company leaderboard with drill-down | Interactive dataframe, sparkline columns, growth scores |
+| **dashboard-compute** | Resource consumption monitoring | `@st.fragment`, `st.popover` filters, TIME_RANGES, line/bar toggle |
+| **dashboard-compute-snowflake** | Same as above but using Snowflake | `st.connection("snowflake")`, SQL-based data generation |
+
+## Quick Start
+
+### Run a Template Locally
+
+```bash
+# Navigate to a template directory
+cd templates/apps/dashboard-metrics
+
+# Install dependencies with uv
+uv pip install -e .
+
+# Run the app
+uv run streamlit run streamlit_app.py
+```
+
+## Template Structure
+
+Each template follows this structure:
+
+```
+dashboard-{name}/
+├── streamlit_app.py    # Main application code
+└── pyproject.toml      # Dependencies and metadata
+```
+
+## Canonical Patterns
+
+When creating new templates or adapting existing ones, follow these patterns for consistency.
+
+### Page Configuration
+
+Always set page config as the first Streamlit call, with `layout="wide"` and a Material icon:
+
+```python
+st.set_page_config(
+    page_title="My Dashboard",
+    page_icon=":material/monitoring:",
+    layout="wide",
+)
+```
+
+### Constants
+
+Use these standard constant names:
+
+```python
+TIME_RANGES = ["1M", "6M", "1Y", "QTD", "YTD", "All"]
+CHART_HEIGHT = 300  # Standard chart height in pixels
+```
+
+### Time Range Filtering
+
+All dashboard templates that support time filtering use the same `filter_by_time_range` function:
+
+```python
+def filter_by_time_range(df: pd.DataFrame, x_col: str, time_range: str) -> pd.DataFrame:
+    """Filter dataframe by time range."""
+    if time_range == "All" or df.empty:
+        return df
+
+    df = df.copy()
+    df[x_col] = pd.to_datetime(df[x_col])
+    max_date = df[x_col].max()
+
+    if time_range == "1M":
+        min_date = max_date - timedelta(days=30)
+    elif time_range == "6M":
+        min_date = max_date - timedelta(days=180)
+    elif time_range == "1Y":
+        min_date = max_date - timedelta(days=365)
+    elif time_range == "QTD":
+        quarter_month = ((max_date.month - 1) // 3) * 3 + 1
+        min_date = pd.Timestamp(date(max_date.year, quarter_month, 1))
+    elif time_range == "YTD":
+        min_date = pd.Timestamp(date(max_date.year, 1, 1))
+    else:
+        return df
+
+    return df[df[x_col] >= min_date]
+```
+
+### Popover Filters
+
+Compact filter controls using `st.popover`:
+
+```python
+with st.popover("Filters", type="tertiary"):
+    line_options = st.pills("Lines", ["Daily", "7-day MA"], selection_mode="multi")
+    time_range = st.segmented_control("Time range", TIME_RANGES, default="All")
+```
+
+### Page Header with Reset Button
+
+```python
+def render_page_header(title: str):
+    """Render page header with title and reset button."""
+    with st.container(
+        horizontal=True, horizontal_alignment="distribute", vertical_alignment="center"
+    ):
+        st.markdown(title)
+        if st.button(":material/restart_alt: Reset", type="tertiary"):
+            st.session_state.clear()
+            st.rerun()
+```
+
+### Independent Widget Updates with @st.fragment
+
+```python
+@st.fragment
+def metric_card():
+    with st.container(border=True):
+        # This widget updates independently without full page rerun
+        ...
+```
+
+### Snowflake Column Normalization
+
+Snowflake returns uppercase column names. Always normalize after queries:
+
+```python
+df = conn.query(query)
+df.columns = df.columns.str.lower()
+```
+
+### Snowflake Connection Error Handling
+
+```python
+try:
+    get_snowflake_connection()
+except Exception as e:
+    st.error(f"Failed to connect to Snowflake: {e}")
+    st.info(
+        "Make sure you have configured your Snowflake connection in "
+        "`.streamlit/secrets.toml` or via environment variables."
+    )
+    st.stop()
+```
+
+### Data Loading with Caching
+
+```python
+@st.cache_data(ttl=3600)
+def load_metric_data() -> pd.DataFrame:
+    """Load metric data. Replace with your actual data source."""
+    # Replace this with:
+    # - Snowflake query via st.connection("snowflake")
+    # - API call
+    # - Database query
+    return generate_synthetic_data()
+```
+
+## Dependencies
+
+All templates require Python >=3.11 and use:
+- `snowflake-connector-python>=3.3.0` (required — `streamlit[snowflake]` silently skips this on Python 3.12+)
+- `streamlit[snowflake]>=1.54.0`
+- `altair>=5.5.0`
+- `pandas>=2.2.3`
+- `numpy>=1.26.0`

package/.agents/skills/developing-with-streamlit/templates/apps/dashboard-companies/pyproject.toml

@@ -0,0 +1,12 @@
+[project]
+name = "dashboard-companies"
+version = "1.0.0"
+description = "A company analytics dashboard with leaderboard, filtering, and drill-down dialogs"
+requires-python = ">=3.11"
+dependencies = [
+    "altair>=5.5.0",
+    "numpy>=1.26.0",
+    "pandas>=2.2.3",
+    "snowflake-connector-python>=3.3.0",
+    "streamlit[snowflake]>=1.54.0",
+]