caucus 0.2.1__tar.gz → 0.2.2__tar.gz

caucus-0.2.2/.github/workflows/evidence-snapshot.yml

@@ -0,0 +1,73 @@
+name: Evidence snapshot
+
+# GitHub's traffic API retains only 14 days of views/clones — this weekly
+# snapshot preserves adoption history (stars, forks, traffic, referrers, PyPI
+# downloads) as append-only JSONL on the 'evidence' branch.
+
+on:
+  schedule:
+    - cron: "0 8 * * 1"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  snapshot:
+    name: Capture adoption metrics
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Checkout evidence branch (create if absent)
+        uses: actions/checkout@v5
+        with:
+          ref: main
+          fetch-depth: 1
+
+      - name: Switch to evidence branch
+        shell: bash
+        run: |
+          if git fetch origin evidence:evidence 2>/dev/null; then
+            git checkout evidence
+          else
+            git checkout --orphan evidence
+            git rm -rfq . 2>/dev/null || true
+          fi
+
+      - name: Capture snapshot
+        shell: bash
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          repo="$GITHUB_REPOSITORY"
+          date=$(date -u +%Y-%m-%d)
+          repo_json=$(gh api "repos/$repo")
+          views=$(gh api "repos/$repo/traffic/views" 2>/dev/null || echo '{}')
+          clones=$(gh api "repos/$repo/traffic/clones" 2>/dev/null || echo '{}')
+          referrers=$(gh api "repos/$repo/traffic/popular/referrers" 2>/dev/null || echo '[]')
+          pypi=$(curl -fsS "https://pypistats.org/api/packages/caucus/recent" 2>/dev/null || echo '{}')
+          jq -cn \
+            --arg date "$date" \
+            --argjson repo "$repo_json" \
+            --argjson views "$views" \
+            --argjson clones "$clones" \
+            --argjson referrers "$referrers" \
+            --argjson pypi "$pypi" \
+            '{date: $date,
+              stars: $repo.stargazers_count,
+              forks: $repo.forks_count,
+              open_issues: $repo.open_issues_count,
+              views: {count: $views.count, uniques: $views.uniques},
+              clones: {count: $clones.count, uniques: $clones.uniques},
+              referrers: $referrers,
+              pypi_recent: $pypi.data}' >> adoption.jsonl
+          tail -1 adoption.jsonl
+
+      - name: Commit snapshot
+        shell: bash
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add adoption.jsonl
+          git commit -m "Evidence snapshot $(date -u +%Y-%m-%d)"
+          git push origin evidence

{caucus-0.2.1 → caucus-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: caucus
-Version: 0.2.1
+Version: 0.2.2
 Summary: Your AI agents, deliberating on the record. MCP-grounded multi-agent consensus with recorded dissent and an auditable decision log.
 Project-URL: Repository, https://github.com/srinath-jukanti/caucus
 Author: Srinath Jukanti

{caucus-0.2.1 → caucus-0.2.2}/examples/trading-robinhood/README.md

@@ -30,22 +30,38 @@ The sample evidence is fictional. The default backend is the locally
 authenticated Claude Code CLI; add `--backend openai --model llama3.1
 --base-url http://localhost:11434/v1` to run fully local via Ollama.
 
-## Live — ground the panel in your broker
+## Live — the full reference deployment, step by step
 
-1. Copy `mcp.example.json` to `mcp.json` and complete authentication per your
-   MCP provider's documentation (for Robinhood, the agentic trading MCP).
-2. Copy `config.yaml` from this directory to the repository root (it is
-   gitignored there) and adjust the watchlist subjects to your own.
-3. Deliberate:
+Everything below is configuration; no code changes are required.
+
+1. **Install**: `uv tool install caucus` (from PyPI).
+2. **Broker MCP**: copy `mcp.example.json` to `mcp.json`; run one interactive
+   `claude` session with it to complete the provider's authentication.
+3. **Config**: copy `config.yaml` and `news_evidence.py` from this directory
+   into your working directory; set `notify.to` to your address and export
+   `GMAIL_ADDRESS`/`GMAIL_APP_PASSWORD` (a Gmail app password).
+4. **Standing plans**: record your cadenced builds/trims and trigger rules —
+   they are injected into every deliberation as evidence:
 
 ```bash
-uv run caucus deliberate "Trim the QQQ position toward its target this week?"
+caucus intents add "ACME build" --direction build --target 5% \
+  --pacing "weekly on dips" --cadence-days 7
+caucus intents add "XYZ exit at breakeven" --direction trim \
+  --target "exit full position" --notes "sell all at cost basis 114.94"
 ```
 
-Each analyst can now call the allowed read-only tools — quotes, historicals,
-portfolio state — and cite what it fetched as evidence. Tool output is
-covered by Caucus's system-level data-not-instructions guard; only
-**read-only** tools are allowed in this example by design.
+5. **Run**: `caucus briefing` — the agenda's four standing questions are
+   deliberated in order, the briefing is rendered and emailed, and every
+   decision (with dissent) lands in the hash-chained log.
+6. **Schedule**: `mkdir -p ~/caucus-live/logs` first (launchd opens its log
+   path before the script runs), then adapt `run-caucus.sh` (secrets from an
+   env file) and either the launchd template `com.example.caucus.plist`
+   (macOS) or the cron line in its comments (Linux).
+
+Each analyst calls the allowed read-only tools — quotes, historicals,
+portfolio, option chains, scans — and cites what it fetched as evidence.
+Tool output is covered by Caucus's system-level data-not-instructions guard;
+only **read-only** tools are allowed in this example by design.
 
 ## Guardrails carried over from the reference system
 

caucus-0.2.2/examples/trading-robinhood/com.example.caucus.plist

@@ -0,0 +1,25 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<!-- launchd template (macOS): copy to ~/Library/LaunchAgents/com.example.caucus.plist,
+     adjust the script path and times, then:
+       launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.example.caucus.plist
+     On Linux, use cron instead:
+       15 8,14 * * 1-5 CAUCUS_DIR=$HOME/caucus-live bash $HOME/caucus-live/run-caucus.sh -->
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>com.example.caucus</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>/bin/bash</string>
+        <string>/Users/YOURUSER/caucus-live/run-caucus.sh</string>
+    </array>
+    <key>StartCalendarInterval</key>
+    <array>
+        <dict><key>Hour</key><integer>8</integer><key>Minute</key><integer>15</integer></dict>
+        <dict><key>Hour</key><integer>14</integer><key>Minute</key><integer>45</integer></dict>
+    </array>
+    <key>StandardErrorPath</key>
+    <string>/Users/YOURUSER/caucus-live/logs/launchd.err</string>
+</dict>
+</plist>

caucus-0.2.2/examples/trading-robinhood/config.yaml

@@ -0,0 +1,72 @@
+# Trading example configuration — a faithful copy of the reference deployment.
+# Copy to your working directory as config.yaml; requires mcp.json (see
+# mcp.example.json) for live broker grounding.
+
+log: decisions.jsonl
+
+# Standing plans (cadenced builds/trims, trigger rules) — create with
+# 'caucus intents add', e.g.:
+#   caucus intents add "ACME build" --direction build --target 5% \
+#     --pacing "weekly on dips" --cadence-days 7
+intents: intents.db
+
+evidence_sources:
+  # Keyless news/macro feeds (Fed press RSS, Hacker News, Polymarket);
+  # per-feed tolerant — a dead feed becomes a note, never a blocked briefing.
+  - name: news-macro
+    command: python3 news_evidence.py
+    timeout_seconds: 60
+  # Pattern for deterministic indicators: compute MAs/momentum/regime in
+  # plain code from your own price cache and print JSON evidence items —
+  # the panel reasons over numbers it did not produce.
+  # - name: quant-snapshot
+  #   command: python3 snapshot_evidence.py
+  #   timeout_seconds: 30
+
+backend:
+  type: claude
+  mcp_config: mcp.json
+  # Read-only tools ONLY — this deployment deliberates and records, never trades.
+  allowed_tools:
+    - mcp__robinhood-trading__get_equity_quotes
+    - mcp__robinhood-trading__get_equity_historicals
+    - mcp__robinhood-trading__get_portfolio
+    - mcp__robinhood-trading__get_equity_positions
+    - mcp__robinhood-trading__get_index_quotes
+    - mcp__robinhood-trading__get_option_chains
+    - mcp__robinhood-trading__get_option_instruments
+    - mcp__robinhood-trading__get_option_quotes
+    - mcp__robinhood-trading__get_scans
+    - mcp__robinhood-trading__run_scan
+    - mcp__robinhood-trading__get_earnings_calendar
+
+panel:
+  - name: macro
+    charge: >-
+      Assess the macro and market regime relevant to the question. Use the
+      news/macro evidence and fetch current quotes rather than assuming;
+      state which signals support or undermine the proposal.
+  - name: momentum
+    charge: >-
+      Evaluate trend and momentum from recent historicals; judge against
+      moving-average position and price behavior, not narrative.
+  - name: risk-officer
+    charge: >-
+      Argue the downside. Quantify what a bad outcome costs given current
+      position sizes (fetch them), concentration, and liquidity. Oppose
+      anything that breaches prudent sizing or deviates from standing
+      intents without strong cause. For options, insist collateral is
+      computed from cash plus liquid reserves, never literal cash alone.
+
+# The standing questions every 'caucus briefing' run answers, in order.
+agenda:
+  - "Given the open intents, live positions, and current prices: which intent, if any, is due for its next action today, and what exactly should be done?"
+  - "Does the current market regime, the news, or any position behavior warrant a defensive action (hedge, trim, or pausing an intent) beyond the standing plans?"
+  - "Income: is there an attractive cash-secured put or covered call this run? Use live option chains (~30-45 DTE, ~0.25 delta) on names held or gladly owned per the intents; size against available collateral; skip any name within 14 days of earnings."
+  - "Opportunity scan: screen today's market movers for at most one new candidate consistent with the intents and regime; drop anything illiquid or junk-quality. If nothing qualifies, say so plainly."
+
+# Delivery — Gmail-friendly SMTP; credentials come from the environment
+# variables GMAIL_ADDRESS and GMAIL_APP_PASSWORD (never from this file).
+notify:
+  type: email
+  to: you@example.com

caucus-0.2.2/examples/trading-robinhood/news_evidence.py

@@ -0,0 +1,64 @@
+"""Evidence source: keyless news/macro feeds, per-feed tolerant.
+
+Always exits 0 with valid JSON — a dead feed becomes a note, not a failure,
+so one outage never blocks the briefing.
+"""
+
+import json
+import re
+import urllib.request
+
+ITEMS = []
+
+
+def fetch(url, timeout=10):
+    req = urllib.request.Request(url, headers={"User-Agent": "caucus-evidence/1.0"})
+    with urllib.request.urlopen(req, timeout=timeout) as resp:
+        return resp.read().decode("utf-8", "replace")
+
+
+def add(source, ref, content):
+    ITEMS.append({"source": source, "ref": str(ref), "content": str(content)[:400]})
+
+
+try:
+    xml = fetch("https://www.federalreserve.gov/feeds/press_all.xml")
+    titles = re.findall(r"<title>(.*?)</title>", xml)[1:6]
+    dates = re.findall(r"<pubDate>(.*?)</pubDate>", xml)[:5]
+    for title, date in zip(titles, dates):
+        add("fed-press", date, title)
+except Exception as err:
+    add("fed-press", "unavailable", "Fed press feed fetch failed: " + str(err))
+
+try:
+    hn = json.loads(
+        fetch(
+            "https://hn.algolia.com/api/v1/search_by_date?query=semiconductor%20OR%20NVDA%20OR%20AI%20chips&tags=story&hitsPerPage=5"
+        )
+    )
+    for hit in hn.get("hits", [])[:5]:
+        title = str(hit.get("title"))
+        points = str(hit.get("points"))
+        add("hackernews", hit.get("created_at", ""), title + " (" + points + " pts)")
+except Exception as err:
+    add("hackernews", "unavailable", "HN fetch failed: " + str(err))
+
+try:
+    markets = json.loads(
+        fetch(
+            "https://gamma-api.polymarket.com/markets?closed=false&active=true&order=volumeNum&ascending=false&limit=30"
+        )
+    )
+    kept = 0
+    for market in markets:
+        question = str(market.get("question", ""))
+        if kept < 5 and re.search(r"fed|fomc|cpi|inflation|rate", question, re.I):
+            prices = str(market.get("outcomePrices"))
+            add("polymarket", question[:60], "active market, implied prices " + prices)
+            kept += 1
+    if kept == 0:
+        add("polymarket", "no-matches", "no active Fed/CPI/inflation markets in top 30 by volume")
+except Exception as err:
+    add("polymarket", "unavailable", "Polymarket fetch failed: " + str(err))
+
+print(json.dumps(ITEMS))

caucus-0.2.2/examples/trading-robinhood/run-caucus.sh

@@ -0,0 +1,24 @@
+#!/bin/bash
+# Headless scheduled Caucus briefing — the reference deployment's launcher.
+# Adjust CAUCUS_DIR and ENVF, then schedule with cron or the launchd template.
+set -uo pipefail
+
+CAUCUS_DIR="${CAUCUS_DIR:-$HOME/caucus-live}"
+ENVF="${CAUCUS_ENV_FILE:-$CAUCUS_DIR/.env}"
+
+cd "$CAUCUS_DIR" || exit 1
+export PATH="$HOME/.local/bin:/opt/homebrew/bin:/usr/local/bin:$PATH"
+
+# Secrets stay in an env file (never in config.yaml): the Claude Code OAuth
+# token for headless runs and the SMTP credentials for the email notifier.
+for var in CLAUDE_CODE_OAUTH_TOKEN GMAIL_ADDRESS GMAIL_APP_PASSWORD; do
+  value=$(grep -E "^${var}=" "$ENVF" 2>/dev/null | head -1 | cut -d= -f2-)
+  [ -n "$value" ] && export "$var"="$value"
+done
+
+mkdir -p logs
+TS=$(date +%Y%m%d-%H%M)
+caucus briefing >> "logs/run-${TS}.log" 2>&1
+RC=$?
+echo "$(date '+%Y-%m-%d %H:%M:%S') rc=${RC}" >> logs/run-history.log
+exit $RC

{caucus-0.2.1 → caucus-0.2.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "caucus"
-version = "0.2.1"
+version = "0.2.2"
 description = "Your AI agents, deliberating on the record. MCP-grounded multi-agent consensus with recorded dissent and an auditable decision log."
 readme = "README.md"
 requires-python = ">=3.11"

{caucus-0.2.1 → caucus-0.2.2}/src/caucus/__init__.py

@@ -1,3 +1,3 @@
 """Caucus — AI agents deliberating on the record."""
 
-__version__ = "0.2.1"
+__version__ = "0.2.2"

{caucus-0.2.1 → caucus-0.2.2}/uv.lock

@@ -34,7 +34,7 @@ wheels = [
 
 [[package]]
 name = "caucus"
-version = "0.2.1"
+version = "0.2.2"
 source = { editable = "." }
 dependencies = [
     { name = "pyyaml" },

caucus-0.2.1/examples/trading-robinhood/config.yaml

@@ -1,41 +0,0 @@
-# Trading example configuration — copy to the repository root as config.yaml.
-# Requires mcp.json (see mcp.example.json) for live broker grounding.
-
-log: decisions.jsonl
-
-backend:
-  type: claude
-  mcp_config: mcp.json
-  # Read-only tools ONLY — this example deliberates, it never trades.
-  allowed_tools:
-    - mcp__robinhood-trading__get_equity_quotes
-    - mcp__robinhood-trading__get_equity_historicals
-    - mcp__robinhood-trading__get_portfolio
-    - mcp__robinhood-trading__get_equity_positions
-
-panel:
-  - name: macro
-    charge: >-
-      Assess the macro and market regime relevant to the question. Fetch
-      current quotes and index levels rather than assuming; state which
-      regime signals support or undermine the proposal.
-  - name: momentum
-    charge: >-
-      Evaluate trend and momentum. Fetch recent historicals; judge the
-      proposal against moving-average position and recent price behavior,
-      not narrative.
-  - name: risk-officer
-    charge: >-
-      Argue the downside. Quantify what a bad outcome costs given current
-      position sizes (fetch them), concentration, and liquidity. Oppose
-      anything that breaches prudent sizing even if the thesis is good.
-
-# The standing questions every briefing run answers ('caucus briefing').
-agenda:
-  - "Given the open intents, live positions, and current prices: which intent, if any, is due for its next action today, and what exactly should be done?"
-  - "Does current market regime or any position's behavior warrant a defensive action (hedge, trim, or pause of an intent) beyond the standing plans?"
-
-# Delivery — Gmail via an app password; the env vars hold the credentials.
-# notify:
-#   type: email
-#   to: you@example.com