axiom-coding-agent-setup 1.0.9 → 1.0.11

package/.agents/skills/developing-with-streamlit/skills/building-streamlit-multipage-apps/SKILL.md

@@ -0,0 +1,218 @@
+---
+name: building-streamlit-multipage-apps
+description: Building multi-page Streamlit apps. Use when creating apps with multiple pages, setting up navigation, or managing state across pages.
+license: Apache-2.0
+---
+
+# Streamlit multi-page apps
+
+Structure and navigation for apps with multiple pages.
+
+## Directory structure
+
+```
+streamlit_app.py          # Main entry point
+app_pages/
+    home.py
+    analytics.py
+    settings.py
+```
+
+**Important:** Name your pages directory `app_pages/` (not `pages/`). Using `pages/` conflicts with Streamlit's old auto-discovery API and can cause unexpected behavior.
+
+## Main module
+
+```python
+# streamlit_app.py
+import streamlit as st
+
+# Initialize global state (shared across pages)
+if "api_client" not in st.session_state:
+    st.session_state.api_client = init_api_client()
+
+# Define navigation
+page = st.navigation([
+    st.Page("app_pages/home.py", title="Home", icon=":material/home:"),
+    st.Page("app_pages/analytics.py", title="Analytics", icon=":material/bar_chart:"),
+    st.Page("app_pages/settings.py", title="Settings", icon=":material/settings:"),
+])
+
+# App-level UI runs before page content
+# Useful for shared elements like titles
+st.title(f"{page.icon} {page.title}")
+
+page.run()
+```
+
+**Note:** When you handle titles in `streamlit_app.py`, individual pages should NOT use `st.title` again.
+
+## Navigation position
+
+**Few pages (3-7) → Top navigation:**
+
+```python
+page = st.navigation([...], position="top")
+```
+
+Creates a clean horizontal menu. Great for simple apps. Sections are supported too—they appear as dropdowns in the top nav.
+
+**Many pages or nested sections → Sidebar:**
+
+```python
+page = st.navigation({
+    "Main": [
+        st.Page("app_pages/home.py", title="Home"),
+        st.Page("app_pages/analytics.py", title="Analytics"),
+    ],
+    "Admin": [
+        st.Page("app_pages/settings.py", title="Settings"),
+        st.Page("app_pages/users.py", title="Users"),
+    ],
+}, position="sidebar")
+```
+
+**Mixed: Some pages ungrouped:**
+
+Use an empty string key `""` for pages that shouldn't be in a section. These ungrouped pages always appear first, before any named groups. Put all ungrouped pages in a single `""` key:
+
+```python
+page = st.navigation({
+    "": [
+        st.Page("app_pages/home.py", title="Home"),
+        st.Page("app_pages/about.py", title="About"),
+    ],
+    "Analytics": [
+        st.Page("app_pages/dashboard.py", title="Dashboard"),
+        st.Page("app_pages/reports.py", title="Reports"),
+    ],
+}, position="top")
+```
+
+## Page modules
+
+```python
+# app_pages/analytics.py
+import streamlit as st
+
+# Access global state
+api = st.session_state.api_client
+user = st.session_state.user
+
+# Page-specific content (title is handled in streamlit_app.py)
+data = api.fetch_analytics(user.id)
+st.line_chart(data)
+```
+
+## Global state
+
+Initialize state in the main module only if it's needed across multiple pages:
+
+```python
+# streamlit_app.py
+st.session_state.api = init_client()
+st.session_state.user = get_user()
+st.session_state.settings = load_settings()
+```
+
+**Tip:** Use `st.session_state.setdefault("key", default_value)` to initialize values only if they don't exist.
+
+**Why main module (for global state):**
+- Runs before every page
+- Ensures state is initialized
+- Single source of truth
+
+## Page-specific state
+
+Use prefixed keys for page-specific state:
+
+```python
+# app_pages/analytics.py
+if "analytics_date_range" not in st.session_state:
+    st.session_state.analytics_date_range = default_range()
+```
+
+## Share elements between pages
+
+Put shared UI in the entrypoint (before `page.run()`) so it appears on all pages:
+
+```python
+# streamlit_app.py
+import streamlit as st
+
+pages = [...]
+page = st.navigation(pages)
+
+# Shared title
+st.title(f"{page.icon} {page.title}")
+
+# Shared sidebar widgets
+with st.sidebar:
+    st.selectbox("Theme", ["Light", "Dark"])
+
+page.run()
+```
+
+## Programmatic navigation
+
+Navigate to another page programmatically:
+
+```python
+if st.button("Go to Settings"):
+    st.switch_page("app_pages/settings.py")
+```
+
+Create navigation links with `st.page_link`:
+
+```python
+st.page_link("app_pages/home.py", label="Home", icon=":material/home:")
+st.page_link("https://example.com", label="External", icon=":material/open_in_new:")
+```
+
+> **Note:** Prefer `st.navigation` over `st.page_link` for standard navigation. Do not use `st.page_link` to recreate the nav bar you get with `st.navigation`. Only use `st.page_link` when linking to pages from somewhere other than the sidebar, or when building a more complex navigation menu.
+
+## Conditional pages
+
+Show different pages based on user role, authentication, or any other condition by building the pages list dynamically:
+
+```python
+# streamlit_app.py
+import streamlit as st
+
+pages = [st.Page("app_pages/home.py", title="Home", icon=":material/home:")]
+
+if st.user.is_logged_in:
+    pages.append(st.Page("app_pages/dashboard.py", title="Dashboard", icon=":material/bar_chart:"))
+
+if st.session_state.get("is_admin"):
+    pages.append(st.Page("app_pages/admin.py", title="Admin", icon=":material/settings:"))
+
+page = st.navigation(pages)
+page.run()
+```
+
+Common conditions for showing/hiding pages:
+- `st.user.is_logged_in` for authenticated users
+- `st.session_state` flags (roles, permissions, feature flags)
+- Environment variables or secrets
+- Time-based access (e.g., beta features)
+
+## Imports from pages
+
+When importing from page files in `app_pages/`, always import from the root directory perspective:
+
+```python
+# app_pages/dashboard.py - GOOD
+from utils.data import load_sales_data
+
+# app_pages/dashboard.py - BAD (don't use relative imports)
+from ..utils.data import load_sales_data
+```
+
+## References
+
+- [Multipage apps docs](https://docs.streamlit.io/develop/concepts/multipage-apps)
+- [st.navigation](https://docs.streamlit.io/develop/api-reference/navigation/st.navigation)
+- [st.Page](https://docs.streamlit.io/develop/api-reference/navigation/st.page)
+- [st.session_state](https://docs.streamlit.io/develop/api-reference/caching-and-state/st.session_state)
+- [st.switch_page](https://docs.streamlit.io/develop/api-reference/navigation/st.switch_page)
+- [st.page_link](https://docs.streamlit.io/develop/api-reference/widgets/st.page_link)

package/.agents/skills/developing-with-streamlit/skills/choosing-streamlit-selection-widgets/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: choosing-streamlit-selection-widgets
+description: Choosing the right Streamlit selection widget. Use when deciding between radio buttons, selectbox, segmented control, pills, or other option selection widgets. Helps pick the right widget for the number of options and selection type.
+license: Apache-2.0
+---
+
+# Streamlit selection widgets
+
+The right selection widget for the job. Streamlit has evolved—many old patterns are now anti-patterns.
+
+## When to use what
+
+Use `st.segmented_control` or `st.pills` when you want all options visible at once. Use `st.selectbox` or `st.multiselect` when options should be hidden in a dropdown.
+
+| Widget | Best For |
+|--------|----------|
+| `st.segmented_control` | 2-5 options, single select, all visible |
+| `st.pills` | 2-5 options, multi-select, all visible |
+| `st.selectbox` | Many options, single select, dropdown |
+| `st.multiselect` | Many options, multi-select, dropdown |
+
+## Segmented control (options visible, single select)
+
+```python
+# BAD
+status = st.radio("Status", ["Draft", "Published"], horizontal=True)
+
+# GOOD
+status = st.segmented_control("Status", ["Draft", "Published"])
+```
+
+For vertical layouts, `st.radio(..., horizontal=False)` is still a great choice.
+
+Cleaner, more modern look than horizontal radio buttons.
+
+## Pills (options visible, multi-select)
+
+```python
+# Multi-select with few options
+selected = st.pills(
+    "Tags",
+    ["Python", "SQL", "dbt", "Streamlit"],
+    selection_mode="multi"
+)
+```
+
+Can also be used to mimic an "example" widget, especially with `label_visibility="collapsed"`:
+```python
+st.pills("Examples", ["Show me sales data", "Top customers"], label_visibility="collapsed")
+```
+
+More visual and easier to use than `st.multiselect` for small option sets.
+
+## Selectbox (many options, single select)
+
+```python
+country = st.selectbox(
+    "Select a country",
+    ["USA", "UK", "Canada", "Germany", "France", ...]
+)
+```
+
+Dropdowns scale better than radio/pills for long lists.
+
+## Multiselect (many options, multi-select)
+
+```python
+countries = st.multiselect(
+    "Select countries",
+    ["USA", "UK", "Canada", "Germany", "France", ...]
+)
+```
+
+## Toggle vs checkbox
+
+Use `st.toggle` for settings that trigger changes in the app. Reserve `st.checkbox` for forms.
+
+```python
+# GOOD: Toggle for app settings
+dark_mode = st.toggle("Dark mode")
+show_advanced = st.toggle("Show advanced options")
+
+# GOOD: Checkbox in forms
+with st.form("signup"):
+    agree = st.checkbox("I agree to the terms")
+    st.form_submit_button("Sign up")
+```
+
+## Forms with border=False
+
+Remove the default form border for cleaner inline forms. Keep the border for longer forms where visual grouping helps.
+
+```python
+# Inline form without border
+with st.form(key="add_item", border=False):
+    with st.container(horizontal=True, vertical_alignment="bottom"):
+        st.text_input("New item", label_visibility="collapsed", placeholder="Add item")
+        st.form_submit_button("Add", icon=":material/add:")
+
+# Longer form - keep the border for visual grouping
+with st.form("signup"):
+    st.text_input("Name")
+    st.text_input("Email")
+    st.selectbox("Role", ["Admin", "User"])
+    st.form_submit_button("Submit")
+```
+
+## Custom options in selectbox and multiselect
+
+Allow users to add their own options with `accept_new_options`:
+
+```python
+# Works with multiselect
+tickers = st.multiselect(
+    "Stock tickers",
+    options=["AAPL", "MSFT", "GOOGL", "NVDA"],
+    default=["AAPL"],
+    accept_new_options=True,
+    placeholder="Choose stocks or type your own"
+)
+
+# Also works with selectbox
+country = st.selectbox(
+    "Country",
+    options=["USA", "UK", "Canada"],
+    accept_new_options=True,
+    placeholder="Select or type a country"
+)
+```
+
+## References
+
+- [st.segmented_control](https://docs.streamlit.io/develop/api-reference/widgets/st.segmented_control)
+- [st.pills](https://docs.streamlit.io/develop/api-reference/widgets/st.pills)
+- [st.selectbox](https://docs.streamlit.io/develop/api-reference/widgets/st.selectbox)
+- [st.multiselect](https://docs.streamlit.io/develop/api-reference/widgets/st.multiselect)
+- [st.toggle](https://docs.streamlit.io/develop/api-reference/widgets/st.toggle)
+- [st.checkbox](https://docs.streamlit.io/develop/api-reference/widgets/st.checkbox)
+- [st.form](https://docs.streamlit.io/develop/api-reference/execution-flow/st.form)

package/.agents/skills/developing-with-streamlit/skills/connecting-streamlit-to-snowflake/SKILL.md

@@ -0,0 +1,188 @@
+---
+name: connecting-streamlit-to-snowflake
+description: Connecting Streamlit apps to Snowflake. Use when setting up database connections, managing secrets, or querying Snowflake from a Streamlit app.
+license: Apache-2.0
+---
+
+# Streamlit Snowflake connection
+
+Connect your Streamlit app to Snowflake the right way.
+
+## Use st.connection
+
+Always use `st.connection("snowflake")` instead of raw connectors.
+
+```python
+import streamlit as st
+
+conn = st.connection("snowflake")
+
+# Query data
+df = conn.query("SELECT * FROM my_table LIMIT 100")
+st.dataframe(df)
+```
+
+**Why st.connection:**
+- Automatic connection pooling
+- Built-in caching
+- Handles reconnection
+- Works with st.secrets
+
+## Caller's rights connection (Streamlit 1.53+)
+
+For apps running in Snowflake, use caller's rights to run queries with the viewer's permissions instead of the app owner's:
+
+```python
+conn = st.connection("snowflake", type="snowflake-callers-rights")
+```
+
+This is useful when:
+- Different users should see different data based on their Snowflake roles
+- You want row-level security to apply based on the viewer
+- You don't want the app to have elevated permissions
+
+## Cached queries
+
+Use the built-in `ttl` parameter to cache query results:
+
+```python
+from datetime import timedelta
+
+conn = st.connection("snowflake")
+
+# Cache for 10 minutes
+df = conn.query("SELECT * FROM metrics", ttl=timedelta(minutes=10))
+
+# Cache for 1 hour
+df = conn.query("SELECT * FROM reference_data", ttl=3600)
+```
+
+## Configure with st.secrets
+
+Store credentials in `.streamlit/secrets.toml` (never commit this file).
+
+**CRITICAL**: Derive the `account` and `host` values from the user's Snowflake CLI connection config. Run `snow connection list` and use the exact values. A wrong `account` will redirect to the wrong login page.
+
+```toml
+# .streamlit/secrets.toml
+[connections.snowflake]
+account = "ORGNAME-ACCTNAME"            # from `snow connection list`
+host = "myaccount.snowflakecomputing.com"  # from `snow connection list` (include if present)
+user = "your_user"
+authenticator = "externalbrowser"
+warehouse = "your_warehouse"
+database = "your_database"
+schema = "your_schema"
+```
+
+Add to `.gitignore`:
+```
+.streamlit/secrets.toml
+```
+
+## Parameterized queries
+
+Use parameters to prevent SQL injection:
+
+```python
+conn = st.connection("snowflake")
+
+# Safe: parameterized
+df = conn.query(
+    "SELECT * FROM users WHERE region = :region",
+    params={"region": selected_region}
+)
+
+# UNSAFE: string formatting - don't do this
+# df = conn.query(f"SELECT * FROM users WHERE region = '{selected_region}'")
+```
+
+## Write data
+
+Use the session for write operations:
+
+```python
+conn = st.connection("snowflake")
+session = conn.session()
+
+# Write a dataframe
+session.write_pandas(df, "MY_TABLE", auto_create_table=True)
+
+# Execute statements
+session.sql("INSERT INTO logs VALUES (:ts, :msg)", params={...}).collect()
+```
+
+## Multiple connections
+
+Define multiple connections in secrets:
+
+```toml
+# .streamlit/secrets.toml
+[connections.snowflake]
+account = "prod_account"
+# ... prod credentials
+
+[connections.snowflake_staging]
+account = "staging_account"
+# ... staging credentials
+```
+
+```python
+prod_conn = st.connection("snowflake")
+staging_conn = st.connection("snowflake_staging")
+```
+
+## Chat with Cortex
+
+Build a chat interface using Snowflake Cortex LLMs:
+
+```python
+import streamlit as st
+from snowflake.cortex import complete
+
+st.set_page_config(page_title="AI Assistant", page_icon=":sparkles:")
+
+if "messages" not in st.session_state:
+    st.session_state.messages = []
+
+for msg in st.session_state.messages:
+    with st.chat_message(msg["role"]):
+        st.write(msg["content"])
+
+if prompt := st.chat_input("Ask anything"):
+    st.session_state.messages.append({"role": "user", "content": prompt})
+
+    with st.chat_message("user"):
+        st.write(prompt)
+
+    with st.chat_message("assistant"):
+        response = st.write_stream(
+            complete(
+                "claude-3-5-sonnet",
+                prompt,
+                session=st.connection("snowflake").session(),
+                stream=True,
+            )
+        )
+
+    st.session_state.messages.append({"role": "assistant", "content": response})
+```
+
+See `building-streamlit-chat-ui` for more chat patterns (avatars, suggestions, history management).
+
+## Python 3.12+ dependency caveat
+
+`streamlit[snowflake]` gates `snowflake-connector-python` on `python_version < "3.12"`. On Python 3.12+, the connector is silently skipped and you get `No module named 'snowflake'` at runtime. Always add `snowflake-connector-python>=3.3.0` as an explicit dependency in `pyproject.toml`:
+
+```toml
+dependencies = [
+    "snowflake-connector-python>=3.3.0",
+    "streamlit[snowflake]>=1.54.0",
+]
+```
+
+## References
+
+- [st.connection](https://docs.streamlit.io/develop/api-reference/connections/st.connection)
+- [SnowflakeConnection](https://docs.streamlit.io/develop/api-reference/connections/st.connections.snowflakeconnection)
+- [st.secrets](https://docs.streamlit.io/develop/api-reference/connections/st.secrets)