Mini-Assistant-Swarm

A small, fork-friendly toolkit of personal AI subagents that lift daily operational load without ever posting, sending, publishing, or committing on the operator's behalf. Every consequential output passes through a truthfulness verifier before it reaches the operator, and every meaningful artefact is written to disk for later audit.

This is the public scaffold. The shared VERIFIER module is fully implemented with passing tests. The seven v1 subagents (SCOUT, SCRIBE, TRACKER, COMPASS, MAP, PROSPECT, TALKS) ship as empty folders so a fork can build them out to fit the operator's specific life and constraints.

What it is, in one paragraph

A personal subagent swarm. You run it locally. It does daily signal sweeps, draft posts, pipeline tracking, weekly focus reviews, competitive intelligence, qualified-lead surfacing, and CFP digests, all gated by a verifier that fails closed on unreachable sources or unverifiable claims. The toolkit proposes via Telegram and never sends; you approve via Telegram. Every artefact lands on disk under a configurable root.

Who it is for

• Solo founders, indie consultants, and one-person research programmes that need to maintain a daily and weekly rhythm without becoming the rhythm.
• Operators who refuse to let an AI assistant post on their behalf but want the structured drafts and the surfaced signals.
• Anyone building governance-first AI tooling for their own life as a credibility-by-dogfooding exercise.

What is in the box

Mini-Assistant-Swarm/
  shared/
    verify.py            VERIFIER, the truthfulness gate. Five capabilities.
                         SQLite-backed 24h cache. Fail-closed posture.
    __init__.py
  agents/                Seven v1 subagents as empty scaffolds, ready to fork.
    scout/               Daily signal sweep.
    scribe/              Draft post writer triggered on demand.
    tracker/             Pipeline state + Friday weekly report.
    compass/             Weekly focus review (Sunday).
    map/                 Monday competitive-intelligence diff.
    prospect/            Daily qualified-lead surfacer.
    talks/               Tuesday CFP digest.
  tests/
    test_verifier.py     Five-test self-test exercising each VERIFIER capability.
  config/                Templates (.template.md). Copy and customise locally.
    voice.template.md
    positioning.template.md
    prior-art.template.md
    ai-act.template.md
    prospect-targets.template.md
    talks-conferences.template.md
  .env.example           Environment template.
  requirements.txt       Python dependencies, pinned.
  install.md             One-time setup walkthrough.
  README.md
  LICENSE                Apache 2.0.

The VERIFIER is implemented and its five tests pass against real network (Wikipedia REST plus a known-good arXiv page). The seven agent folders are intentionally empty so a fork can fill them in against its own operator's actual context and constraints.

VERIFIER, the only non-negotiable

shared/verify.py is the truthfulness gate. No factual claim leaves any subagent without passing through it. The five capabilities:

• verify_url(url) checks HTTP reachability and pulls the page title for evidence.
• verify_claim_against_source(claim, url) fetches the source URL and runs a keyword-coverage check (v1 is coarse; the API surface is in place for an LLM-verify upgrade later).
• verify_citation(author, year, title=None) confirms the author was alive at the cited publication year, via Wikipedia's structured death-year lookup.
• verify_author_alive_in_year(name, year) is the underlying primitive.
• verify_person_role(name, role) is a coarse Wikipedia-extract scan; verifies the role terms appear on the person's summary.

Every call hits a SQLite cache for 24 hours by content hash. Every call writes to a verifier_log table for auditability. Every call fails closed: unreachable sources, parse failures, and unknown persons all return unknown, which counts as failed for letting claims through.

Five tests run against real network and must all pass before any subagent is built on top:

py -m unittest tests.test_verifier -v

Expected output: Ran 5 tests in ~1s. OK.

How to fork and provision for your own use

1. Fork this repo on GitHub to your own account or org.

2. Clone your fork.

   git clone https://github.com/YOUR-HANDLE/Mini-Assistant-Swarm.git
   cd Mini-Assistant-Swarm

3. Install Python dependencies. Python 3.10 or newer.

   py -m pip install -r requirements.txt

4. Run the VERIFIER self-test. This confirms the network path, the SQLite cache, and the five capabilities all work in your environment.

   py -m unittest tests.test_verifier -v

   All five must pass before you build any agent on top.

5. Copy the environment template and customise.

   cp .env.example .env
   # edit .env, set DAILY_PLANNER_ROOT to a folder you own

6. Customise the config templates under config/. Copy each *.template.md to *.md and fill in your own:

   • voice.md - your voice rules. What you sound like; what you avoid.
   • positioning.md - what you are building, who it is for, your defining angle.
   • prior-art.md - competitors and adjacent work you want surfaced.
   • ai-act.md (or whichever regulation applies to your domain).
   • prospect-targets.md - the shape of a qualified lead in your world.
   • talks-conferences.md - venues you would consider speaking at.

   The .md files are gitignored by default so your fork can hold your private content without leaking it back into the public repo.

7. Hook up the Telegram bot (or your preferred human-interface channel). Set the credentials in .env. The toolkit listens, proposes, and waits for approval; it never sends on your behalf.

8. Build the agents. The seven agent folders are intentionally empty. The build spec for each agent (cadence, inputs, outputs, what counts as a Decision Receipt) lives in the issues on this repo. Pick the ones that fit your operating model; you do not need all seven.

9. Wire the orchestrator to your local scheduler. On Windows this is Task Scheduler; on macOS launchd; on Linux cron or systemd-timers.

Architectural posture

• Never posts, sends, publishes, reaches out, connects, or commits. Every consequential action is proposed and waits for human approval through the configured interface (Telegram in the reference design, but the interface is pluggable).
• Every factual claim passes through VERIFIER. Unreachable source means unverified means refused. The toolkit fails closed.
• Every meaningful output is written to disk under DAILY_PLANNER_ROOT so the operator has a durable artefact for every decision the swarm contributed to.
• State lives in a single SQLite database at the project root. One file, easy to back up, easy to inspect.
• No agent shares state across operators. This is single-tenant by design. Multi-tenant deployments are an upstream concern.

Acknowledgements

Built and open-sourced by Aperintel as part of the broader governance-first AI infrastructure thesis. Aperintel runs a private fork of this scaffold for its own daily operations as a dogfooding exercise; the open scaffold here is brand-neutral and intentionally portable to any operator with their own life to coordinate.

Licence

Apache 2.0. See LICENSE.