devrel-swarm 0.2.4__tar.gz

devrel_swarm-0.2.4/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daria Dovzhikova
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

devrel_swarm-0.2.4/PKG-INFO

@@ -0,0 +1,308 @@
+Metadata-Version: 2.4
+Name: devrel-swarm
+Version: 0.2.4
+Summary: A 13-agent CLI that runs DevRel, sales, and marketing on your repo. BYO Anthropic key.
+Author-email: Daria Dovzhikova <dovzhikova@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/dovzhikova/devrel-swarm
+Project-URL: Repository, https://github.com/dovzhikova/devrel-swarm
+Project-URL: Issues, https://github.com/dovzhikova/devrel-swarm/issues
+Project-URL: Changelog, https://github.com/dovzhikova/devrel-swarm/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://github.com/dovzhikova/devrel-swarm/tree/main/docs
+Keywords: devrel,developer-advocacy,ai-agents,anthropic,claude,marketing-automation,content-pipeline,competitive-intelligence,cli,pipx
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
+Classifier: Topic :: Office/Business
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: anthropic>=0.28.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: scipy>=1.13.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: tenacity>=8.2.0
+Requires-Dist: PyGithub>=2.1.1
+Requires-Dist: typer>=0.12.0
+Requires-Dist: rich>=13.7.0
+Requires-Dist: tomli-w>=1.0.0
+Provides-Extra: video
+Requires-Dist: openai>=1.50.0; extra == "video"
+Requires-Dist: playwright>=1.49.0; extra == "video"
+Requires-Dist: pyautogui>=0.9.54; extra == "video"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
+Requires-Dist: respx>=0.20.2; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: mypy>=1.5.0; extra == "dev"
+Requires-Dist: build>=1.0.0; extra == "dev"
+Requires-Dist: twine>=5.0.0; extra == "dev"
+Requires-Dist: devrel-swarm[video]; extra == "dev"
+Dynamic: license-file
+
+# devrel-swarm
+
+**A developer-first CLI for AI-powered DevRel, sales, and marketing.**
+
+`devrel-swarm` is a `pipx`-installable command-line tool that runs a 13-agent system against any project — community triage, social listening, theme extraction, growth experiments, content production, video tutorials, documentation, competitive intel, sales outreach, brand-consistent campaigns, and post-publish content performance analysis. Operates on a project repo the way `git`, `npm`, and `cargo` do.
+
+Every piece of content the system produces flows through an 8-stage editorial pipeline (developmental edit → line edit → copy edit → anti-slop → reader-persona test → readability check → brand audit) so output reads like senior-editor work, not generic AI prose.
+
+> Every deliverable in this repository was produced by the agent system itself.
+
+---
+
+## Quick start
+
+```bash
+pipx install devrel-swarm
+
+cd /path/to/your/project
+devrel init --name myproject --url https://myproject.dev --github-repo me/myproject
+
+# edit .devrel/voice.md, .devrel/style.md, .devrel/slop-blocklist.md
+
+export ANTHROPIC_API_KEY=sk-ant-...
+devrel doctor                                  # check env + scaffold
+devrel content draft "tutorial on feature flags" --type tutorial
+devrel run                                     # full weekly pipeline
+```
+
+After `devrel init`, your repo has a `.devrel/` directory with:
+
+```
+.devrel/
+  config.toml          # product identity, model selection, budget caps
+  voice.md             # tone profile + sample passages    (commit)
+  style.md             # house style + per-content targets (commit)
+  slop-blocklist.md    # banned phrases                    (commit)
+  kb/                  # knowledge base, TF-IDF indexed
+  deliverables/        # generated outputs
+  state.db             # SQLite: jobs, costs, checkpoints
+```
+
+The four committed files (`config.toml`, `voice.md`, `style.md`, `slop-blocklist.md`) encode the editorial contract. Diff them like any other source.
+
+---
+
+## Commands
+
+```
+# Bootstrap & health
+devrel init                      bootstrap .devrel/ in cwd
+devrel doctor [--json]           check env, API keys, KB freshness
+devrel cost [--month YYYY-MM]    token + USD report from state.db
+
+# Pipelines
+devrel run                       full weekly cycle
+devrel run --health              health check only (Watchdog)
+devrel run --agent NAME --task T run a single agent ad-hoc
+
+# DevRel
+devrel triage [--days N]         GitHub issue triage (Sage)
+devrel listen [--platforms ...]  Reddit / HN / X (Echo)
+devrel synthesize                theme extraction (Iris)
+devrel experiment HYPOTHESIS     A/B + power analysis (Nova)
+
+# Content
+devrel content draft PROMPT      revision-looped + 5-lever quality (Kai)
+devrel content audit FILE        run quality pipeline on existing draft
+devrel content slop FILE         run only the anti-slop pass
+devrel docs build                AST-based docs (Dex)
+devrel video record SCRIPT       screen-recorded tutorial (Vox)
+
+# Sales
+devrel intel COMPETITOR
+devrel sales outreach COMPANY
+devrel sales battlecard COMPETITOR
+devrel sales sequence CAMPAIGN
+
+# Marketing
+devrel marketing blog TOPIC
+devrel marketing landing TOPIC
+devrel marketing social TOPIC
+devrel marketing campaign BRIEF
+
+# Knowledge base
+devrel kb add URL [--category C]
+devrel kb list
+devrel kb refresh
+
+# Config & schedule
+devrel config get KEY
+devrel config set KEY VALUE
+devrel schedule install | list | remove
+
+# Outputs
+devrel deliverables list
+devrel deliverables show NAME
+
+# Analytics (Argus)
+devrel analytics report [--since 7d] [--push] [--push-on-partial]
+devrel analytics history CONTENT_ID
+devrel analytics diff PERIOD_A PERIOD_B
+devrel analytics calibration
+devrel analytics summary [--root PATH]
+```
+
+Global flags on most verbs: `--json` (machine-readable output) and `--quiet`.
+
+---
+
+## Editorial quality pipeline
+
+Every content-producing run (`devrel content draft`, `devrel content audit`, plus internal calls from `marketing`, `sales`, `kb`-driven tutorials) flows through 8 stages:
+
+```
+1. Generate          KB-grounded; voice.md + style.md in prompt
+2. Developmental     critique+revise (structure, argument, hook)
+3. Line edit         critique+revise (rhythm, voice fidelity)
+4. Copy edit         critique+revise (grammar, code, consistency)
+5. Anti-slop         regex blocklist + LLM lint; force-rewrite on hit;
+                       second failure aborts loud with a phrase report
+6. Reader persona    "skeptical senior backend dev" scores 1-10
+7. Readability       Flesch + sentence variance + jargon density
+                       checked against per-content-type targets
+8. Brand audit       Sentinel (existing 6-dimension audit)
+
+→ deliverables/ + revision-trace.json (every stage's score + diff)
+```
+
+Stages 5-7 use Haiku for cost; stages 2-4 use Sonnet. Total cost ≈ 2.5-4× a single revision loop, with prompt caching pulling toward the lower bound. BudgetGate guardrails (configurable in `.devrel/config.toml`) track spend; `devrel cost --month YYYY-MM` reports it.
+
+---
+
+## How it works internally
+
+Hub-and-spoke with 13 agents. Atlas orchestrates; specialists execute across three pipelines.
+
+```
+Atlas (Orchestrator)
+├── Health: Watchdog (pre-flight) + Sentinel (pre-publish brand audit) + Argus (post-publish performance analyst)
+├── DevRel: Sage, Echo, Iris, Nova, Kai, Vox, Dex
+└── Sales:  Rex, Pax, Mox
+```
+
+The weekly cycle (driven by `devrel run`):
+
+```
+Stage 0: Watchdog         (health + budget check)
+Stage 1: Sage + Echo + Dex     parallel
+Stage 2: Rex + Iris            parallel
+Stage 3: Nova + Kai            parallel (Kai routes through quality pipeline)
+Stage 4: Vox
+Stage 5: Sentinel              brand audit
+Stage 5b: Argus                post-publish content performance analysis
+Stage 6: Instantly sync, OKR compilation, Sheets publish, digest
+```
+
+Argus is config-gated by `[orchestration].analytics_in_run` (default `true`); set to `false` to skip the stage. Standalone use via `devrel analytics report` is unaffected.
+
+The `Atlas.delegate()` API also dispatches single-agent tasks, which is what every non-`run` verb wraps. So `devrel triage` is `Atlas.delegate("sage", "Triage GitHub issues from the last 7 days")` — the agents never appear in the public CLI surface, only the verbs.
+
+---
+
+## Configuration
+
+`.devrel/config.toml` example:
+
+```toml
+[project]
+name = "openclaw"
+url = "https://openclaw.ai"
+github_repo = "openclaw/openclaw"
+
+[model]
+default = "claude-sonnet-4-6"
+cheap = "claude-haiku-4-5-20251001"
+opus_opt_in = true
+
+[budget]
+monthly_usd = 100.0
+warn_at_pct = 80
+```
+
+Edit with `devrel config set <key> <value>` or directly in your editor.
+
+### Environment variables
+
+| Variable | Required | Used by |
+|----------|----------|---------|
+| `ANTHROPIC_API_KEY` | yes | every LLM-using verb |
+| `GITHUB_TOKEN` | for triage | Sage |
+| `FIRECRAWL_API_KEY` | for KB harvest + intel | `kb add`, Echo, Rex |
+| `BRAVE_API_KEY` | optional fallback | search |
+| `INSTANTLY_API_KEY` | for cold-email sync | Pax, Mox |
+| `APOLLO_API_KEY` | for lead enrichment | Rex, Pax |
+| `TELEGRAM_BOT_TOKEN` | for digests | Atlas pipeline |
+| `EMAIL_SENDER` / `EMAIL_PASSWORD` | for digests | Atlas pipeline |
+| `OPENAI_API_KEY` | for video TTS | Vox |
+
+`.env` files at the project root are loaded automatically. Cross-project shared keys can live at `~/.devrel/secrets.env`.
+
+---
+
+## Retargeting to another product
+
+```bash
+cd /path/to/other-project
+devrel init --name otherproduct --url https://otherproduct.dev --github-repo owner/otherproduct
+devrel kb add https://otherproduct.dev/docs --category docs
+# edit voice.md / style.md / slop-blocklist.md to match the other product's voice
+devrel doctor
+devrel run
+```
+
+The agent system is product-agnostic. Per-project config + KB + voice files do all the targeting.
+
+---
+
+## Documentation
+
+The user-facing docs live in [`docs/`](docs/):
+
+- [`docs/quickstart.md`](docs/quickstart.md) — bootstrap a project and run your first weekly cycle in 5 minutes
+- [`docs/agents/argus.md`](docs/agents/argus.md) — content performance analyst, the 13th agent
+- [`docs/cli/analytics.md`](docs/cli/analytics.md) — full reference for the `devrel analytics` subgroup
+- [`docs/cookbook.md`](docs/cookbook.md) — common recipes (calibration, weekly cron, multi-project rollups)
+
+Internal docs (architecture specs, implementation plans) live in [`docs/superpowers/`](docs/superpowers/).
+
+---
+
+## Tech stack
+
+| Component | Choice |
+|---|---|
+| Language | Python 3.12+ |
+| CLI framework | Typer + Rich |
+| Agent SDK | Claude Agent SDK |
+| HTTP | httpx (async) |
+| Default model | Claude Sonnet 4.6 (Haiku for cheap quality stages, Opus opt-in) |
+| Stats | scipy (power analysis, Bayesian eval) |
+| Video | Playwright + FFmpeg + OpenAI TTS |
+| Storage | SQLite per project (.devrel/state.db) |
+| Tests | pytest + pytest-asyncio + respx |
+
+---
+
+## Author
+
+**Daria Dovzhikova** — DevTools Growth Strategist & AI Agent Builder
+- 12+ years in DevTools (JetBrains, Huawei, Lightrun, Odigos)
+- [dariadovzhikova.com](https://dariadovzhikova.com)
+
+---
+
+MIT License

devrel_swarm-0.2.4/README.md

@@ -0,0 +1,255 @@
+# devrel-swarm
+
+**A developer-first CLI for AI-powered DevRel, sales, and marketing.**
+
+`devrel-swarm` is a `pipx`-installable command-line tool that runs a 13-agent system against any project — community triage, social listening, theme extraction, growth experiments, content production, video tutorials, documentation, competitive intel, sales outreach, brand-consistent campaigns, and post-publish content performance analysis. Operates on a project repo the way `git`, `npm`, and `cargo` do.
+
+Every piece of content the system produces flows through an 8-stage editorial pipeline (developmental edit → line edit → copy edit → anti-slop → reader-persona test → readability check → brand audit) so output reads like senior-editor work, not generic AI prose.
+
+> Every deliverable in this repository was produced by the agent system itself.
+
+---
+
+## Quick start
+
+```bash
+pipx install devrel-swarm
+
+cd /path/to/your/project
+devrel init --name myproject --url https://myproject.dev --github-repo me/myproject
+
+# edit .devrel/voice.md, .devrel/style.md, .devrel/slop-blocklist.md
+
+export ANTHROPIC_API_KEY=sk-ant-...
+devrel doctor                                  # check env + scaffold
+devrel content draft "tutorial on feature flags" --type tutorial
+devrel run                                     # full weekly pipeline
+```
+
+After `devrel init`, your repo has a `.devrel/` directory with:
+
+```
+.devrel/
+  config.toml          # product identity, model selection, budget caps
+  voice.md             # tone profile + sample passages    (commit)
+  style.md             # house style + per-content targets (commit)
+  slop-blocklist.md    # banned phrases                    (commit)
+  kb/                  # knowledge base, TF-IDF indexed
+  deliverables/        # generated outputs
+  state.db             # SQLite: jobs, costs, checkpoints
+```
+
+The four committed files (`config.toml`, `voice.md`, `style.md`, `slop-blocklist.md`) encode the editorial contract. Diff them like any other source.
+
+---
+
+## Commands
+
+```
+# Bootstrap & health
+devrel init                      bootstrap .devrel/ in cwd
+devrel doctor [--json]           check env, API keys, KB freshness
+devrel cost [--month YYYY-MM]    token + USD report from state.db
+
+# Pipelines
+devrel run                       full weekly cycle
+devrel run --health              health check only (Watchdog)
+devrel run --agent NAME --task T run a single agent ad-hoc
+
+# DevRel
+devrel triage [--days N]         GitHub issue triage (Sage)
+devrel listen [--platforms ...]  Reddit / HN / X (Echo)
+devrel synthesize                theme extraction (Iris)
+devrel experiment HYPOTHESIS     A/B + power analysis (Nova)
+
+# Content
+devrel content draft PROMPT      revision-looped + 5-lever quality (Kai)
+devrel content audit FILE        run quality pipeline on existing draft
+devrel content slop FILE         run only the anti-slop pass
+devrel docs build                AST-based docs (Dex)
+devrel video record SCRIPT       screen-recorded tutorial (Vox)
+
+# Sales
+devrel intel COMPETITOR
+devrel sales outreach COMPANY
+devrel sales battlecard COMPETITOR
+devrel sales sequence CAMPAIGN
+
+# Marketing
+devrel marketing blog TOPIC
+devrel marketing landing TOPIC
+devrel marketing social TOPIC
+devrel marketing campaign BRIEF
+
+# Knowledge base
+devrel kb add URL [--category C]
+devrel kb list
+devrel kb refresh
+
+# Config & schedule
+devrel config get KEY
+devrel config set KEY VALUE
+devrel schedule install | list | remove
+
+# Outputs
+devrel deliverables list
+devrel deliverables show NAME
+
+# Analytics (Argus)
+devrel analytics report [--since 7d] [--push] [--push-on-partial]
+devrel analytics history CONTENT_ID
+devrel analytics diff PERIOD_A PERIOD_B
+devrel analytics calibration
+devrel analytics summary [--root PATH]
+```
+
+Global flags on most verbs: `--json` (machine-readable output) and `--quiet`.
+
+---
+
+## Editorial quality pipeline
+
+Every content-producing run (`devrel content draft`, `devrel content audit`, plus internal calls from `marketing`, `sales`, `kb`-driven tutorials) flows through 8 stages:
+
+```
+1. Generate          KB-grounded; voice.md + style.md in prompt
+2. Developmental     critique+revise (structure, argument, hook)
+3. Line edit         critique+revise (rhythm, voice fidelity)
+4. Copy edit         critique+revise (grammar, code, consistency)
+5. Anti-slop         regex blocklist + LLM lint; force-rewrite on hit;
+                       second failure aborts loud with a phrase report
+6. Reader persona    "skeptical senior backend dev" scores 1-10
+7. Readability       Flesch + sentence variance + jargon density
+                       checked against per-content-type targets
+8. Brand audit       Sentinel (existing 6-dimension audit)
+
+→ deliverables/ + revision-trace.json (every stage's score + diff)
+```
+
+Stages 5-7 use Haiku for cost; stages 2-4 use Sonnet. Total cost ≈ 2.5-4× a single revision loop, with prompt caching pulling toward the lower bound. BudgetGate guardrails (configurable in `.devrel/config.toml`) track spend; `devrel cost --month YYYY-MM` reports it.
+
+---
+
+## How it works internally
+
+Hub-and-spoke with 13 agents. Atlas orchestrates; specialists execute across three pipelines.
+
+```
+Atlas (Orchestrator)
+├── Health: Watchdog (pre-flight) + Sentinel (pre-publish brand audit) + Argus (post-publish performance analyst)
+├── DevRel: Sage, Echo, Iris, Nova, Kai, Vox, Dex
+└── Sales:  Rex, Pax, Mox
+```
+
+The weekly cycle (driven by `devrel run`):
+
+```
+Stage 0: Watchdog         (health + budget check)
+Stage 1: Sage + Echo + Dex     parallel
+Stage 2: Rex + Iris            parallel
+Stage 3: Nova + Kai            parallel (Kai routes through quality pipeline)
+Stage 4: Vox
+Stage 5: Sentinel              brand audit
+Stage 5b: Argus                post-publish content performance analysis
+Stage 6: Instantly sync, OKR compilation, Sheets publish, digest
+```
+
+Argus is config-gated by `[orchestration].analytics_in_run` (default `true`); set to `false` to skip the stage. Standalone use via `devrel analytics report` is unaffected.
+
+The `Atlas.delegate()` API also dispatches single-agent tasks, which is what every non-`run` verb wraps. So `devrel triage` is `Atlas.delegate("sage", "Triage GitHub issues from the last 7 days")` — the agents never appear in the public CLI surface, only the verbs.
+
+---
+
+## Configuration
+
+`.devrel/config.toml` example:
+
+```toml
+[project]
+name = "openclaw"
+url = "https://openclaw.ai"
+github_repo = "openclaw/openclaw"
+
+[model]
+default = "claude-sonnet-4-6"
+cheap = "claude-haiku-4-5-20251001"
+opus_opt_in = true
+
+[budget]
+monthly_usd = 100.0
+warn_at_pct = 80
+```
+
+Edit with `devrel config set <key> <value>` or directly in your editor.
+
+### Environment variables
+
+| Variable | Required | Used by |
+|----------|----------|---------|
+| `ANTHROPIC_API_KEY` | yes | every LLM-using verb |
+| `GITHUB_TOKEN` | for triage | Sage |
+| `FIRECRAWL_API_KEY` | for KB harvest + intel | `kb add`, Echo, Rex |
+| `BRAVE_API_KEY` | optional fallback | search |
+| `INSTANTLY_API_KEY` | for cold-email sync | Pax, Mox |
+| `APOLLO_API_KEY` | for lead enrichment | Rex, Pax |
+| `TELEGRAM_BOT_TOKEN` | for digests | Atlas pipeline |
+| `EMAIL_SENDER` / `EMAIL_PASSWORD` | for digests | Atlas pipeline |
+| `OPENAI_API_KEY` | for video TTS | Vox |
+
+`.env` files at the project root are loaded automatically. Cross-project shared keys can live at `~/.devrel/secrets.env`.
+
+---
+
+## Retargeting to another product
+
+```bash
+cd /path/to/other-project
+devrel init --name otherproduct --url https://otherproduct.dev --github-repo owner/otherproduct
+devrel kb add https://otherproduct.dev/docs --category docs
+# edit voice.md / style.md / slop-blocklist.md to match the other product's voice
+devrel doctor
+devrel run
+```
+
+The agent system is product-agnostic. Per-project config + KB + voice files do all the targeting.
+
+---
+
+## Documentation
+
+The user-facing docs live in [`docs/`](docs/):
+
+- [`docs/quickstart.md`](docs/quickstart.md) — bootstrap a project and run your first weekly cycle in 5 minutes
+- [`docs/agents/argus.md`](docs/agents/argus.md) — content performance analyst, the 13th agent
+- [`docs/cli/analytics.md`](docs/cli/analytics.md) — full reference for the `devrel analytics` subgroup
+- [`docs/cookbook.md`](docs/cookbook.md) — common recipes (calibration, weekly cron, multi-project rollups)
+
+Internal docs (architecture specs, implementation plans) live in [`docs/superpowers/`](docs/superpowers/).
+
+---
+
+## Tech stack
+
+| Component | Choice |
+|---|---|
+| Language | Python 3.12+ |
+| CLI framework | Typer + Rich |
+| Agent SDK | Claude Agent SDK |
+| HTTP | httpx (async) |
+| Default model | Claude Sonnet 4.6 (Haiku for cheap quality stages, Opus opt-in) |
+| Stats | scipy (power analysis, Bayesian eval) |
+| Video | Playwright + FFmpeg + OpenAI TTS |
+| Storage | SQLite per project (.devrel/state.db) |
+| Tests | pytest + pytest-asyncio + respx |
+
+---
+
+## Author
+
+**Daria Dovzhikova** — DevTools Growth Strategist & AI Agent Builder
+- 12+ years in DevTools (JetBrains, Huawei, Lightrun, Odigos)
+- [dariadovzhikova.com](https://dariadovzhikova.com)
+
+---
+
+MIT License