# SMF Swarm: Inside the Predictive Agent Swarm Pipeline
SMF Swarm is the open-source engine behind every forecast SMF Works publishes. It is a hybrid prediction pipeline that fuses LangGraph's deterministic state management with CrewAI's role-based agent orchestration, then layers a social-swarm validation stage on top to surface hidden assumptions and force calibration before any confidence number is returned.
If you have ever wanted to run a team of specialist AI agents that research, model, argue, and then agree on a probability—SMF Swarm is that system, packaged as a CLI tool and a self-contained web UI.
What It Is
At its core, SMF Swarm is a prediction pipeline, not a chatbot. You ask a question about a future event—"Will NVIDIA market cap exceed $4 trillion by July 2026?"—and the pipeline executes a fixed graph of research, feature engineering, modeling, validation, and reporting nodes. Each node is staffed by one or more agents with specific roles (Researcher, Feature Engineer, Modeler, Validator, Reporter). The agents can use tools (search, calculation, simulation) and their outputs are passed through structured JSON schemas so downstream systems can act on them without guessing.
The pipeline runs in three modes:
- Standard Mode — Fast single-model prediction. Best for operational questions where you need an answer in seconds. - Debate Mode — Adversarial ensemble. An Optimist, a Skeptic, and an Analyst produce opening arguments and rebuttals, then a Judge synthesizes the median view. Best for controversial or high-stakes questions. - Full + Social — Standard pipeline + Debate merge → social swarm calibration. A secondary swarm reviews the draft prediction for groupthink, availability bias, and overconfidence. Best for publishable forecasts and capital allocation decisions.
Capabilities
The current release ships with the following:
| Capability | What It Does | |------------|--------------| | Any LLM Backend | Ollama, OpenAI, Anthropic, Groq, Together, or any OpenAI-compatible API. Swap models in one command. | | Hardware-Aware Scaling | Auto-detects RAM and VRAM on first run, then recommends a swarm profile (Compact, Balanced, Performance, Enthusiast) sized for your machine. Runs on 8 GB laptops. | | Web UI | Standalone Flask + vanilla JS interface at `localhost:8080`. No external CSS frameworks, no CDN dependencies. Works offline. | | Structured Output | Every prediction returns JSON with `confidence`, `summary`, `risk_assessment`, `data_quality`, and `timeline`. | | Health Monitoring | Per-node tracking: duration, error count, success rate, social modifier. | | Report Export | One-click Markdown download of any completed forecast from the Web UI. | | PDF / TXT / MD Upload | Drag-and-drop source documents into the Web UI to inject context into the pipeline. |
The Development Cycle
SMF Swarm is built iteratively, with each release validated against real prediction-market data and synthetic stress tests before it is tagged.
Architecture. The pipeline is a directed graph of stateful nodes. Nodes are pure functions that receive a shared state object, execute an agent crew, and return an updated state. LangGraph handles the graph topology and checkpointing; CrewAI handles the agent-role definitions and tool delegation. This separation keeps the execution deterministic while allowing flexible agent behavior inside each node.
Social Swarm Layer. After the primary pipeline produces a draft prediction, the social swarm kicks in. This is a secondary crew of agents that do not see the source data directly. They review the draft for logical consistency, look for missing alternative hypotheses, and adjust the confidence score based on detected bias patterns. The social modifier (e.g., -0.15) is the quantitative output of this review.
Release Process. We follow semantic versioning, test against frozen benchmark suites, and publish changelogs with migration notes. The install script is a single `curl | bash` that detects your OS, creates a virtual environment, and runs a configuration wizard. No manual dependency hunting.
Open Source, Open to Everyone
SMF Swarm is released under the MIT license. The full source code, documentation, and issue tracker are on GitHub.
Repository: [github.com/smfworks/smf-swarm](https://github.com/smfworks/smf-swarm)
You can clone it, fork it, run it commercially, or embed it in your own product. We welcome pull requests, bug reports, and feature requests. There is no enterprise gate, no API key required for the core engine, and no telemetry that phones home.
If you need a managed, conversational interface on top of SMF Swarm, see [SMF Predict](https://smfworks.com/predict)—our commercial product that wraps the pipeline in a pre-configured Hermes agent experience.
Target Audience
SMF Swarm is a developer and engineer tool. You interact with it via the command line or Python API. If you are comfortable with `pip install`, environment variables, and reading JSON output, you are the target user.
Specific profiles that get the most value:
- Quantitative analysts and traders building custom prediction models for financial or political markets. - AI researchers studying multi-agent consensus, adversarial reasoning, or swarm calibration. - Data engineers who need structured, reproducible forecasting pipelines they can automate via cron or CI/CD. - Enterprise risk teams that want to surface hidden assumptions in strategic forecasts before committing capital. - Solo developers on modest hardware who still want rigorous agent-based prediction without cloud GPU bills.
Use Cases
Here is how users are deploying SMF Swarm today:
- Financial forecasting. Predicting earnings surprises, sector rotations, and macro regime shifts with debate-mode ensembles. - Political prediction. Forecasting election outcomes, policy passage probabilities, and regulatory risk. - Technology trend analysis. Estimating adoption curves for emerging tech (AI agents, spatial computing, quantum) with multi-year timelines. - Enterprise risk assessment. Running "pre-mortem" predictions on project deadlines, supply-chain disruptions, and competitive threats. - Academic research. Generating calibrated probabilistic forecasts as inputs for structured expert judgment studies.
Get Started
One-line install:
```bash curl -fsSL https://raw.githubusercontent.com/smfworks/smf-swarm/main/install.sh | bash ```
Then configure and predict:
```bash smf-swarm configure smf-swarm predict "Will AI agent adoption in enterprise exceed 60% by end 2026?" --mode full --domain technology ```
Or launch the Web UI:
```bash smf-swarm web ```
The documentation covers setup, architecture, the full CLI reference, and the Python API.
What’s Next
The roadmap includes streaming prediction updates (live SSE as each node completes), extended model support for local multimodal backends, and a plugin system for custom nodes. If you want to shape the direction, open an issue or submit a PR.
SMF Swarm is not a toy. It is an industrial-grade prediction engine, built by a team that believes the future should be modeled, not guessed.
— Liam Hermes Chief Data Officer, SMF Works