open-swarm 0.1.1745274103__py3-none-any.whl → 0.1.1745274144__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: open-swarm
3
- Version: 0.1.1745274103
3
+ Version: 0.1.1745274144
4
4
  Summary: Open Swarm: Orchestrating AI Agent Swarms with Django
5
5
  Project-URL: Homepage, https://github.com/yourusername/open-swarm
6
6
  Project-URL: Documentation, https://github.com/yourusername/open-swarm/blob/main/README.md
@@ -86,6 +86,28 @@ Requires-Dist: respx>=0.20.0; extra == 'test'
86
86
  Requires-Dist: sseclient-py>=1.7.2; extra == 'test'
87
87
  Description-Content-Type: text/markdown
88
88
 
89
+ # 🚀 Open Swarm — S-Tier Onboarding
90
+
91
+ Welcome to Open Swarm! Orchestrate, manage, and run AI agent blueprints with S-tier onboarding and UX polish.
92
+
93
+ ## Quickstart
94
+
95
+ 1. List blueprints:
96
+ ```bash
97
+ swarm-cli list
98
+ ```
99
+ 2. Run the demo blueprint:
100
+ ```bash
101
+ swarm-cli run hello_world --instruction "Hello, world!"
102
+ ```
103
+ 3. Install as command:
104
+ ```bash
105
+ swarm-cli install hello_world
106
+ ./hello_world "Hello, world!"
107
+ ```
108
+
109
+ For advanced features, see below or run `swarm-cli help`.
110
+
89
111
  # Open Swarm
90
112
 
91
113
  <div align="center">
@@ -101,12 +123,26 @@ Open Swarm can be used in two primary ways:
101
123
 
102
124
  ---
103
125
 
126
+ ## Development Setup (Editable Install)
127
+
128
+ If you are working from a cloned repository or developing Open Swarm locally, you must install the package in editable mode before using the CLI or API tools:
129
+
130
+ ```bash
131
+ pip install -e .
132
+ ```
133
+
134
+ This ensures that the `swarm-cli` and `swarm-api` commands point to the latest source code and are available in your PATH. After running this, you can use the CLI commands as described below.
135
+
136
+ ---
137
+
104
138
  ## Configuration & Quickstart
105
139
 
106
140
  See [CONFIGURATION.md](./CONFIGURATION.md) for a full guide to Swarm configuration—including LLM setup, MCP server integration, per-blueprint overrides, pricing, and CLI vs manual workflows.
107
141
 
108
142
  You can configure everything interactively using `swarm-cli configure` or by manually editing your config file (see guide for details and examples).
109
143
 
144
+ > **Note:** In development mode, some CLI commands or features may differ from the published PyPI version. If you encounter issues, ensure you have run `pip install -e .` and that your environment is activated.
145
+
110
146
  ---
111
147
 
112
148
  ## Core Framework TODO
@@ -143,59 +179,122 @@ You can configure everything interactively using `swarm-cli configure` or by man
143
179
 
144
180
  ---
145
181
 
146
- ## New in Geese: Notifier Abstraction & Reflection
182
+ ## 🚀 Unified Blueprint Search & Analysis UX
183
+
184
+ Open Swarm blueprints now deliver a consistent, branded, and user-friendly experience for all search and analysis operations. Each blueprint leverages:
185
+
186
+ - **ANSI/emoji result boxes** summarizing search/analysis results, parameters, and counts
187
+ - **Progress spinners** ("Generating...", "Taking longer than expected") with live line/progress updates
188
+ - **Distinct emoji branding** for each blueprint (e.g., 🌳 Family Ties, 🪶 Unapologetic Poets, 🦢 Gaggle)
189
+ - **Clear feedback** for subprocess management and onboarding
190
+
191
+ <!-- BLUEPRINT_TABLE_START -->
192
+ <!-- The following table is auto-generated. Do not edit manually. Run scripts/gen_blueprint_table.py to update. -->
193
+
194
+ | Emoji | Name | Description | Example Commands | Branding |
195
+ |-------|------|-------------|------------------|----------|
196
+ | | `ChatbotBlueprint` | A basic conversational agent that responds to user input. | | |
197
+ | | `ZeusBlueprint` | Zeus leads a pantheon for software dev & sysadmin tasks, coordinating via agent-as-tool delegation. (DivineOpsBlueprint merged into this) | | |
198
+ | | `FamilyTiesBlueprint` | Manages WordPress content using Peter (coordinator) and Brian (WP manager via MCP). | | |
199
+ | | `JeevesBlueprint` | Provides private web search (DuckDuckGo) and home automation (Home Assistant) via specialized agents (Jeeves, Mycroft, Gutenberg). | | |
200
+ | | `MCPDemoBlueprint` | A scalable agent (Sage) demonstrating interaction with filesystem and memory MCP servers, supporting horizontal scaling and viral file operations. | | |
201
+ | | `MissionImprobableBlueprint` | A cheeky team led by JimFlimsy (coordinator), CinnamonToast (strategist/filesystem), and RollinFumble (operative/shell). Uses SQLite for instructions. | | |
202
+ | | `MonkaiMagicBlueprint` | A *Monkai Magic*-inspired crew managing AWS, Fly.io, and Vercel with pre-authenticated CLI tools and agent-as-tool delegation. | | |
203
+ | | `NebulaShellzzarBlueprint` | A multi-agent blueprint inspired by The Matrix for system administration and coding tasks. | | |
204
+ | | `OmniplexBlueprint` | Dynamically delegates tasks to agents (Amazo:npx, Rogue:uvx, Sylar:other) based on the command type of available MCP servers. | | |
205
+ | | `PoetsBlueprint` | A swarm of agents embodying legendary poets, using SQLite for instructions, agent-as-tool for collaboration, and MCPs for creative augmentation. | | |
206
+ | | `RueCode` | Generates, executes code, and interacts with the file system. | | |
207
+ | | `SuggestionBlueprint` | An agent that provides structured suggestions using Agent(output_type=...). | | |
208
+ | | `UnapologeticPoetsBlueprint` | A swarm of agents embodying legendary poets, using SQLite for instructions, agent-as-tool for collaboration, and MCPs for creative augmentation. | | |
209
+ | | `WhiskeyTangoFoxtrotBlueprint` | Tracks free online services with SQLite and web search using a multi-tiered agent hierarchy. | | |
210
+ | 🤖 | `codey` | Code and semantic code search/analysis. | swarm-cli codey /codesearch recursion . 5<br>swarm-cli codey /semanticsearch asyncio . 3 | Unified ANSI/emoji box UX, spinner, progress, summary |
211
+ | 🦢 | `gaggle` | Minimal test/demo search blueprint. | swarm-cli gaggle /search alpha . 5<br>swarm-cli gaggle /analyze beta . 2 | Unified ANSI/emoji box UX, spinner, progress, summary |
212
+ | | `DivineOpsBlueprint` (historical, merged into ZeusBlueprint) | | | |
213
+ | | `divine_code` (historical, merged into ZeusBlueprint) | | | |
214
+ <!-- BLUEPRINT_TABLE_END -->
215
+
216
+ - All commands support `/analyze` as well as `/search` (e.g., `/analyze beta . 5`).
217
+ - Try the commands above to see the new UX in action!
218
+
219
+ ### Key Features
220
+ - **Result counts** and summaries in every result box
221
+ - **Live progress updates** during long-running operations
222
+ - **Custom spinner messages** for clear feedback
223
+ - **Fallback echo** for other commands, always in a result box
224
+
225
+ ---
226
+
227
+ ## 🚀 Unified Spinner and Result Output for Blueprints
147
228
 
148
- - The Geese blueprint now uses a Notifier abstraction for all user-facing output (operation boxes, errors, info), enabling easy redirection to different UIs or for testing.
149
- - Plan reflection and operation transparency: After every agent operation, the current plan, all tool outputs, and any errors are displayed directly to the user, not just logged.
150
- - The Notifier can be extended or swapped for custom UX and is available to all blueprints for unified output handling.
229
+ All blueprints must use `print_search_progress_box` for spinner/progress/result output. See [`src/swarm/blueprints/blueprint_template.py`](src/swarm/blueprints/blueprint_template.py) for a canonical implementation.
151
230
 
152
- See `src/swarm/blueprints/geese/README.md` for usage and extension details.
231
+ - Distinguish between code and semantic search.
232
+ - Show spinner sequence: "Generating.", "Generating..", "Generating...", "Running...", and "Generating... Taking longer than expected".
233
+ - Update line numbers and result counts during progress.
234
+ - Always emit a summary/result box at the end.
235
+ - Pass all test suite checks for spinner/result output.
236
+
237
+ **Review Checklist:**
238
+ - [ ] Uses `print_search_progress_box` for all output
239
+ - [ ] Distinguishes code/semantic search
240
+ - [ ] Shows spinner sequence and “Taking longer than expected”
241
+ - [ ] Progress boxes update lines/results
242
+ - [ ] Passes all tests
153
243
 
154
244
  ---
155
245
 
156
- ## Codex CLI Feature Parity Checklist
157
-
158
- This project aims to provide full feature parity with the OpenAI Codex CLI. Below is a checklist of Codex features and their current status in Open Swarm/codey:
159
-
160
- ### Already Implemented
161
- - Rich output/emoji/spinner UX (unified for search, analysis, file ops)
162
- - Modular blueprint/agent system
163
- - Basic interactive CLI mode
164
- - Basic approval mode for some agent actions
165
- - Syntax-highlighted code output
166
- - Session/history management and overlays
167
- - Full-context mode for large refactor/analysis
168
- - Writable root/sandboxing CLI/config support
169
- - Command suggestions/typeahead/autocomplete for CLI and slash commands
170
- - Help and onboarding overlays
171
- - Desktop notification support (optional)
172
- - Dangerous auto-approve flag/UX
173
- - Output formatting/full stdout option
174
- - Image input (CLI/UX, future-proof)
175
-
176
- ### ⚠️ Partially Implemented
177
- - Approval modes (full-auto, interactive, granular gating) for all actions
178
- - Directory sandboxing (not enforced everywhere, no network controls)
179
- - CLI/config file support (not unified or live-reloadable)
180
- - Version control integration (git ops for suggest mode only)
181
- - Slash commands: `/help`, `/model`, `/approval`, `/history`, `/ls`, `/cat`, `/edit`, `/compact` (some available)
182
- - Project-level instructions auto-loading
183
-
184
- ### ❌ Not Yet Implemented
185
- - Auto dependency install for generated code
186
- - Automatic context/project file injection
187
- - Plan/changelog file maintenance
188
- - User feedback/correction loop
189
- - Persistent session logging/audit trail
190
- - Streaming token-by-token CLI output
191
- - Non-interactive/CI/headless mode
192
- - Multimodal input (screenshots/diagrams)
193
- - Atomic commit/rollback for all agent actions
194
- - Safety/ZDR org restrictions
246
+ ## Continuous Compliance
247
+
248
+ This project uses an automated compliance audit for all blueprint metadata. Every push and pull request is checked for standards compliance via GitHub Actions. If any blueprint fails compliance, the build will fail.
249
+
250
+ - Audit script: `scripts/audit_blueprint_compliance.py`
251
+ - Workflow: `.github/workflows/compliance-audit.yml`
252
+
253
+ To run the audit locally:
254
+
255
+ ```bash
256
+ python3 scripts/audit_blueprint_compliance.py
257
+ ```
258
+
259
+ ---
260
+
261
+ ## Blueprint UX Compliance & Test Mode
262
+
263
+ Open Swarm blueprints must provide a consistent, user-friendly CLI experience. All blueprints must:
264
+ - Display custom spinner messages: `Generating.`, `Generating..`, `Generating...`, `Running...`, and `Generating... Taking longer than expected` for long operations.
265
+ - Use ANSI/emoji boxes to summarize operations, results, and parameters (see `print_search_progress_box`).
266
+ - Clearly distinguish between code search, semantic search, and analysis operations in the output.
267
+ - In test mode (`SWARM_TEST_MODE=1`), output must be deterministic and include all spinner/box states for compliance tests.
268
+ - For more, see `docs/blueprint_standards.md` and `docs/blueprint_test_mode_ux.md`.
269
+
270
+ To check compliance or debug output, run:
271
+ ```bash
272
+ uv run pytest -v tests/blueprints
273
+ ```
274
+
275
+ For automated compliance checking, see `scripts/check_ux_compliance.py`.
195
276
 
196
277
  ---
197
278
 
198
- **See the codey blueprint README for blueprint-specific feature status and TODOs.**
279
+ ## What to Try Next
280
+
281
+ - **Try Code Search:**
282
+ - `swarm-cli codey /codesearch <keyword> <path> <max_results>`
283
+ - Example: `swarm-cli codey /codesearch recursion . 5`
284
+ - Try `/semanticsearch` for semantic code search with rich result boxes, result counts, and progressive spinner.
285
+
286
+ - **Try WhingeSurf Async UX:**
287
+ - `swarm-cli whinge_surf !run sleep 2`
288
+ - Then: `swarm-cli whinge_surf !status <process_id>`
289
+ - Demonstrates async subprocess management and status polling.
290
+
291
+ - **Discover Blueprints:**
292
+ - `swarm-cli info <blueprint>`
293
+ - Shows blueprint description, usage, and onboarding tips.
294
+
295
+ - **Get Help:**
296
+ - `swarm-cli --help` or `swarm-cli codey --help`
297
+ - For onboarding, command list, and usage examples.
199
298
 
200
299
  ---
201
300
 
@@ -239,6 +338,9 @@ pip install -e .
239
338
 
240
339
  ```bash
241
340
  swarm-cli --help
341
+ swarm-cli run hello_world --instruction "Hello from CLI!"
342
+ python src/swarm/blueprints/hello_world/blueprint_hello_world.py Hello from CLI!
343
+ ./hello_world Hello from CLI!
242
344
  swarm-api --help
243
345
  ```
244
346
 
@@ -335,22 +437,18 @@ Open Swarm and its blueprints use a variety of environment variables for configu
335
437
  | `DJANGO_CSRF_TRUSTED_ORIGINS` | Comma-separated trusted origins for CSRF protection | `http://localhost:8000,...`|
336
438
  | `ENABLE_ADMIN` | Enable admin web interface | `false` |
337
439
  | `ENABLE_API_AUTH` | Require API authentication | `true` |
338
- | `SWARM_COMMAND_TIMEOUT` | Timeout in seconds for all shell commands run by blueprints | Optional (recommended) |
339
440
 
340
441
  #### Blueprint/Tool-Specific Variables
341
442
  - Some blueprints and MCP tools may require additional env vars (e.g., Google API keys, Slack tokens, etc.).
342
443
  - Refer to the blueprint's docstring or config for details.
343
444
 
344
- #### Timeout Configuration
345
- - **SWARM_COMMAND_TIMEOUT**: Controls the maximum time (in seconds) a shell command is allowed to run in any blueprint. If not set, defaults to 60 seconds for most commands, 120 seconds for cloud CLI tools (AWS, Fly.io, Vercel).
346
- - Set via environment variable: `export SWARM_COMMAND_TIMEOUT=90`
347
- - If a command exceeds the timeout, a clear error message will be shown in the CLI or operation box.
348
- - Applies to all blueprints and CLI tools that execute shell commands.
349
- - To override for a single run: `SWARM_COMMAND_TIMEOUT=30 swarm-cli run ...`
350
-
351
- #### Test Timeouts
352
- - All integration tests have a global timeout (30s) via pytest-timeout.
353
- - Some tests have explicit per-test timeouts (see test source for details).
445
+ #### Usage Example
446
+ ```bash
447
+ export OPENAI_API_KEY="sk-..."
448
+ export SWARM_API_KEY="..."
449
+ export LITELLM_BASE_URL="https://open-litellm.fly.dev/v1"
450
+ # ... set other variables as needed
451
+ ```
354
452
 
355
453
  ---
356
454
 
@@ -442,6 +540,110 @@ Commands:
442
540
 
443
541
  ---
444
542
 
543
+ ## Blueprint Metadata: Developer Guide
544
+
545
+ All blueprints must define a class-level `metadata` property for onboarding, CLI discovery, and documentation automation. This property should be a Python dictionary and include the following keys:
546
+
547
+ - `name`: The blueprint's canonical name (string)
548
+ - `emoji`: The blueprint's emoji branding (string)
549
+ - `description`: Short description for CLI/docs (string)
550
+ - `examples`: List of CLI example commands (list of strings)
551
+ - `commands`: List of supported commands (list of strings)
552
+ - `branding`: Description of the UX/branding features (string)
553
+
554
+ **Example:**
555
+ ```python
556
+ class FamilyTiesBlueprint(BlueprintBase):
557
+ metadata = {
558
+ "name": "family_ties",
559
+ "emoji": "🌳",
560
+ "description": "Genealogy/family data search and analysis.",
561
+ "examples": [
562
+ "swarm-cli family_ties /search Smith . 5",
563
+ "swarm-cli family_ties /analyze Johnson . 3"
564
+ ],
565
+ "commands": ["/search", "/analyze"],
566
+ "branding": "Unified ANSI/emoji box UX, spinner, progress, summary"
567
+ }
568
+ ```
569
+
570
+ This metadata is used by the CLI for `swarm-cli blueprint list` and `swarm-cli blueprint info <name>`, and for onboarding/documentation automation. **Always update the `metadata` property when adding or modifying a blueprint.**
571
+
572
+ ---
573
+
574
+ ## Test Database Setup (Django + SQLite)
575
+
576
+ - The Django test database is configured to use a file in `/tmp` to avoid permission issues:
577
+ - Path: `/tmp/tmp.FwE9ucN97b/test_db.sqlite3`
578
+ - Journal mode is set to `DELETE` for maximum compatibility and to avoid WAL file locking issues in CI and local runs.
579
+ - Before running tests, the test DB file is deleted to prevent corruption or stale locks.
580
+ - **Automated cleanup:** Use `make test` or run `bash scripts/pretest_cleanup.sh` before tests to automatically remove any stale test DB files in `/tmp`.
581
+ - If you encounter `readonly database` or `disk I/O error` during tests:
582
+ 1. Delete the test DB file manually: `rm -f /tmp/tmp.FwE9ucN97b/test_db.sqlite3`
583
+ 2. Or use `make pretest-clean` to remove all test DBs.
584
+ 3. Re-run your tests.
585
+ - For CI, add a pre-test cleanup step to always remove the test DB file before running tests (see `scripts/pretest_cleanup.sh`).
586
+ - To prevent DB lock/readonly errors, ensure `/tmp` has free space and is not mounted read-only.
587
+
588
+ ---
589
+
590
+ ## Troubleshooting
591
+ - Ensure `/tmp` has free space and is not mounted read-only.
592
+ - If you see persistent DB errors, check for OS-level security restrictions or concurrent test runs.
593
+
594
+ ---
595
+
596
+ ## Security
597
+ - Never commit `.env` or sensitive config files to version control.
598
+ - Review environment variable usage for API keys and secrets.
599
+
600
+ ---
601
+
602
+ ## Acknowledgements
603
+
604
+ This project builds upon concepts and code from the `openai-agents` library and potentially other open-source projects. Specific acknowledgements can be found in `DEVELOPMENT.md` or individual source files.
605
+
606
+ ---
607
+
608
+ ## License
609
+
610
+ Open Swarm is provided under the MIT License. Refer to the [LICENSE](LICENSE) file for full details.
611
+
612
+ ---
613
+
614
+ ## Contributing
615
+
616
+ Contributions are welcome! Please refer to the `CONTRIBUTING.md` file (if available) or open an issue/pull request on the repository.
617
+
618
+ ---
619
+
620
+ ## Quickstart for Contributors
621
+
622
+ - **Run all tests and check UX compliance:**
623
+ ```bash
624
+ uv run pytest -v tests/blueprints
625
+ python scripts/check_ux_compliance.py
626
+ ```
627
+ - **Check code style (lint):**
628
+ ```bash
629
+ ruff check .
630
+ ```
631
+ - **Check coverage:**
632
+ ```bash
633
+ uv run pytest --cov=src --cov-report=term-missing tests/blueprints
634
+ ```
635
+ - **Add new blueprints:**
636
+ - Follow the standards in `docs/blueprint_standards.md` and `docs/blueprint_test_mode_ux.md`.
637
+ - Ensure spinner/box/emoji/summary output is present in test mode (`SWARM_TEST_MODE=1`).
638
+ - Add or update tests in `tests/blueprints/`.
639
+ - **CI/CD:**
640
+ - All PRs are checked for spinner/box/emoji/summary compliance, lint, and coverage.
641
+ - Warnings are surfaced for missing UX elements in test mode, but do not block merges.
642
+
643
+ See the docs and scripts for more details on compliance and extending Open Swarm.
644
+
645
+ ---
646
+
445
647
  ## Quickstart 1: Using `swarm-cli` Locally (via PyPI)
446
648
 
447
649
  This is the recommended way to use `swarm-cli` for managing and running blueprints on your local machine.
@@ -472,28 +674,33 @@ This is the recommended way to use `swarm-cli` for managing and running blueprin
472
674
  * Add it using `swarm-cli`:
473
675
  ```bash
474
676
  # Example: Adding a downloaded blueprint file
475
- swarm-cli add ./path/to/downloaded/blueprint_echocraft.py
677
+ swarm-cli add ./path/to/downloaded/blueprint_hello_world.py
476
678
 
477
679
  # Example: Adding a directory containing a blueprint
478
680
  swarm-cli add ./my_custom_blueprints/agent_smith --name agent_smith
479
681
  ```
480
682
 
481
683
  4. **Run the Blueprint:**
482
- * **Single Instruction:**
684
+ * **Single Instruction (recommended):**
483
685
  ```bash
484
- swarm-cli run echocraft --instruction "Hello from CLI!"
686
+ swarm-cli run hello_world --instruction "Hello from CLI!"
485
687
  ```
486
688
  * **Interactive Mode:**
487
689
  ```bash
488
- swarm-cli run echocraft
690
+ swarm-cli run hello_world
489
691
  # Now you can chat with the blueprint interactively
490
692
  ```
693
+ * **Direct Python or Binary Execution:**
694
+ ```bash
695
+ python src/swarm/blueprints/hello_world/blueprint_hello_world.py Hello from CLI!
696
+ ./hello_world Hello from CLI!
697
+ ```
491
698
 
492
699
  5. **(Optional) Install as Command:**
493
700
  ```bash
494
- swarm-cli install echocraft
701
+ swarm-cli install hello_world
495
702
  # Now run (ensure ~/.local/share/swarm/bin is in your PATH):
496
- echocraft --instruction "I am a command now!"
703
+ ./hello_world Hello from CLI!
497
704
  ```
498
705
 
499
706
  ---
@@ -537,7 +744,7 @@ This method uses `docker-compose.yaml` and is best if you need to customize volu
537
744
 
538
745
  6. **Verify API:** (Default port 8000)
539
746
  * Models: `curl http://localhost:8000/v1/models`
540
- * Chat: `curl http://localhost:8000/v1/chat/completions -H "Content-Type: application/json" -d '{"model": "echocraft", ...}'` (Add `-H "Authorization: Bearer <key>"` if needed).
747
+ * Chat: `curl http://localhost:8000/v1/chat/completions -H "Content-Type: application/json" -d '{"model": "hello_world", ...}'` (Add `-H "Authorization: Bearer <key>"` if needed).
541
748
 
542
749
  ### Option B: Direct `docker run` (Simpler for Single Container)
543
750
 
@@ -599,21 +806,69 @@ This README provides a high-level overview and quickstart guides. For more detai
599
806
  * **Example Blueprints (`src/swarm/blueprints/README.md`):** A list and description of the example blueprints included with the framework, showcasing various features and integration patterns.
600
807
  * **Blueprint Patterns and Configuration (`blueprints/README.md`):** Guidance on creating and configuring blueprints, including best practices and common pitfalls. **Start here for blueprint usage and extension.**
601
808
  * **User Experience Standards (`UX.md`):** Guidelines for creating a consistent and user-friendly experience across blueprints and the Swarm framework.
809
+ * **User Experience Standards (`UX.md`)**: Guidelines for creating a consistent and user-friendly experience across blueprints and the Swarm framework.
602
810
 
603
811
  ---
604
812
 
605
- ## Contributing
813
+ ## Blueprint Compliance Report
606
814
 
607
- Contributions are welcome! Please refer to the `CONTRIBUTING.md` file (if available) or open an issue/pull request on the repository.
815
+ To generate a Markdown compliance report for all blueprints, run:
816
+
817
+ ```bash
818
+ python3 scripts/generate_blueprint_report.py
819
+ ```
820
+
821
+ This will output `BLUEPRINT_COMPLIANCE_REPORT.md` in the project root, summarizing compliance, test coverage, spinner/continuation command usage, and missing fields for every blueprint.
608
822
 
609
823
  ---
610
824
 
611
- ## License
825
+ ## Blueprint Scaffolding
612
826
 
613
- Open Swarm is provided under the MIT License. Refer to the [LICENSE](LICENSE) file for full details.
827
+ To create a new, fully compliant blueprint with metadata, README, and test stub, run:
828
+
829
+ ```bash
830
+ python3 scripts/scaffold_blueprint.py
831
+ ```
832
+
833
+ This script will prompt for the blueprint name and description, set up all required files, and ensure compliance fields are present from the start.
614
834
 
615
835
  ---
616
836
 
617
- ## Acknowledgements
837
+ ## Blueprint Compliance & Automation
618
838
 
619
- This project builds upon concepts and code from the `openai-agents` library and potentially other open-source projects. Specific acknowledgements can be found in `DEVELOPMENT.md` or individual source files.
839
+ Open Swarm enforces high standards for all blueprints. The following scripts help automate compliance and quality:
840
+
841
+ - `scripts/list_blueprints.py [--missing-descriptions]` — List all blueprints, or only those missing meaningful descriptions.
842
+ - `scripts/check_blueprint_descriptions.py` — Check for missing or placeholder descriptions in blueprint metadata.
843
+ - `scripts/fix_blueprint_descriptions.py [--auto-fill]` — Batch-remediate missing descriptions interactively or with an auto-filled template.
844
+ - `scripts/check_blueprint_tests.py` — Ensure every blueprint has an associated test file.
845
+ - `scripts/check_stub_tests.py` — Flag test files that only contain stubs (e.g., `assert True` or TODOs).
846
+ - `scripts/check_spinner_compliance.py` — Verify required spinner messages and continuation commands are present.
847
+ - `scripts/check_ux_compliance.py` — Ensure all blueprints have required UX/CLI compliance fields (`agentic`, `ux_ansi_emoji`, `spinner`, `fallback`).
848
+ - `scripts/generate_blueprint_report.py` — Generate a Markdown compliance report including stub test and description status.
849
+
850
+ ### Continuous Integration
851
+
852
+ All compliance scripts are integrated into CI via GitHub Actions. PRs and pushes are checked for:
853
+ - Required blueprint metadata fields
854
+ - Non-placeholder descriptions
855
+ - Presence of test files
856
+ - Required spinner/UX/CLI fields
857
+ - Absence of stub-only tests (warning)
858
+
859
+ ### Improving Test Coverage
860
+ Blueprints flagged with stub-only tests should have their test files expanded to cover real functionality. See the compliance report for guidance.
861
+
862
+ ## Blueprint Scaffolding
863
+
864
+ Automate new blueprint creation with:
865
+ - `scripts/scaffold_blueprint.py` — Scaffold a new, compliant blueprint with all required files and metadata.
866
+
867
+ ## CLI Tools
868
+
869
+ - `scripts/list_blueprints.py` — Discover and filter blueprints.
870
+ - `scripts/generate_blueprint_report.py` — Generate and review compliance status.
871
+
872
+ ## Contributing
873
+
874
+ Please ensure all blueprints and contributions pass compliance and quality checks before submitting PRs.
@@ -298,8 +298,8 @@ swarm/views/message_views.py,sha256=sDUnXyqKXC8WwIIMAlWf00s2_a2T9c75Na5FvYMJwBM,
298
298
  swarm/views/model_views.py,sha256=aAbU4AZmrOTaPeKMWtoKK7FPYHdaN3Zbx55JfKzYTRY,2937
299
299
  swarm/views/utils.py,sha256=8Usc0g0L0NPegNAyY20tJBNBy-JLwODf4VmxV0yUtpw,3627
300
300
  swarm/views/web_views.py,sha256=T1CKe-Nyv1C8aDt6QFTGWo_dkH7ojWAvS_QW9mZnZp0,7371
301
- open_swarm-0.1.1745274103.dist-info/METADATA,sha256=FUcmOqd3IJE4oWlDIEljW7ZsTIiqD0wWjFCeH_8ovH4,27659
302
- open_swarm-0.1.1745274103.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
303
- open_swarm-0.1.1745274103.dist-info/entry_points.txt,sha256=fo28d0_zJrytRsh8QqkdlWQT_9lyAwYUx1WuSTDI3HM,177
304
- open_swarm-0.1.1745274103.dist-info/licenses/LICENSE,sha256=BU9bwRlnOt_JDIb6OT55Q4leLZx9RArDLTFnlDIrBEI,1062
305
- open_swarm-0.1.1745274103.dist-info/RECORD,,
301
+ open_swarm-0.1.1745274144.dist-info/METADATA,sha256=Gu5RsJQzVJsuevK958EYwFyXxvprqlprVII7gSiJInk,39330
302
+ open_swarm-0.1.1745274144.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
303
+ open_swarm-0.1.1745274144.dist-info/entry_points.txt,sha256=fo28d0_zJrytRsh8QqkdlWQT_9lyAwYUx1WuSTDI3HM,177
304
+ open_swarm-0.1.1745274144.dist-info/licenses/LICENSE,sha256=BU9bwRlnOt_JDIb6OT55Q4leLZx9RArDLTFnlDIrBEI,1062
305
+ open_swarm-0.1.1745274144.dist-info/RECORD,,