axiom-coding-agent-setup 1.0.10 → 1.0.11

package/.agents/skills/developing-with-streamlit/skills/setting-up-streamlit-environment/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: setting-up-streamlit-environment
+description: Setting up Python environments for Streamlit apps. Use when creating a new project or managing dependencies. Covers uv for dependency management and running apps.
+license: Apache-2.0
+---
+
+# Streamlit environment
+
+Use whatever dependency management the project already has (pip, poetry, conda, etc.). If starting fresh and uv is available, it's a good default—fast, reliable, and creates isolated environments automatically.
+
+If uv is not installed, ask the user before installing it.
+
+## CRITICAL: Always Use Latest Streamlit
+
+**Always specify `streamlit>=1.53.0`** (or latest) in dependencies. Many Streamlit features and patterns in these skills require recent versions. Older streamlit versions will cause errors with:
+- Material icons (`:material/icon_name:`)
+- `st.pills()`, `st.segmented_control()`
+- Modern caching decorators
+- Navigation APIs
+
+When setting up a new project or fixing an existing one, **always check and update the streamlit version**.
+
+## Using uv
+
+If uv is available, here's how to set up a Streamlit project.
+
+### Quick start (venv only)
+
+For simple apps, just create a virtual environment:
+
+```bash
+uv venv
+source .venv/bin/activate  # or .venv\Scripts\activate on Windows
+uv pip install streamlit
+```
+
+Run with:
+
+```bash
+streamlit run streamlit_app.py
+```
+
+## Full project setup
+
+For larger projects or when you need reproducible builds:
+
+```bash
+uv init my-streamlit-app
+cd my-streamlit-app
+uv add streamlit
+```
+
+This creates:
+- `pyproject.toml` with dependencies
+- `uv.lock` for reproducible builds
+- `.venv/` virtual environment
+
+Run with:
+
+```bash
+uv run streamlit run streamlit_app.py
+```
+
+## With options
+
+Avoid setting options unless you have a specific reason:
+
+```bash
+streamlit run streamlit_app.py --server.headless true  # Only for automated/CI environments
+```
+
+## Add dependencies
+
+```bash
+# With venv approach
+uv pip install plotly snowflake-connector-python
+
+# With full project (uv init)
+uv add plotly snowflake-connector-python
+```
+
+## Project structure
+
+Keep it simple. For most apps:
+
+```
+my-streamlit-app/
+├── .venv/
+└── streamlit_app.py
+```
+
+Only add more when needed:
+- `app_pages/` → Only for multi-page apps
+- `.streamlit/config.toml` → Only if customizing theme or settings
+- `.streamlit/secrets.toml` → Only if using secrets (add to `.gitignore`)
+- `pyproject.toml` → Only if using `uv init` for reproducible builds
+
+## Convention
+
+Name your main file `streamlit_app.py` for consistency. This is what Streamlit expects by default.
+
+**What goes in the main module:**
+- When using navigation: it's a router that defines pages and runs them
+- When there's no navigation: it's the home page with your main content
+
+## pyproject.toml Example
+
+```toml
+[project]
+name = "my-streamlit-app"
+version = "0.1.0"
+requires-python = ">=3.11"
+dependencies = [
+    "streamlit>=1.53.0",
+    "plotly>=5.0.0",
+    "snowflake-connector-python>=3.0.0",
+]
+
+[tool.uv]
+dev-dependencies = [
+    "pytest>=8.0.0",
+]
+```
+
+## References
+
+- [uv documentation](https://docs.astral.sh/uv/)
+- [Streamlit installation](https://docs.streamlit.io/get-started/installation)

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

@@ -0,0 +1,165 @@
+---
+name: using-streamlit-cli
+description: Documents Streamlit CLI commands for running apps, managing configuration, and diagnostics. Use when starting Streamlit apps, configuring runtime options, or troubleshooting CLI issues.
+---
+
+# Using the Streamlit CLI
+
+The Streamlit CLI is the primary tool for running Streamlit applications and managing configuration. This skill covers all essential commands and configuration options.
+
+## Running Streamlit apps
+
+### Basic syntax
+
+```bash
+streamlit run [<entrypoint>] [-- config options] [script args]
+```
+
+### Entrypoint options
+
+| Argument | Behavior |
+|----------|----------|
+| (none) | Looks for `streamlit_app.py` in current directory |
+| Directory path | Runs `streamlit_app.py` within that directory |
+| File path | Runs the specified file directly |
+| URL | Runs a remote script (e.g., from GitHub) |
+
+### Examples
+
+```bash
+# Run default app in current directory
+streamlit run
+
+# Run a specific file
+streamlit run app.py
+
+# Run from a URL
+streamlit run https://raw.githubusercontent.com/streamlit/demo-uber-nyc-pickups/master/streamlit_app.py
+
+# Alternative: run as Python module (useful for IDE configuration)
+python -m streamlit run app.py
+```
+
+### Running with `uv` (recommended)
+
+Use `uv run` to run Streamlit in a virtual environment with automatic dependency management:
+
+```bash
+# Run with uv (automatically uses/creates virtual environment)
+uv run streamlit run app.py
+
+# With configuration options
+uv run streamlit run app.py --server.headless=true
+
+# With script arguments
+uv run streamlit run app.py -- arg1 arg2
+```
+
+Using `uv run` is the recommended approach because it:
+- Automatically manages virtual environments
+- Resolves and installs dependencies from `pyproject.toml`
+- Ensures reproducible environments across machines
+- Avoids manual activation/deactivation of virtual environments
+
+## Setting configuration with `streamlit run`
+
+Configuration options follow the pattern `--<section>.<option>=<value>` and must come after the script name.
+
+> **Recommendation:** For persistent configuration, use `.streamlit/config.toml` in your project directory instead of command-line flags. This keeps your run command simple and makes configuration easier to manage and share with your team.
+
+### Examples
+
+```bash
+streamlit run app.py --server.port=8080
+streamlit run app.py --server.headless=true
+streamlit run app.py --server.runOnSave=true
+streamlit run app.py --server.address=0.0.0.0
+streamlit run app.py --client.showErrorDetails=false
+streamlit run app.py --theme.primaryColor=blue
+```
+
+### Combining multiple options
+
+```bash
+streamlit run app.py \
+    --server.port=8080 \
+    --server.headless=true \
+    --theme.primaryColor=blue \
+    --client.showErrorDetails=false
+```
+
+## Passing arguments to your script
+
+Script arguments come after configuration options. Use `sys.argv` to access them:
+
+```bash
+streamlit run app.py -- arg1 arg2 "arg with spaces"
+```
+
+In your script:
+
+```python
+import sys
+
+# sys.argv[0] = script path
+# sys.argv[1:] = your arguments
+args = sys.argv[1:]
+```
+
+## Other CLI commands
+
+### View configuration
+
+```bash
+# Show all current configuration settings
+streamlit config show
+```
+
+### Cache management
+
+```bash
+# Clear all cached data from disk
+streamlit cache clear
+```
+
+### Diagnostics and help
+
+```bash
+# Show installed version
+streamlit version
+
+# List all available commands
+streamlit help
+
+# Open documentation in browser
+streamlit docs
+```
+
+### Project scaffolding
+
+```bash
+# Create starter files for a new project
+streamlit init
+```
+
+### Demo app
+
+```bash
+# Launch the Streamlit demo application
+streamlit hello
+```
+
+## Configuration precedence
+
+Configuration can be set in multiple places. Order of precedence (highest to lowest):
+
+1. **Command-line flags** (`--server.port=8080`)
+2. **Environment variables** (`STREAMLIT_SERVER_PORT=8080`)
+3. **Local config** (`.streamlit/config.toml` in project directory)
+4. **Global config** (`~/.streamlit/config.toml`)
+
+## References
+
+- [Run your app](https://docs.streamlit.io/develop/concepts/architecture/run-your-app) - Concepts and methods for running Streamlit apps
+- [config.toml](https://docs.streamlit.io/develop/api-reference/configuration/config.toml) - Complete configuration options reference
+- [CLI reference](https://docs.streamlit.io/develop/api-reference/cli) - Full CLI command documentation

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

@@ -0,0 +1,170 @@
+---
+name: using-streamlit-custom-components
+description: Using third-party Streamlit custom components. Use when extending Streamlit with community packages. Covers installation, popular custom components, and when to use them.
+license: Apache-2.0
+---
+
+# Streamlit custom components
+
+Extend Streamlit with third-party custom components from the community.
+
+## What are custom components?
+
+Custom components are standalone Python libraries that add features not in Streamlit's core API. They're built by the community and can be installed like any Python package.
+
+## Installation
+
+Install using the PyPI package name (not the repo name—they can differ):
+
+```bash
+uv add <pypi-package-name>
+```
+
+Then import according to the component's documentation. The import name often differs from the package name too.
+
+## Use with caution
+
+Components are not maintained by Streamlit. Before adopting:
+
+- **Check maintenance** - Is it actively maintained? Recent commits?
+- **Check compatibility** - Does it work with your Streamlit version?
+- **Check popularity** - GitHub stars, downloads, community usage
+- **Consider alternatives** - Can you achieve this with core Streamlit?
+
+Custom components can break when Streamlit updates, so prefer core features when possible.
+
+## Popular custom components
+
+### streamlit-keyup
+
+Text input that fires on every keystroke instead of waiting for enter/blur. Useful for live search.
+
+- **Repo:** https://github.com/blackary/streamlit-keyup
+- **Docs:** https://pypi.org/project/streamlit-keyup/
+
+```bash
+uv add streamlit-keyup
+```
+
+```python
+from st_keyup import st_keyup
+
+query = st_keyup("Search", debounce=300)  # 300ms debounce
+filtered = df[df["name"].str.contains(query, case=False)]
+st.dataframe(filtered)
+```
+
+### streamlit-bokeh
+
+Official replacement for `st.bokeh_chart` (removed from Streamlit API). Maintained by Streamlit.
+
+- **Repo:** https://github.com/streamlit/streamlit-bokeh
+- **Docs:** https://pypi.org/project/streamlit-bokeh/
+
+```bash
+uv add streamlit-bokeh
+```
+
+```python
+from bokeh.plotting import figure
+from streamlit_bokeh import streamlit_bokeh
+
+p = figure(title="Simple Line", x_axis_label="x", y_axis_label="y")
+p.line([1, 2, 3, 4, 5], [6, 7, 2, 4, 5], line_width=2)
+streamlit_bokeh(p)
+```
+
+### streamlit-aggrid
+
+Interactive dataframes with sorting, filtering, cell editing, grouping, and pivoting. Use when you need customization beyond what `st.dataframe` and `st.data_editor` offer.
+
+- **Repo:** https://github.com/PablocFonseca/streamlit-aggrid
+- **Docs:** https://pypi.org/project/streamlit-aggrid/
+
+```bash
+uv add streamlit-aggrid
+```
+
+```python
+from st_aggrid import AgGrid
+
+AgGrid(df, editable=True, filter=True)
+```
+
+**When to use aggrid over st.dataframe:**
+- Interactive row grouping and pivoting
+- Advanced filtering and sorting UI
+- Complex cell editing workflows
+- Custom cell renderers
+
+### streamlit-folium
+
+Interactive maps powered by Folium.
+
+- **Repo:** https://github.com/randyzwitch/streamlit-folium
+- **Docs:** https://folium.streamlit.app/
+
+```bash
+uv add streamlit-folium
+```
+
+```python
+import folium
+from streamlit_folium import st_folium
+
+m = folium.Map(location=[37.7749, -122.4194], zoom_start=12)
+st_folium(m, width=700)
+```
+
+### pygwalker
+
+Tableau-like drag-and-drop data exploration.
+
+- **Repo:** https://github.com/Kanaries/pygwalker
+- **Docs:** https://docs.kanaries.net/pygwalker
+
+```bash
+uv add pygwalker
+```
+
+```python
+import pygwalker as pyg
+
+pyg.walk(df, env="Streamlit")
+```
+
+### streamlit-extras
+
+A collection of community utilities. Cherry-pick what you need.
+
+- **Repo:** https://github.com/arnaudmiribel/streamlit-extras
+- **Docs:** https://extras.streamlit.app/
+
+```bash
+uv add streamlit-extras
+```
+
+```python
+from streamlit_extras.image_selector import image_selector
+
+# Let users click on regions of an image
+selection = image_selector(image, selections=["Region A", "Region B"])
+```
+
+```python
+from streamlit_extras.vertical_slider import vertical_slider
+
+# A vertical slider widget
+value = vertical_slider("Volume", min_value=0, max_value=100, default_value=50)
+```
+
+## Discover more
+
+Browse the custom component gallery: https://streamlit.io/components
+
+Filter by category, popularity, and recency to find custom components for your use case.
+
+## References
+
+- [Components Gallery](https://streamlit.io/components)
+- [Build a custom component](https://docs.streamlit.io/develop/concepts/custom-components)

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

@@ -0,0 +1,229 @@
+---
+name: using-streamlit-layouts
+description: Structuring Streamlit app layouts. Use when placing content in sidebars, columns, containers, or dialogs. Covers sidebar usage, column limits, horizontal containers, dialogs, and bordered cards.
+license: Apache-2.0
+---
+
+# Streamlit layout
+
+How you structure your app affects usability more than you think.
+
+## Sidebar: navigation + global filters only
+
+The sidebar should only contain navigation and app-level filters. Main content goes in the main area.
+
+```python
+# GOOD
+with st.sidebar:
+    date_range = st.date_input("Date range")
+    region = st.selectbox("Region", ["All", "US", "EU", "APAC"])
+    st.caption("App v1.2.3")
+```
+
+```python
+# BAD: Too much content in sidebar
+with st.sidebar:
+    st.title("Dashboard")
+    st.dataframe(df)  # Don't put main content here
+    st.bar_chart(data)
+```
+
+**What goes in sidebar:**
+- Global filters (date range, user selection, region)
+- App info (version, feedback link)
+
+**What stays out:**
+- Main content, charts, tables, results
+
+## Columns: max 4, set alignment
+
+Don't use too many columns—they get cramped.
+
+```python
+# GOOD
+col1, col2 = st.columns(2)
+
+# Custom widths (ratios)
+col1, col2 = st.columns([2, 1])  # 2:1 ratio
+
+# OK with alignment
+cols = st.columns(4, vertical_alignment="center")
+
+# BAD: Too many, cramped
+col1, col2, col3, col4, col5, col6 = st.columns(6)
+```
+
+## Horizontal containers for button groups
+
+Use `st.container(horizontal=True)` instead of columns for button groups:
+
+```python
+with st.container(horizontal=True):
+    st.button("Cancel")
+    st.button("Save")
+    st.button("Submit")
+```
+
+## Aligning elements
+
+Use `horizontal_alignment` on containers to position elements:
+
+```python
+# Center elements
+with st.container(horizontal_alignment="center"):
+    st.image("logo.png", width=200)
+    st.title("Welcome")
+
+# Right-align elements
+with st.container(horizontal_alignment="right"):
+    st.button("Settings", icon=":material/settings:")
+
+# Distribute evenly (great for button groups)
+with st.container(horizontal=True, horizontal_alignment="distribute"):
+    st.button("Cancel")
+    st.button("Save")
+    st.button("Submit")
+```
+
+Options: `"left"` (default), `"center"`, `"right"`, `"distribute"`
+
+## Bordered containers
+
+Use `border=True` on containers for visual grouping. See `building-streamlit-dashboards` for dashboard-specific patterns like KPI cards.
+
+```python
+with st.container(border=True):
+    st.subheader("Section title")
+    st.write("Grouped content here")
+```
+
+## Tabs
+
+Organize content into switchable views:
+
+```python
+tab1, tab2 = st.tabs(["Chart", "Data"])
+
+with tab1:
+    st.line_chart(data)
+with tab2:
+    st.dataframe(df)
+```
+
+## Expander
+
+Collapsible sections for secondary content:
+
+```python
+with st.expander("See details"):
+    st.write("Hidden content here")
+    st.code("print('hello')")
+```
+
+## Empty and placeholders
+
+`st.empty()` creates a single-element placeholder that can be updated or cleared:
+
+```python
+placeholder = st.empty()
+
+# Update the placeholder
+placeholder.text("Loading...")
+result = load_data()
+placeholder.dataframe(result)
+
+# Clear it
+placeholder.empty()
+```
+
+## Popover
+
+Click to reveal content:
+
+```python
+with st.popover("Settings"):
+    st.checkbox("Dark mode")
+    st.slider("Font size", 10, 24)
+```
+
+## Dialogs for focused interactions
+
+Use `@st.dialog` for UI that doesn't need to be always visible:
+
+```python
+@st.dialog("Confirm deletion")
+def confirm_delete(item_name):
+    st.write(f"Are you sure you want to delete **{item_name}**?")
+    if st.button("Delete", type="primary"):
+        delete_item(item_name)
+        st.rerun()
+
+if st.button("Delete item"):
+    confirm_delete("My Document")
+```
+
+**Key points:**
+- Dialogs rerun independently from the main script
+- Use `st.session_state` to pass widget values from the dialog to the main app
+- Call `st.rerun()` to close dialog and refresh main app
+- Use `dismissible=False` for forced actions
+- `st.sidebar` is not supported inside dialogs
+
+**When to use dialogs:**
+- Confirmation prompts
+- Settings panels
+- Forms that don't need to be always visible
+
+## Spacing
+
+Control spacing between elements with `gap` on containers:
+
+```python
+# Remove spacing for tight list-like UIs
+with st.container(gap=None, border=True):
+    for item in items:
+        st.checkbox(item.text)
+
+# Explicit gap sizes
+with st.container(gap="small"):
+    ...
+```
+
+Add vertical space with `st.space`:
+
+```python
+st.space("small")   # Small gap
+st.space("medium")  # Medium gap
+st.space("large")   # Large gap
+st.space(50)        # Custom pixels
+```
+
+## Width and height
+
+Control element sizing:
+
+```python
+# Stretch to fill available space (equal height columns)
+cols = st.columns(2)
+with cols[0].container(border=True, height="stretch"):
+    st.line_chart(data)
+with cols[1].container(border=True, height="stretch"):
+    st.dataframe(df)
+
+# Shrink to content size
+st.container(width="content")
+
+# Fixed pixel sizes
+st.container(height=300)
+```
+
+## References
+
+- [st.columns](https://docs.streamlit.io/develop/api-reference/layout/st.columns)
+- [st.container](https://docs.streamlit.io/develop/api-reference/layout/st.container)
+- [st.sidebar](https://docs.streamlit.io/develop/api-reference/layout/st.sidebar)
+- [st.tabs](https://docs.streamlit.io/develop/api-reference/layout/st.tabs)
+- [st.expander](https://docs.streamlit.io/develop/api-reference/layout/st.expander)
+- [st.popover](https://docs.streamlit.io/develop/api-reference/layout/st.popover)
+- [st.empty](https://docs.streamlit.io/develop/api-reference/layout/st.empty)
+- [st.dialog](https://docs.streamlit.io/develop/api-reference/execution-flow/st.dialog)