Virtual Agents Debate Workspace built with Flutter and Riverpod.

Flutter Agents Club is a virtual workspace where AI agents engage in structured debates within grid-based rooms. Users can create custom agents, organize rooms, configure debate parameters, and observe simulations using mock, cloud, or local LLM responses with optional MCP tool calls.

• Responsive Layout: Wide split view for desktop/tablet and bottom navigation for mobile.
• Interactive Grid Map: Zoom/pan, context menus, and draggable agents.
• Agent Factory: Personas, roles, icons/colors, LLM provider/model selection, local models, and MCP tool binding.
• Room & Zone Management: Room/zone naming, adjustable room grid size, presets, and agent sorting/clearing.
• Debate Simulation: Moderated/round-robin/free-for-all/workflow modes, end conditions, speech bubbles, and conclusions.
• Workflow Builder: Node-based turn order with examples and tool nodes.
• MCP Tools: HTTP/stdio server config, tool discovery, and tool-call logs.
• Knowledge Base: Notes plus text/markdown file uploads.
• Logs & Snapshots: Room logs (Markdown), agent history, app logs, and room snapshot JSON export/import.
• Localization & Themes: EN/KO/JA/ZH and light/dark/system toggle.

• Language: Dart
• Framework: Flutter (SDK ^3.10.7)
• State Management: Riverpod (flutter_riverpod)
• Networking: Http
• Local Storage: shared_preferences
• Markdown Rendering: gpt_markdown
• Workflow Builder: vyuh_node_flow
• Tooling: mcp_dart
• Logging: logging
• File Picker: file_picker

lib/
├── l10n/          # Localization files (ARB)
├── models/        # Data models and entities
├── providers/     # Riverpod state providers
├── screens/       # Main application screens
├── services/      # Business logic, storage, and API services
├── theme/         # App theme and styling
└── widgets/       # Reusable UI components
docs/              # Project documentation and plan

• Flutter SDK (^3.10.7)
• Dart SDK
• (Optional) API Keys for Google Gemini or OpenAI
• (Optional) Local LLM server (Ollama or LM Studio)
• (Optional) MCP server for tool calls

1. Clone the repository:

   git clone https://github.com/your-username/flutter_agents_club.git
   cd flutter_agents_club

2. Install dependencies:

   flutter pub get

Run the application using the Flutter CLI:

flutter run

To use real LLM responses, provide API keys and/or local server URLs:

1. Open the app.
2. Navigate to the Settings tab.
3. Enter your Gemini API Key and/or OpenAI API Key.
4. (Optional) Set Ollama or LM Studio base URLs and refresh models.
5. Settings are persisted locally on your device.

To enable MCP tools:

1. Open the Tools tab.
2. Add MCP servers (HTTP or stdio depending on platform support).
3. Refresh tools and bind them to agents or workflow tool nodes.

Standard Flutter commands are used for development:

• TODO: Implement unit and widget tests for debate scheduling, persistence, workflow validation, and MCP tool parsing.
• Currently, no automated tests are included in the repository.

For more detailed information on the product intent and workflows, see:

• docs/plan_workflow.md: Product plan and detailed workflows.
• docs/project_plan_and_workflow_ko.md: Korean plan and workflow overview.
• docs/prd_ko.md: Korean PRD reflecting current implementation.
• AGENTS.md: AI Interaction guidelines and project technical constraints.

This project is licensed under the BSD 3-Clause License - see the LICENSE file for details.