campaigns-os 0.1.1

Campaign primitives for autonomous organizations powered by AgentRL pods.

Campaigns

Campaigns is an open-source campaign operating-system layer above AgentRL.

AgentRL answers:

How do we improve, evaluate, evolve, version, and deploy an agent harness?

Campaigns answers:

How do we continuously execute a user's goal through an evolving autonomous organization?

The user does not micromanage every task. The user defines goals, reviews harnesses and approval gates, monitors traces when desired, and receives an ultimate final review packet across the fleet and contract agents.

Dynamic workflow

1. User creates a targeted AgentRL harness
   Example: Market Researcher with RAG, trace, decision-log, evaluation, memory, and approval-gate components.

2. User defines a campaign
   Example: run a marketing campaign using the Market Researcher and RAG Analyst harnesses.

3. Campaigns employs those harnesses as fleet agents
   Each employed agent has a mandate, decision rights, review obligations, and an AgentRL pod declaration.

4. Fleet agents plan and execute bounded work
   The Market Researcher runs RAG-grounded research. The Campaign Manager creates approval gates and operating cadence.

5. Fleet agents contract short-term specialist workers in parallel
   Example contracts: SEO Optimizer, Outreach Worker, Creative Worker, Analytics Worker.

6. Contract agents return deliverables, traces, costs, and evidence
   Employed agents remain accountable for synthesis and decisions.

7. Campaigns synthesizes a final report
   The user receives one final review packet across all fleet and contract agents instead of being forced to micromanage.

8. User monitors traces and performance reviews when desired
   Trace monitors expose decision quality, constraint compliance, contract outcomes, evidence quality, and cost/timeline drift.

9. User performs ultimate review
   Approve, revise, stop, or launch the next iteration.

10. AgentRL consumes traces and review outcomes
    Harnesses can evolve, be versioned, promoted, deployed, or rolled back.

Campaign primitive

campaign:
  objective: Increase recurring revenue by 30% for a local detailing business
  budget:
    dollars: 5000
  timeline:
    days: 90
  metrics:
    - recurring_revenue
    - conversion_rate
  constraints:
    - human approval for spend > $500
  employed_harnesses:
    - agent_name: Market Researcher
      role: market_researcher
      objective: Research demand, competitors, segments, and campaign risks
      components: [rag, trace, decision_log, evaluation]
    - agent_name: RAG Analyst
      role: rag_analyst
      objective: Retrieve and synthesize evidence for claims and assumptions
      components: [rag, trace, evaluation]

A campaign turns a user goal into an accountable operating structure:

Campaign
  -> Workflow DAG
  -> Organization
  -> Team
  -> Employed Fleet Agent
  -> AgentRL Pod Instantiation
  -> Runtime / Harness
       -> Contracted Agents for short-term parallel work
  -> Trace Monitor
  -> Performance Reviews
  -> Ultimate User Review
  -> AgentRL Evolution / Promotion / Rollback

Install

From PyPI after release:

pip install campaigns-os

From source:

python -m venv .venv
source .venv/bin/activate
pip install -e .[dev]

Run from GitHub Container Registry after package publication:

docker pull ghcr.io/junaidahmed361/campaigns:latest
docker run --rm ghcr.io/junaidahmed361/campaigns:latest --version

Quick start

Create a review dossier from an example campaign:

campaigns compile examples/revenue-growth.yaml

Or from Python:

from campaigns import CampaignSpec, CampaignCompiler

spec = CampaignSpec.from_dict({
    "objective": "Increase recurring revenue",
    "metrics": ["revenue", "conversions"],
    "employed_harnesses": [{
        "agent_name": "Market Researcher",
        "role": "market_researcher",
        "objective": "Research the market with RAG-grounded evidence",
        "components": ["rag", "trace", "decision_log", "evaluation"],
    }],
})

dossier = CampaignCompiler().compile(spec)
print(dossier.to_dict()["workflow"])

Current primitives

• AgentHarnessDefinition: campaign-side reference to a user-created targeted AgentRL harness.
• CampaignSpec: user-defined goal, budget, timeline, success metrics, constraints, and employed harnesses.
• AgentRLPodInstantiation: portable declaration of an AgentRL pod used by an employed or contract agent.
• EmployedAgent: accountable fleet participant with role, mandate, decision rights, contracts, and review obligations.
• Contract: outsourced short-term specialist work with success criteria, trace requirements, and a contracted pod.
• WorkflowStep: DAG step for harness creation, campaign definition, fleet employment, contract work, synthesis, performance review, ultimate review, and AgentRL evolution.
• TraceMonitor: user-monitorable trace surface for fleet performance reviews.
• PerformanceReview: scorecard scaffold for reviewing employed agents without micromanagement.
• ReviewDossier: final artifact the user reviews before approving execution, accepting outcomes, or triggering another iteration.
• CampaignAutorun: simple fit / transform / score / autorun primitive for bounded observe-plan-act-verify-review loops.
• AutorunPolicy, GoalCheck, and CampaignIteration: /goal-style loop limits, stop conditions, second-model goal checks, independent final auditor hints, budget pause/resume state, and iteration records.
• RetrospectiveFeedback: continual-learning feedback that routes reinforcement to either Campaigns-owned next-iteration strategy or AgentRL-owned agent harness lifecycle updates.
• CampaignAutorun.final_review(...): after the user gives final review, a retro agent traverses trace surfaces across all employed agents, attributes root cause, and plans AgentRL self-reinforcement for the relevant harness.

SDK retro example:

from campaigns import CampaignAutorun

runner = CampaignAutorun().fit(campaign)
runner.autorun(max_loops=1)
retro = runner.retro({
    "summary": "The Market Researcher missed competitor pricing evidence.",
    "attention_level": "agentrl",
    "target": "Market Researcher",
    "reinforce": "Require competitor price citations before recommendations.",
})

Boundary

Campaigns does not implement agent runtimes, model training, harness evaluation, harness evolution, or deployment. It records which AgentRL pod should own those lifecycle responsibilities and how the campaign organization composes them. AgentRL does not implement campaign autorun, campaign organizations, contracted-worker queues, performance-review dashboards, or marketing/business workflow policy; those belong in Campaigns.

Claude-style loop autorun

Campaigns includes a simple scikit-learn-style autorun primitive for dynamic campaign workflows:

from campaigns import CampaignAutorun

runner = CampaignAutorun().fit(spec)
dossier = runner.transform()
readiness = runner.score()
result = runner.autorun(max_loops=3)

The autorun loop is intentionally an operating plan, not an agent runtime:

observe -> plan -> act -> verify -> review -> repeat until approval/stop/limit

It can select workflow steps dynamically across loops, preserve trace/review surfaces, and stop at ultimate user review. Runtime execution is delegated to agent systems; harness lifecycle feedback is handed to AgentRL.

CLI:

campaigns autorun examples/revenue-growth.yaml --loops 3

Sister commercial app

The private sister repo is campaigns-app. It provides the commercial interface around the open-source core: hosted UI, billing, user workspaces, approvals, trace/performance dashboards, and integrations.