axiom-coding-agent-setup 1.0.10 → 1.0.11

package/.agents/skills/developing-with-streamlit/skills/improving-streamlit-design/SKILL.md

@@ -0,0 +1,191 @@
+---
+name: improving-streamlit-design
+description: Improving visual design in Streamlit apps. Use when polishing apps with icons, badges, spacing, or text styling. Covers Material icons, badge syntax, divider alternatives, and text casing conventions.
+license: Apache-2.0
+---
+
+# Streamlit visual design
+
+Small touches that make apps feel polished.
+
+**Related skills:** Visual design works hand-in-hand with other skills:
+- `choosing-streamlit-selection-widgets` → Choosing the right widget (segmented control, pills, toggle)
+- `displaying-streamlit-data` → Column config, sparklines, bordered metrics
+- `using-streamlit-layouts` → Containers, alignment, dashboard cards
+
+## Page config
+
+Set browser tab title, icon, and layout. Place this at the top of your script to avoid visual blinking:
+
+```python
+st.set_page_config(
+    page_title="My Dashboard",
+    page_icon=":material/analytics:",
+    layout="wide",  # Use "wide" for dashboards with lots of data
+)
+```
+
+**Layout options:**
+- `layout="centered"` (default) → Best for most apps, content is constrained to a readable width
+- `layout="wide"` → Full-width, good for dashboards and data-heavy apps
+
+## App logo
+
+Add a logo to the sidebar/header:
+
+```python
+st.logo("logo.png")
+```
+
+## Icons over emojis
+
+Use Material icons for a cleaner, more professional look.
+
+```python
+# GOOD: Material icons
+st.markdown(":material/settings:")
+st.markdown(":material/calendar_today:")
+st.markdown(":material/dashboard:")
+st.markdown(":material/person:")
+
+# SPARINGLY: Emojis for special occasions
+st.markdown("Celebration! 🎉")
+```
+
+Format: `:material/icon_name:`
+
+Find icons: https://fonts.google.com/icons
+
+**Popular icons by category:**
+
+| Category | Icons |
+|----------|-------|
+| Navigation | `home`, `arrow_back`, `menu`, `settings`, `search` |
+| Actions | `send`, `play_arrow`, `refresh`, `download`, `upload`, `save`, `delete`, `edit` |
+| Status | `check_circle`, `error`, `warning`, `info`, `pending` |
+| Data | `table_chart`, `bar_chart`, `analytics`, `query_stats`, `database` |
+| Content | `chat`, `code`, `description`, `article`, `folder` |
+| UI | `visibility`, `build`, `tune`, `filter_list` |
+
+## Badges for status
+
+For standalone badges:
+```python
+st.badge("Active", icon=":material/check:", color="green")
+st.badge("Pending", icon=":material/schedule:", color="orange")
+st.badge("Deprecated", color="red")
+```
+
+For inline badges in text:
+```python
+st.markdown("""
+:green-badge[Active] :orange-badge[Pending] :red-badge[Deprecated] :blue-badge[New]
+""")
+```
+
+Avoid the old verbose syntax:
+```python
+# OLD (still works but cluttered)
+st.markdown(":orange-background[:orange[Pending]]")
+```
+
+## Spacing: remove dividers
+
+Dividers (`st.divider()` or `---`) look heavy. Just remove them—Streamlit's default spacing is usually enough.
+
+```python
+# BAD
+st.header("Section 1")
+st.write("Content")
+st.divider()  # Too heavy
+st.header("Section 2")
+
+# GOOD
+st.header("Section 1")
+st.write("Content")
+st.header("Section 2")
+```
+
+If you genuinely need spacing:
+```python
+st.space("small")   # Small gap
+st.space("medium")  # Medium gap
+st.space("large")   # Large gap
+st.space(50)        # Custom pixels for fine-tuning
+```
+
+**Don't** systematically replace dividers with `st.space()`—it can look weird too.
+
+## Sentence casing
+
+Use sentence casing for titles and labels. Title Case Feels Shouty.
+
+```python
+# GOOD
+st.title("Upload your data")
+st.selectbox("Select a region", options)
+st.button("Save changes")
+
+# BAD
+st.title("Upload Your Data")
+st.selectbox("Select A Region", options)
+```
+
+## Caption over info
+
+`st.info()` is too heavy for simple informational text.
+
+```python
+# GOOD: Lighter
+st.caption("Data last updated 5 minutes ago")
+
+# BAD: Too heavy
+st.info("Data last updated 5 minutes ago")
+```
+
+**When to use what:**
+- `st.caption` → Simple info, metadata, timestamps
+- `st.info` → Important instructions
+- `st.warning` → Caution, potential issues
+- `st.error` → Errors that block progress
+- `st.success` → Confirmation of action
+- `st.toast` → Lightweight confirmation that auto-dismisses
+
+## Text alignment
+
+Use `text_alignment` for text elements:
+
+```python
+st.title("Centered title", text_alignment="center")
+st.write("Right aligned", text_alignment="right")
+st.caption("Justified text", text_alignment="justify")
+```
+
+Options: `"left"` (default), `"center"`, `"right"`, `"justify"`
+
+**Note:** `horizontal_alignment` on containers positions elements but also sets their `text_alignment`. If you need different text alignment within a horizontally-aligned container, override `text_alignment` on the text element itself.
+
+## Icons in callouts and expanders
+
+Material icons can make callouts and expanders look nicer:
+
+```python
+st.info("Processing complete", icon=":material/check_circle:")
+st.warning("Rate limit approaching", icon=":material/warning:")
+st.error("Connection failed", icon=":material/error:")
+st.success("Saved!", icon=":material/thumb_up:")
+
+with st.expander("Settings", icon=":material/settings:"):
+    st.write("Configure your preferences")
+```
+
+Other elements like `st.button` and `st.tabs` also support icons—worth considering when it adds clarity.
+
+## References
+
+- [st.set_page_config](https://docs.streamlit.io/develop/api-reference/configuration/st.set_page_config)
+- [st.logo](https://docs.streamlit.io/develop/api-reference/media/st.logo)
+- [st.badge](https://docs.streamlit.io/develop/api-reference/text/st.badge)
+- [st.space](https://docs.streamlit.io/develop/api-reference/layout/st.space)
+- [st.markdown](https://docs.streamlit.io/develop/api-reference/text/st.markdown)
+- [st.toast](https://docs.streamlit.io/develop/api-reference/status/st.toast)

package/.agents/skills/developing-with-streamlit/skills/optimizing-streamlit-performance/SKILL.md

@@ -0,0 +1,323 @@
+---
+name: optimizing-streamlit-performance
+description: Optimizing Streamlit app performance. Use when apps are slow, rerunning too often, or loading heavy content. Covers caching, fragments, and static vs dynamic widget choices.
+license: Apache-2.0
+---
+
+# Streamlit performance
+
+Performance is the biggest win. Without caching and fragments, your app reruns everything on every interaction.
+
+## Caching
+
+### @st.cache_data for data
+
+Use for any function that loads or computes data.
+
+```python
+# BAD: Recomputes on every rerun
+def load_data(path):
+    return pd.read_csv(path)
+
+# GOOD: Cached
+@st.cache_data
+def load_data(path):
+    return pd.read_csv(path)
+```
+
+### @st.cache_resource for connections
+
+Use for connections, API clients, ML models—objects that can't be serialized.
+
+```python
+@st.cache_resource
+def get_connection():
+    return st.connection("snowflake")
+
+@st.cache_resource
+def load_model():
+    return torch.load("model.pt")
+```
+
+**Critical warning:** Never mutate `@st.cache_resource` returns—changes affect all users:
+
+```python
+# BAD: Mutating shared resource
+@st.cache_resource
+def get_config():
+    return {"setting": "default"}
+
+config = get_config()
+config["setting"] = "custom"  # Affects ALL users!
+
+# GOOD: Copy before modifying
+config = get_config().copy()
+config["setting"] = "custom"
+```
+
+**Cleanup with `on_release`:** Clean up resources when evicted from cache:
+
+```python
+def cleanup_connection(conn):
+    conn.close()
+
+@st.cache_resource(on_release=cleanup_connection)
+def get_database():
+    return create_connection()
+```
+
+### TTL for fresh data
+
+```python
+@st.cache_data(ttl="5m")  # 5 minutes
+def get_metrics():
+    return api.fetch()
+
+@st.cache_data(ttl="1h")  # 1 hour
+def load_reference_data():
+    return pd.read_csv("large_reference.csv")
+```
+
+**Guidelines:**
+- Real-time dashboards → `ttl="1m"` or less
+- Metrics/reports → `ttl="5m"` to `ttl="15m"`
+- Reference data → `ttl="1h"` or more
+- Static data → No TTL
+
+### Prevent unbounded cache growth
+
+**Important:** Caches without `ttl` or `max_entries` can grow indefinitely and cause memory issues. For any cached function that stores changing objects (user-specific data, parameterized queries), set limits:
+
+```python
+# BAD: Unbounded cache - memory will grow indefinitely
+@st.cache_data
+def get_user_data(user_id):
+    return fetch_user(user_id)
+
+# GOOD: Bounded cache with TTL
+@st.cache_data(ttl="1h")
+def get_user_data(user_id):
+    return fetch_user(user_id)
+
+# GOOD: Bounded cache with max entries
+@st.cache_data(max_entries=100)
+def get_user_data(user_id):
+    return fetch_user(user_id)
+```
+
+Use `ttl` for time-based expiration OR `max_entries` for size-based limits. You usually don't need both.
+
+### Caching anti-patterns
+
+**Don't cache functions that read widgets:**
+
+```python
+# BAD: Widget inside cached function
+@st.cache_data
+def filtered_data():
+    query = st.text_input("Query")  # Widget inside cached function!
+    return df[df["name"].str.contains(query)]
+
+# GOOD: Pass widget values as parameters
+@st.cache_data
+def filtered_data(query: str):
+    return df[df["name"].str.contains(query)]
+
+query = st.text_input("Query")
+result = filtered_data(query)
+```
+
+**Cache at the right granularity:**
+
+```python
+# BAD: Caching too much - new cache entry per filter value
+@st.cache_data
+def get_and_filter_data(filter_value):
+    data = load_all_data()  # Expensive!
+    return data[data["col"] == filter_value]
+
+# GOOD: Cache the expensive part, filter separately
+@st.cache_data(ttl="1h")
+def load_all_data():
+    return fetch_from_database()
+
+data = load_all_data()
+filtered = data[data["col"] == filter_value]
+```
+
+## Fragments
+
+Use `@st.fragment` to isolate reruns for self-contained UI pieces.
+
+```python
+# BAD: Full app reruns
+st.metric("Users", get_count())
+if st.button("Refresh"):
+    st.rerun()
+
+# GOOD: Only fragment reruns
+@st.fragment
+def live_metrics():
+    st.metric("Users", get_count())
+    st.button("Refresh")
+
+live_metrics()
+```
+
+For auto-refreshing metrics, use `run_every`:
+```python
+@st.fragment(run_every="30s")
+def auto_refresh_metrics():
+    st.metric("Users", get_count())
+
+auto_refresh_metrics()
+```
+
+Use for: live metrics, refresh buttons, interactive charts that don't affect global state.
+
+## Forms to batch interactions
+
+By default, every widget interaction triggers a full rerun. Use `st.form` to batch multiple inputs and only rerun on submit.
+
+```python
+# BAD: Reruns on every keystroke and selection
+name = st.text_input("Name")
+email = st.text_input("Email")
+role = st.selectbox("Role", ["Admin", "User"])
+
+# GOOD: Single rerun when user clicks Submit
+with st.form("user_form"):
+    name = st.text_input("Name")
+    email = st.text_input("Email")
+    role = st.selectbox("Role", ["Admin", "User"])
+    submitted = st.form_submit_button("Submit")
+
+if submitted:
+    save_user(name, email, role)
+```
+
+Use `border=False` for seamless inline forms that don't look like forms:
+
+```python
+with st.form("search", border=False):
+    with st.container(horizontal=True):
+        query = st.text_input("Search", label_visibility="collapsed")
+        st.form_submit_button(":material/search:")
+```
+
+**When to use forms:**
+- Multiple related inputs (signup, filters, settings)
+- Text inputs where typing triggers expensive operations
+- Any UI where "submit" semantics make sense
+
+**When NOT to use forms:** If inputs depend on each other (e.g., selecting a country should update available cities), forms won't work since there's no rerun until submit.
+
+## Conditional rendering
+
+**This is critical and often missed.**
+
+Layout containers like `st.tabs`, `st.expander`, and `st.popover` always render all their content, even when hidden or collapsed.
+
+To render content only when needed, use elements like `st.segmented_control`, `st.toggle`, or `@st.dialog` with conditional logic:
+
+```python
+# BAD: Heavy content loads even when tab not visible
+tab1, tab2 = st.tabs(["Light", "Heavy"])
+with tab2:
+    expensive_chart()  # Always computed!
+
+# GOOD: Content only loads when selected
+view = st.segmented_control("View", ["Light", "Heavy"])
+if view == "Heavy":
+    expensive_chart()  # Only computed when selected
+```
+
+```python
+# BAD: Expander content always loads
+with st.expander("Advanced options"):
+    heavy_computation()  # Runs even when collapsed!
+
+# GOOD: Toggle controls loading
+if st.toggle("Show advanced options"):
+    heavy_computation()  # Only runs when toggled on
+```
+
+## Pre-computation
+
+Move expensive work outside the main flow:
+- Compute aggregations in SQL/dbt, not Python
+- Pre-compute metrics in scheduled jobs
+- Use materialized views for complex queries
+
+## Large data handling
+
+### For datasets under ~100M rows
+
+```python
+@st.cache_data
+def load_data():
+    return pd.read_parquet("large_file.parquet")
+```
+
+### For very large datasets (over ~100M rows)
+
+> **Note:** This is only an escape hatch when serialization becomes too slow. In most cases, data this large shouldn't be loaded entirely into memory—prefer using a database that queries and loads data on demand.
+
+`@st.cache_data` uses pickle which slows with huge data. Use `@st.cache_resource` instead:
+
+```python
+@st.cache_resource  # No serialization overhead
+def load_huge_data():
+    return pd.read_parquet("huge_file.parquet")
+
+# WARNING: Don't mutate the returned DataFrame!
+```
+
+### Sampling for exploration
+
+When exploring large datasets, load a random sample instead of the full data:
+
+```python
+@st.cache_data(ttl="1h")
+def load_sample(n=10000):
+    df = pd.read_parquet("huge.parquet")
+    return df.sample(n=n)
+```
+
+## Multithreading
+
+Custom threads cannot call Streamlit commands (no session context).
+
+```python
+import threading
+
+def fetch_in_background(url, results, index):
+    results[index] = requests.get(url).json()  # No st.* calls!
+
+# Collect results, then display in main thread
+results = [None] * len(urls)
+threads = [
+    threading.Thread(target=fetch_in_background, args=(url, results, i))
+    for i, url in enumerate(urls)
+]
+for t in threads:
+    t.start()
+for t in threads:
+    t.join()
+
+# Now display in main thread
+for result in results:
+    st.write(result)
+```
+
+**Prefer alternatives when possible:**
+- `@st.cache_data` for expensive computations
+- `@st.fragment(run_every="5s")` for periodic updates
+
+## References
+
+- [Caching overview](https://docs.streamlit.io/develop/concepts/architecture/caching)
+- [st.cache_data](https://docs.streamlit.io/develop/api-reference/caching-and-state/st.cache_data)
+- [st.cache_resource](https://docs.streamlit.io/develop/api-reference/caching-and-state/st.cache_resource)
+- [st.fragment](https://docs.streamlit.io/develop/api-reference/execution-flow/st.fragment)
+- [st.form](https://docs.streamlit.io/develop/api-reference/execution-flow/st.form)

package/.agents/skills/developing-with-streamlit/skills/organizing-streamlit-code/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: organizing-streamlit-code
+description: Organizing Streamlit code for maintainability. Use when structuring apps with separate modules and utilities. Covers separation of concerns, keeping UI code clean, and import patterns.
+license: Apache-2.0
+---
+
+# Streamlit code organization
+
+For most simple apps, keep everything in one file—it's cleaner and more straightforward. The app file should read like a normal Python script for data processing, with a few Streamlit commands sprinkled in.
+
+Name the main file `streamlit_app.py` (Streamlit's default).
+
+## When to split
+
+**Keep in one file (most apps):**
+- Apps under ~1000 lines
+- One-off scripts and prototypes
+- Apps where logic is straightforward
+
+**Consider splitting when:**
+- Data processing is complex (50+ lines of non-UI code)
+- Multiple pages share logic
+- You want to test business logic separately
+
+If splitting makes sense, here's how to organize it.
+
+## Directory structure
+
+```
+my-app/
+├── streamlit_app.py      # Main entry point
+├── app_pages/            # Page UI modules
+│   ├── dashboard.py
+│   └── settings.py
+└── utils/                # Business logic & helpers
+    ├── data.py
+    └── api.py
+```
+
+## Separating UI from logic
+
+When you do split, keep Streamlit files focused on UI and move complex logic to utility modules:
+
+```python
+# streamlit_app.py - UI-focused
+import streamlit as st
+from utils.data import load_sales_data, compute_metrics
+
+st.title("Sales Dashboard")
+
+start = st.date_input("Start")
+end = st.date_input("End")
+
+data = load_sales_data(start, end)
+metrics = compute_metrics(data)
+
+st.metric("Revenue", f"${metrics['revenue']:,.0f}")
+st.dataframe(data)
+```
+
+## Avoid if __name__ == "__main__"
+
+Streamlit apps run the entire file on each interaction. Don't use the main guard in Streamlit files.
+
+```python
+# BAD - don't do this in streamlit_app.py or pages
+if __name__ == "__main__":
+    main()
+
+# GOOD - just put the code directly
+import streamlit as st
+
+st.title("My App")
+```
+
+The main guard is fine in utility modules for quick testing:
+
+```python
+# utils/data.py
+def load_data(path):
+    ...
+
+# Optional: test this module directly with `python utils/data.py`
+if __name__ == "__main__":
+    print(load_data("test.csv"))
+```
+
+## References
+
+- [Multipage apps](https://docs.streamlit.io/develop/concepts/multipage-apps)
+- [st.cache_data](https://docs.streamlit.io/develop/api-reference/caching-and-state/st.cache_data)