Samsarix Agent Swarm

Samsarix Agent Swarm is a small Python harness for testing and contract-checking multi-agent workflow behavior without committing to a model vendor or production agent platform. It runs application-supplied async responders in a deterministic round-robin collective with hard limits, explicit completion, structured failures, portable JSON transcripts, and offline structural verification.

Maintained by Samsarix LLC. General and licensing inquiries: contact@samsarix.com. Product support and private security reports: support@samsarix.com.

It is for Python developers who need to prototype or regression-test the coordination layer around agents: who speaks next, when a run stops, what happens on timeout, and what record is left behind. The bundled demo is a transparent simulator—not an LLM—and requires no API key.

Status: 0.1.0 alpha. The core local workflow is implemented and tested; bundled provider clients, durable resume, parallel execution, and tool execution are deliberately out of scope for 0.1.x.

Fastest successful path

Prerequisite: Python 3.11 through 3.14.

git clone https://github.com/Deathcharge/samsarix-agent-swarm.git
cd samsarix-agent-swarm
python -m venv .venv

Activate the environment:

# macOS/Linux
source .venv/bin/activate

# Windows PowerShell
.venv\Scripts\Activate.ps1

Install this checkout and run the credential-free simulation:

python -m pip install -e .
samsarix-swarm run "Design a safe retry policy" --state-out run.json
samsarix-swarm show run.json
samsarix-swarm verify run.json examples/demo-review.contract.json
samsarix-swarm verify-suite examples/demo-review.suite.json

The command runs three deterministic roles—Analyst, Critic, and Synthesizer—and exits successfully only when a responder explicitly signals completion. run.json contains the schema-versioned transcript. Existing files are never overwritten unless --force is supplied. The verify command then checks that record against a committed structural contract without calling a model.

For machine-readable output:

samsarix-swarm run "Review a release checklist" --format json

See every limit and exit behavior with:

samsarix-swarm --help
samsarix-swarm run --help
samsarix-swarm verify --help
samsarix-swarm verify-suite --help

CI contract gates

RunContract captures provider-neutral orchestration expectations: collective identity, terminal status, turn bounds, exact agent order, absence of recorded errors, and required final metadata. The CLI returns 0 for a passing contract, 4 for a valid run that violates its contract, and 2 for invalid input.

samsarix-swarm verify run.json examples/demo-review.contract.json --format json

Contracts inspect structure, not prose. They do not claim that the response is truthful, safe, helpful, or semantically correct. See real use cases and competitive positioning.

For regression datasets, a versioned suite manifest groups up to 100 named run-record and contract pairs. Verification continues after individual artifact errors and can emit text, JSON, or JUnit XML:

samsarix-swarm verify-suite examples/demo-review.suite.json --format junit

See the scenario-suite guide for the manifest schema, path-containment rules, CI example, and dataset practices.

The adapter cookbook includes an independently validated Samsarix Orchestration consumer, redacted run evidence, and a contract that catches participant-role drift without adding a framework dependency.

Use your own responder

The orchestration layer is provider-neutral. A responder receives an AgentRequest and returns either an AgentReply or a string:

import asyncio

from samsarix_agent_swarm import (
    AgentReply,
    AgentRequest,
    SamsarixCollective,
    SamsarixAgent,
)


async def responder(request: AgentRequest) -> AgentReply:
    # Call your model SDK, local model, fixture, or rules engine here.
    return AgentReply(
        content=f"Validated: {request.task}",
        complete=True,
        metadata={"provider": "my-adapter"},
    )


async def main() -> None:
    agent = SamsarixAgent("Reviewer", "check release evidence", responder)
    collective = SamsarixCollective(
        [agent],
        max_rounds=1,
        response_timeout=15,
        max_retries=0,
    )
    result = await collective.run("Verify the wheel imports from a clean environment")
    print(result.to_json())


asyncio.run(main())

A complete runnable version lives at examples/custom_responder.py.

Failure and cancellation behavior

• Tasks are non-empty and bounded to 100,000 characters by default.
• Context must be JSON-compatible and has a configurable top-level item cap.
• Agent replies, rounds, timeouts, and retries are bounded.
• Retries default to zero to prevent accidental provider cost amplification.
• An exhausted timeout or responder failure produces RunStatus.FAILED with an error transcript entry.
• Reaching the round limit produces RunStatus.MAX_ROUNDS; it is never reported as task completion.
• asyncio cancellation propagates to the caller instead of being converted into success or retry.
• A collective serializes concurrent calls through a run lock so its mutable agent state is not interleaved.

Public API

The deliberate 0.1.x surface is:

• SamsarixAgent: a named role with a bounded local transcript and injected async responder;
• SamsarixCollective: bounded deterministic execution;
• SamsarixOrchestrator: explicit registration and routing across named collectives;
• AgentRequest / AgentReply: the provider-adapter contract;
• Message, RunResult, and RunStatus: immutable run records;
• RunContract, ContractResult, and ContractViolation: portable structural assertions;
• verify_run_result / load_run_contract: programmatic contract verification;
• SuiteManifest, SuiteScenario, and SuiteResult: portable regression datasets;
• verify_suite / load_suite_manifest: bounded aggregate verification and JUnit reporting;
• load_run_result: bounded JSON transcript loading.

The historical helix_agent_swarm import, helix-swarm command, HelixConsciousAgent, HelixCollective, HelixOrchestrator, and earlier module paths remain compatibility aliases during 0.1.x; they all delegate to the Samsarix implementation. See docs/MIGRATION.md. The copied SaaS routes, flagship registry imports, fabricated consensus scorer, and hidden Redis/database integrations were removed because they were not runnable in this repository.

Development

Install the pinned development toolchain:

python -m pip install -r requirements-dev.lock
python -m pip install -e .

Run the same meaningful checks as CI:

python -m ruff format --check .
python -m ruff check .
python -m mypy
python -m pytest --cov=src/samsarix_agent_swarm --cov=src/helix_agent_swarm --cov-report=term-missing
python -m build
python -m twine check dist/*

The runtime package has no third-party dependencies. requirements-dev.lock pins the top-level contributor/CI tools; their transitive packages remain constrained by those tools. The project uses a standard src/ layout so tests and local imports cannot accidentally succeed against an unshipped source directory.

Architecture

application/model fixture
        │ AgentRequest → AgentReply
        ▼
SamsarixAgent (bounded local state)
        ▼
SamsarixCollective (rounds, timeout, retry, completion)
        ▼
RunResult ──► stdout / atomic JSON transcript
        │
        └────► RunContract ──► pass / stable violations / CI exit code
                    ▲
SuiteManifest ──────┴────────► aggregate text / JSON / JUnit
        ▲
SamsarixOrchestrator (optional named routing)

The library does not execute tools, evaluate model output, open network connections, read API keys, persist hidden state, or create background workers. Those responsibilities stay with the embedding application.

Security, privacy, and cost

Samsarix Agent Swarm has no telemetry and no built-in provider client. Prompts, context, and replies stay in process unless the caller's responder sends them elsewhere or the caller explicitly writes a run record. JSON records may contain the complete task and replies; treat them as potentially sensitive.

The library validates record, contract, and suite structure plus JSON-compatible metadata, bounds file reads and nested metadata depth, contains suite paths, limits rounds/retries/timeouts, and uses atomic non-overwriting transcript writes. It is not a sandbox: an application must treat model output as untrusted data and must enforce authorization, redaction, provider budgets, and tool permissions at its own boundaries.

See SECURITY.md for the trust model and reporting guidance.

Limitations and non-goals

• The demo produces templates, not intelligent answers.
• Execution is sequential round-robin only.
• Run records are inspectable transcripts, not resumable checkpoints.
• Contracts validate workflow structure, not semantic answer quality.
• There are no bundled model-provider, database, web API, tool, or cloud integrations.
• The package does not claim that multiple agreeing strings establish truth or quality.
• Demand and product-market fit have not been validated.

These constraints keep the package independently useful as a small harness rather than an incomplete competitor to full agent frameworks.

Distribution and releases

python -m build produces a source distribution and universal wheel. python -m twine check dist/* validates the publication metadata. A samsarix-vX.Y.Z tag runs the pinned release workflow, repeats the source and installation gates, generates SHA-256 checksums and cryptographically signed GitHub artifact attestations, then attaches the artifacts to a GitHub release. Verify a downloaded artifact with gh attestation verify <artifact> --repo Deathcharge/samsarix-agent-swarm.

The repository's historical v1.0.0 tag belongs to the superseded Helix extraction and is preserved for auditability. Supported Samsarix releases use the samsarix-vX.Y.Z namespace. PyPI publication remains separate until a Samsarix trusted publisher is configured.

Changes are tracked in CHANGELOG.md. Product decisions, baseline evidence, and release gates live in docs/PRODUCTIZATION.md. The current product thesis and implementation priorities are recorded in docs/COMPETITIVE_POSITIONING.md and ROADMAP.md.

Contributing

See CONTRIBUTING.md. Changes to completion semantics, state schema, retry defaults, or the public API require tests and a changelog entry.

Citation and support

Citation metadata is provided in CITATION.cff. Best-effort community and private support channels are documented in SUPPORT.md.

License

Copyright 2026 Samsarix LLC and contributors. The current source tree is licensed under the unmodified Mozilla Public License 2.0. MPL-2.0 keeps distributed modifications to covered source files available under the MPL while allowing the library to be combined with applications under other licenses.

Copyright and contact details are recorded in NOTICE, the practical model and historical-license boundary are explained in LICENSING.md, and the source license does not grant rights to Samsarix names or logos; see TRADEMARKS.md.