{"id":31144135,"url":"https://github.com/ashenfad/agex-ui","last_synced_at":"2026-07-01T12:32:14.104Z","repository":{"id":314039150,"uuid":"1043545819","full_name":"ashenfad/agex-ui","owner":"ashenfad","description":"Agex \u0026 NiceGui","archived":false,"fork":false,"pushed_at":"2026-03-01T21:32:06.000Z","size":3192,"stargazers_count":5,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-01T21:48:43.709Z","etag":null,"topics":["agentic","agex","ai","nicegui"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ashenfad.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-24T05:01:36.000Z","updated_at":"2026-01-19T13:06:47.000Z","dependencies_parsed_at":"2025-09-10T08:35:35.965Z","dependency_job_id":"05637894-7c39-4147-8f00-17033e21de21","html_url":"https://github.com/ashenfad/agex-ui","commit_stats":null,"previous_names":["ashenfad/agex-ui"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ashenfad/agex-ui","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ashenfad%2Fagex-ui","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ashenfad%2Fagex-ui/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ashenfad%2Fagex-ui/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ashenfad%2Fagex-ui/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ashenfad","download_url":"https://codeload.github.com/ashenfad/agex-ui/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ashenfad%2Fagex-ui/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35007276,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-01T02:00:05.325Z","response_time":130,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic","agex","ai","nicegui"],"created_at":"2025-09-18T14:22:42.664Z","updated_at":"2026-07-01T12:32:14.099Z","avatar_url":"https://github.com/ashenfad.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# agex-ui\n\nA demo for building agent-driven user interfaces with [`agex`](https://ashenfad.github.io/agex/) and [NiceGUI](https://nicegui.io/).\n\n**agex-ui** provides components for creating chat interfaces where AI agents can respond with text, dataframes, and plotly visualizations, with real-time streaming of agent activity.\n\n\u003ca href=\"https://youtu.be/10kG4tw0D4k\"\u003e\u003cimg src=\"assets/tmnt.png\" alt=\"TMNT Calendar Assistant\" width=\"500\"\u003e\u003c/a\u003e\n\n## Features\n\nThis repository serves as a reference implementation for integrating `agex` agents into a web UI.\n\n- **Multi-Type Responses**: Renders text, DataFrames, and Plotly figures.\n- **Real-Time Streaming**: Displays agent thought and action events as they happen.\n- **State Persistence**: Session branching, history restoration, and undo support.\n- **Live App Preview**: Sandboxed preview of agent-built NiceGUI apps with debug capture.\n- **File Management**: Upload, download, and browse files in the agent's virtual filesystem.\n\n## Quick Start\n\n### Installation\n\n```bash\n# Clone and install\ngit clone https://github.com/ashenfad/agex-ui.git\ncd agex-ui\npip install -e .\n```\n\n### Running a Demo\n\n```bash\n# Workshop - agent builds interactive NiceGUI apps with live preview\npython -m agex_ui.workshop.main\n\n# TMNT - calendar assistant using local iCal files\npython -m agex_ui.tmnt.main\n```\n\nThen open your browser to the displayed URL (typically `http://localhost:8080`).\n\n\u003e [!NOTE]\n\u003e **LLM Configuration Required**: Set your [LLM provider credentials](https://ashenfad.github.io/agex/api/llm/) (e.g., `GOOGLE_API_KEY` for Gemini).\n\n## Architecture\n\n```\nagex_ui/\n├── core/           # Reusable framework components\n│   ├── events.py       # Event handling and token streaming\n│   ├── file_manager.py # File drawer component (upload/download/delete)\n│   ├── history.py      # Chat history restoration from state\n│   ├── preview.py      # Live preview infrastructure for sandboxed apps\n│   ├── renderers.py    # UI renderers for responses and events\n│   ├── responses.py    # Response type system (Response, ResponsePart, etc.)\n│   ├── session_panel.py# Session management drawer (history/fork/undo)\n│   ├── sessions.py     # Session manager with kvgit branch-backed state\n│   ├── theme.py        # Theme management with CSS variables\n│   ├── turn.py         # Turn orchestration (run_agent_turn)\n│   ├── user_bubble.py  # Shared user bubble rendering with revert support\n│   └── utils.py        # Shared UI utilities\n├── templates/      # UI templates\n│   └── chat_interface.py  # Standard chat interface template (orchestrator)\n├── workshop/       # App builder demo (agent builds NiceGUI apps)\n│   ├── agent.py        # Workshop agent with calgebra + NiceGUI tools\n│   ├── main.py         # Application entry point\n│   ├── nicegui_primer.py # NiceGUI layout and component best practices\n│   └── primer.py       # Agent system prompts\n├── tmnt/           # TMNT demo (local iCal files, no OAuth)\n│   ├── agent.py        # Agent definition with calgebra integration\n│   ├── main.py         # Application entry point\n│   ├── primer.py       # Agent system prompts\n│   └── utils.py        # Calendar loading utilities\n└── cal/            # Google Calendar example (requires OAuth)\n    ├── agent.py        # Agent with Google Calendar integration\n    ├── main.py         # Application entry point\n    ├── primer.py       # Agent system prompts\n    └── utils.py        # Calendar-specific utilities\n```\n\n## Building Your Own Agent-Driven UI\n\nHere's how to create a custom agent-driven chat interface:\n\n### 1. Define Your Agent Task\n\n```python\n# my_agent.py\nfrom agex import Agent, connect_llm\nfrom agex_ui.core.responses import Response\nimport pandas as pd\n\nagent = Agent(\n    name=\"my_agent\",\n    primer=\"You are a helpful assistant...\",\n    llm=connect_llm(provider=\"anthropic\", model=\"claude-haiku-4-5\"),\n)\n\n# Register the Response type\nagent.cls(Response)\n\n@agent.task\ndef handle_prompt(prompt: str) -\u003e Response:\n    \"\"\"Process user prompt and return a multi-part response.\"\"\"\n    # Your agent logic here\n    return Response(parts=[\n        \"Here's your analysis:\",\n        pd.DataFrame({\"col1\": [1, 2, 3]}),\n    ])\n```\n\n### 2. Create the Chat Interface\n\n```python\n# main.py\nfrom nicegui import ui, app\nfrom agex_ui.templates import create_chat_interface, ChatInterfaceConfig\nfrom agex_ui.core.turn import TurnConfig\nfrom my_agent import agent, handle_prompt\n\napp.add_static_files(\"/assets\", \"./assets\")\n\n@ui.page(\"/\")\ndef index():\n    # Create interface (returns chat_messages, chat_input, theme_manager)\n    chat_messages, chat_input, theme = create_chat_interface(\n        agent=agent,\n        agent_task=handle_prompt,\n        config=ChatInterfaceConfig(\n            title=\"My Agent App\",\n            page_title=\"My App\",\n            greeting=\"Hello! How can I help?\",\n        ),\n        turn_config=TurnConfig(\n            show_setup_events=False,\n            enable_token_streaming=True,\n        ),\n    )\n\nui.run()\n```\n\nThat's it! You now have an agent-driven chat interface.\n\n## Response Types\n\nAgents can return any combination of:\n\n- **Text (str)**: Rendered as markdown\n- **DataFrames (pd.DataFrame)**: Rendered as interactive tables\n- **Plotly Figures (go.Figure)**: Rendered as interactive charts\n- **Response**: Multi-part container for combining types\n\n```python\nfrom agex_ui.core.responses import Response\n\n# Single type\nreturn \"Simple text response\"\n\n# Multiple types in one response\nreturn Response(parts=[\n    \"Analysis complete:\",\n    dataframe,\n    plotly_figure,\n    \"Additional notes...\",\n])\n```\n\n## Configuration Options\n\n### ChatInterfaceConfig\n\nCustomize the chat interface appearance:\n\n```python\nChatInterfaceConfig(\n    header_bg_color=\"#5894c8\",     # Header background color\n    title=\"My App\",                 # Header title\n    page_title=\"My App\",            # Browser page title\n    greeting=\"Welcome!\",            # Initial bot message\n    robot_avatar=\"assets/robot.png\",\n    human_avatar=\"assets/human.png\",\n    dark_mode=True,                  # Start in dark mode\n)\n```\n\n### TurnConfig\n\nCustomize turn execution behavior:\n\n```python\nTurnConfig(\n    show_setup_events=False,        # Show/hide agent setup events\n    enable_token_streaming=True,    # Enable real-time token streaming\n    auto_scroll=True,                # Auto-scroll to new messages\n    collapse_agent_activity=True,   # Start with activity collapsed\n)\n```\n\n## Example Agents\n\n### Workshop (App Builder)\n\nThe `workshop` package demonstrates an agent that builds interactive NiceGUI apps. The agent writes and edits app code, which runs in a sandboxed live preview alongside the chat.\n\n- Live preview with sandboxed execution via [`sandtrap`](https://github.com/ashenfad/sandtrap)\n- File management (upload data files, browse agent's virtual filesystem)\n- Debug capture (DOM snapshots, console logs)\n\n```bash\npython -m agex_ui.workshop.main\n```\n\n### TMNT Demo\n\nThe `tmnt` package demonstrates a calendar assistant using local iCal files. No OAuth or external API setup required beyond your LLM credentials.\n\n- Uses [`calgebra`](https://github.com/ashenfad/calgebra) for timeline operations\n- Showcases multi-part responses (text + tables + charts)\n- Demonstrates state persistence with `Versioned` storage\n\n📺 **[Watch the demo](https://youtu.be/10kG4tw0D4k)**\n\n```bash\npython -m agex_ui.tmnt.main\n```\n\n### Google Calendar Assistant (Advanced)\n\nThe `cal` package demonstrates Google Calendar integration.\n\n\u003e [!WARNING]\n\u003e Requires [Google Calendar OAuth credentials](https://google-calendar-simple-api.readthedocs.io/en/latest/getting_started.html#credentials).\n\n```bash\npython -m agex_ui.cal.main\n```\n\n## Design Philosophy\n\n**Agent-Agnostic Core**: The framework doesn't create or configure agents. You define your agent with domain-specific setup, then pass its task function to the UI framework.\n\n**Separation of Concerns**:\n- **Core**: UI orchestration, rendering, event handling (framework layer)\n- **Templates**: Reusable layouts and configurations (presentation layer)\n- **Your Agent**: Domain logic, tools, prompts (application layer)\n\nThis architecture ensures the framework remains flexible and reusable across different agent implementations.\n\n## Learn More\n\n- **agex Documentation**: [ashenfad.github.io/agex/](https://ashenfad.github.io/agex/)\n- **calgebra Documentation**: [github.com/ashenfad/calgebra](https://github.com/ashenfad/calgebra)\n- **NiceGUI Documentation**: [nicegui.io](https://nicegui.io/)\n\n## License\n\nMIT License - See [LICENSE](LICENSE) file for details.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fashenfad%2Fagex-ui","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fashenfad%2Fagex-ui","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fashenfad%2Fagex-ui/lists"}