frontier-council 0.1.0__py3-none-any.whl

frontier_council/__init__.py

@@ -0,0 +1,19 @@
+"""Frontier Council - Multi-model deliberation for important decisions."""
+
+__version__ = "0.1.0"
+
+from .council import (
+    run_council,
+    run_blind_phase_parallel,
+    detect_social_context,
+    COUNCIL,
+    JUDGE_MODEL,
+)
+
+__all__ = [
+    "run_council",
+    "run_blind_phase_parallel",
+    "detect_social_context",
+    "COUNCIL",
+    "JUDGE_MODEL",
+]

frontier_council/cli.py

@@ -0,0 +1,214 @@
+"""CLI entry point for frontier-council."""
+
+import argparse
+import json
+import os
+import random
+import subprocess
+import sys
+from datetime import datetime
+from pathlib import Path
+
+from .council import (
+    COUNCIL,
+    detect_social_context,
+    run_council,
+)
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="LLM Council - Multi-model deliberation for important decisions",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  frontier-council "Should we use microservices or monolith?"
+  frontier-council "What questions should I ask?" --social
+  frontier-council "Career decision" --persona "builder who hates process work"
+  frontier-council "Architecture choice" --rounds 3 --output transcript.md
+        """,
+    )
+    parser.add_argument("question", help="The question for the council to deliberate")
+    parser.add_argument(
+        "--rounds",
+        type=int,
+        default=2,
+        help="Number of deliberation rounds (default: 2, exits early on consensus)",
+    )
+    parser.add_argument(
+        "--quiet",
+        action="store_true",
+        help="Suppress progress output",
+    )
+    parser.add_argument(
+        "--output", "-o",
+        help="Save transcript to file",
+    )
+    parser.add_argument(
+        "--named",
+        action="store_true",
+        help="Show real model names instead of anonymous Speaker 1, 2, etc.",
+    )
+    parser.add_argument(
+        "--no-blind",
+        action="store_true",
+        help="Skip blind first-pass (faster, but more anchoring bias)",
+    )
+    parser.add_argument(
+        "--context", "-c",
+        help="Context hint for the judge (e.g., 'architecture decision', 'ethics question')",
+    )
+    parser.add_argument(
+        "--share",
+        action="store_true",
+        help="Upload transcript to secret GitHub Gist and print URL",
+    )
+    parser.add_argument(
+        "--social",
+        action="store_true",
+        help="Enable social calibration mode (for interview questions, outreach, networking)",
+    )
+    parser.add_argument(
+        "--persona", "-p",
+        help="Context about the person asking (e.g., 'builder who hates process work')",
+    )
+    parser.add_argument(
+        "--advocate",
+        type=int,
+        choices=[1, 2, 3, 4, 5],
+        help="Which speaker (1-5) should be devil's advocate (default: random)",
+    )
+    args = parser.parse_args()
+
+    # Auto-detect social context if not explicitly set
+    social_mode = args.social or detect_social_context(args.question)
+    if social_mode and not args.social and not args.quiet:
+        print("(Auto-detected social context - enabling social calibration mode)")
+        print()
+
+    # Get API keys
+    api_key = os.environ.get("OPENROUTER_API_KEY")
+    if not api_key:
+        print("Error: OPENROUTER_API_KEY environment variable not set", file=sys.stderr)
+        sys.exit(1)
+
+    google_api_key = os.environ.get("GOOGLE_API_KEY")
+    moonshot_api_key = os.environ.get("MOONSHOT_API_KEY")
+
+    use_blind = not args.no_blind
+
+    if not args.quiet:
+        mode_parts = []
+        mode_parts.append("named" if args.named else "anonymous")
+        mode_parts.append("blind first-pass" if use_blind else "no blind phase")
+        if social_mode:
+            mode_parts.append("social calibration")
+        print(f"Running LLM Council ({', '.join(mode_parts)})...")
+        fallbacks = []
+        if google_api_key:
+            fallbacks.append("Gemini→AI Studio")
+        if moonshot_api_key:
+            fallbacks.append("Kimi→Moonshot")
+        if fallbacks:
+            print(f"(Fallbacks enabled: {', '.join(fallbacks)})")
+        print()
+
+    try:
+        advocate_idx = (args.advocate - 1) if args.advocate else random.randint(0, len(COUNCIL) - 1)
+
+        if not args.quiet and args.persona:
+            print(f"(Persona context: {args.persona})")
+            print()
+        if not args.quiet:
+            advocate_name = COUNCIL[advocate_idx][0]
+            print(f"(Devil's advocate: {advocate_name})")
+            print()
+
+        transcript, failed_models = run_council(
+            question=args.question,
+            council_config=COUNCIL,
+            api_key=api_key,
+            google_api_key=google_api_key,
+            moonshot_api_key=moonshot_api_key,
+            rounds=args.rounds,
+            verbose=not args.quiet,
+            anonymous=not args.named,
+            blind=use_blind,
+            context=args.context,
+            social_mode=social_mode,
+            persona=args.persona,
+            advocate_idx=advocate_idx,
+        )
+
+        # Print failure summary
+        if failed_models and not args.quiet:
+            print()
+            print("=" * 60)
+            print("⚠️  MODEL FAILURES")
+            print("=" * 60)
+            for failure in failed_models:
+                print(f"  • {failure}")
+            working_count = len(COUNCIL) - len(set(f.split(":")[0].split(" (")[0] for f in failed_models))
+            print(f"\nCouncil ran with {working_count}/{len(COUNCIL)} models")
+            print("=" * 60)
+            print()
+
+        # Save transcript
+        if args.output:
+            Path(args.output).write_text(transcript)
+            if not args.quiet:
+                print(f"Transcript saved to: {args.output}")
+
+        # Share via gist
+        gist_url = None
+        if args.share:
+            try:
+                import tempfile
+                with tempfile.NamedTemporaryFile(
+                    mode='w', suffix='.md', prefix='council-', delete=False
+                ) as f:
+                    f.write(f"# LLM Council Deliberation\n\n")
+                    f.write(f"**Question:** {args.question}\n\n")
+                    if args.context:
+                        f.write(f"**Context:** {args.context}\n\n")
+                    f.write(f"**Date:** {datetime.now().strftime('%Y-%m-%d %H:%M')}\n\n---\n\n")
+                    f.write(transcript)
+                    temp_path = f.name
+
+                result = subprocess.run(
+                    ["gh", "gist", "create", temp_path, "--desc", f"LLM Council: {args.question[:50]}"],
+                    capture_output=True, text=True
+                )
+                os.unlink(temp_path)
+
+                if result.returncode == 0:
+                    gist_url = result.stdout.strip()
+                    print(f"\n🔗 Shared: {gist_url}")
+                else:
+                    print(f"Gist creation failed: {result.stderr}", file=sys.stderr)
+            except FileNotFoundError:
+                print("Error: 'gh' CLI not found. Install with: brew install gh", file=sys.stderr)
+
+        # Log to history
+        history_file = Path(__file__).parent.parent / "council_history.jsonl"
+        log_entry = {
+            "timestamp": datetime.now().isoformat(),
+            "question": args.question[:200],
+            "gist": gist_url,
+            "context": args.context,
+            "rounds": args.rounds,
+            "blind": use_blind,
+            "models": [name for name, _, _ in COUNCIL],
+        }
+        with open(history_file, "a") as f:
+            f.write(json.dumps(log_entry) + "\n")
+
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        import traceback
+        traceback.print_exc()
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

frontier_council/council.py

@@ -0,0 +1,830 @@
+"""Core council deliberation logic."""
+
+import asyncio
+import httpx
+import json
+import re
+from pathlib import Path
+
+OPENROUTER_URL = "https://openrouter.ai/api/v1/chat/completions"
+GOOGLE_AI_STUDIO_URL = "https://generativelanguage.googleapis.com/v1beta/models"
+MOONSHOT_URL = "https://api.moonshot.cn/v1/chat/completions"
+
+# Model configurations (all via OpenRouter, with fallbacks where available)
+# Format: (name, openrouter_model, fallback) - fallback is (provider, model) or None
+# Providers: "google" = AI Studio, "moonshot" = Moonshot API
+COUNCIL = [
+    ("Claude", "anthropic/claude-opus-4.5", None),
+    ("GPT", "openai/gpt-5.2-pro", None),
+    ("Gemini", "google/gemini-3-pro-preview", ("google", "gemini-2.5-pro")),
+    ("Grok", "x-ai/grok-4", None),
+    ("Kimi", "moonshotai/kimi-k2.5", ("moonshot", "kimi-k2.5")),
+]
+
+JUDGE_MODEL = "anthropic/claude-opus-4.5"
+
+# Keywords that suggest social/conversational context (auto-detect)
+SOCIAL_KEYWORDS = [
+    "interview", "ask him", "ask her", "ask them", "question to ask",
+    "networking", "outreach", "message", "email", "linkedin",
+    "coffee chat", "informational", "reach out", "follow up",
+    "what should i say", "how should i respond", "conversation",
+]
+
+# Thinking models don't stream well - use non-streaming for these
+THINKING_MODEL_SUFFIXES = {
+    "gemini-3-pro-preview",
+    "kimi-k2.5",
+    "deepseek-r1",
+    "o1-preview", "o1-mini", "o1",
+    "o3-preview", "o3-mini", "o3",
+}
+
+
+def is_thinking_model(model: str) -> bool:
+    """Check if model is a thinking model that doesn't stream well."""
+    model_name = model.split("/")[-1].lower()
+    return model_name in THINKING_MODEL_SUFFIXES
+
+
+def detect_social_context(question: str) -> bool:
+    """Auto-detect if the question is about social/conversational context."""
+    question_lower = question.lower()
+    return any(keyword in question_lower for keyword in SOCIAL_KEYWORDS)
+
+
+def query_model(
+    api_key: str,
+    model: str,
+    messages: list[dict],
+    max_tokens: int = 1500,
+    timeout: float = 120.0,
+    stream: bool = False,
+    retries: int = 2,
+) -> str:
+    """Query a model via OpenRouter with retry logic for flaky models."""
+    if is_thinking_model(model):
+        max_tokens = max(max_tokens, 4000)
+        timeout = max(timeout, 180.0)
+
+    if stream and not is_thinking_model(model):
+        result = query_model_streaming(api_key, model, messages, max_tokens, timeout)
+        if not result.startswith("["):
+            return result
+        print("(Streaming failed, retrying without streaming...)", flush=True)
+
+    for attempt in range(retries + 1):
+        try:
+            response = httpx.post(
+                OPENROUTER_URL,
+                headers={"Authorization": f"Bearer {api_key}"},
+                json={
+                    "model": model,
+                    "messages": messages,
+                    "max_tokens": max_tokens,
+                },
+                timeout=timeout,
+            )
+        except (httpx.RequestError, httpx.RemoteProtocolError) as e:
+            if attempt < retries:
+                continue
+            return f"[Error: Connection failed for {model}: {e}]"
+
+        if response.status_code != 200:
+            if attempt < retries:
+                continue
+            return f"[Error: HTTP {response.status_code} from {model}]"
+
+        data = response.json()
+
+        if "error" in data:
+            if attempt < retries:
+                continue
+            return f"[Error: {data['error'].get('message', data['error'])}]"
+
+        if "choices" not in data or not data["choices"]:
+            if attempt < retries:
+                continue
+            return f"[Error: No response from {model}]"
+
+        content = data["choices"][0]["message"]["content"]
+
+        if not content or not content.strip():
+            reasoning = data["choices"][0]["message"].get("reasoning", "")
+            if reasoning and reasoning.strip():
+                if attempt < retries:
+                    continue
+                return f"[Model still thinking - needs more tokens. Partial reasoning: {reasoning[:150]}...]"
+            if attempt < retries:
+                continue
+            return f"[No response from {model} after {retries + 1} attempts]"
+
+        if "<think>" in content:
+            content = re.sub(r'<think>.*?</think>', '', content, flags=re.DOTALL).strip()
+
+        return content
+
+    return f"[Error: Failed to get response from {model}]"
+
+
+def query_google_ai_studio(
+    api_key: str,
+    model: str,
+    messages: list[dict],
+    max_tokens: int = 8192,
+    timeout: float = 120.0,
+    retries: int = 2,
+) -> str:
+    """Query Google AI Studio directly (fallback for Gemini models)."""
+    contents = []
+    system_instruction = None
+
+    for msg in messages:
+        role = msg["role"]
+        content = msg["content"]
+
+        if role == "system":
+            system_instruction = content
+        elif role == "user":
+            contents.append({"role": "user", "parts": [{"text": content}]})
+        elif role == "assistant":
+            contents.append({"role": "model", "parts": [{"text": content}]})
+
+    body = {
+        "contents": contents,
+        "generationConfig": {
+            "maxOutputTokens": max_tokens,
+        }
+    }
+    if system_instruction:
+        body["systemInstruction"] = {"parts": [{"text": system_instruction}]}
+
+    url = f"{GOOGLE_AI_STUDIO_URL}/{model}:generateContent?key={api_key}"
+
+    for attempt in range(retries + 1):
+        try:
+            response = httpx.post(url, json=body, timeout=timeout)
+
+            if response.status_code != 200:
+                if attempt < retries:
+                    continue
+                return f"[Error: HTTP {response.status_code} from AI Studio {model}]"
+
+            data = response.json()
+
+            if "error" in data:
+                if attempt < retries:
+                    continue
+                return f"[Error: {data['error'].get('message', data['error'])}]"
+
+            candidates = data.get("candidates", [])
+            if not candidates:
+                if attempt < retries:
+                    continue
+                return f"[Error: No candidates from AI Studio {model}]"
+
+            parts = candidates[0].get("content", {}).get("parts", [])
+            if not parts:
+                if attempt < retries:
+                    continue
+                return f"[Error: No content from AI Studio {model}]"
+
+            content = parts[0].get("text", "")
+            if not content.strip():
+                if attempt < retries:
+                    continue
+                return f"[No response from AI Studio {model} after {retries + 1} attempts]"
+
+            return content
+
+        except httpx.TimeoutException:
+            if attempt < retries:
+                continue
+            return f"[Error: Timeout from AI Studio {model}]"
+        except httpx.RequestError as e:
+            if attempt < retries:
+                continue
+            return f"[Error: Request failed for AI Studio {model}: {e}]"
+
+    return f"[Error: Failed to get response from AI Studio {model}]"
+
+
+def query_moonshot(
+    api_key: str,
+    model: str,
+    messages: list[dict],
+    max_tokens: int = 8192,
+    timeout: float = 120.0,
+    retries: int = 2,
+) -> str:
+    """Query Moonshot API directly (fallback for Kimi models)."""
+    for attempt in range(retries + 1):
+        try:
+            response = httpx.post(
+                MOONSHOT_URL,
+                headers={"Authorization": f"Bearer {api_key}"},
+                json={
+                    "model": model,
+                    "messages": messages,
+                    "max_tokens": max_tokens,
+                },
+                timeout=timeout,
+            )
+
+            if response.status_code != 200:
+                if attempt < retries:
+                    continue
+                return f"[Error: HTTP {response.status_code} from Moonshot {model}]"
+
+            data = response.json()
+
+            if "error" in data:
+                if attempt < retries:
+                    continue
+                return f"[Error: {data['error'].get('message', data['error'])}]"
+
+            if "choices" not in data or not data["choices"]:
+                if attempt < retries:
+                    continue
+                return f"[Error: No response from Moonshot {model}]"
+
+            content = data["choices"][0]["message"]["content"]
+
+            if not content or not content.strip():
+                if attempt < retries:
+                    continue
+                return f"[No response from Moonshot {model} after {retries + 1} attempts]"
+
+            return content
+
+        except httpx.TimeoutException:
+            if attempt < retries:
+                continue
+            return f"[Error: Timeout from Moonshot {model}]"
+        except httpx.RequestError as e:
+            if attempt < retries:
+                continue
+            return f"[Error: Request failed for Moonshot {model}: {e}]"
+
+    return f"[Error: Failed to get response from Moonshot {model}]"
+
+
+def query_model_streaming(
+    api_key: str,
+    model: str,
+    messages: list[dict],
+    max_tokens: int = 1500,
+    timeout: float = 120.0,
+) -> str:
+    """Query a model with streaming output - prints tokens as they arrive."""
+    import json as json_module
+
+    full_content = []
+    in_think_block = False
+    error_msg = None
+
+    try:
+        with httpx.stream(
+            "POST",
+            OPENROUTER_URL,
+            headers={"Authorization": f"Bearer {api_key}"},
+            json={
+                "model": model,
+                "messages": messages,
+                "max_tokens": max_tokens,
+                "stream": True,
+            },
+            timeout=timeout,
+        ) as response:
+            if response.status_code != 200:
+                error_msg = f"[Error: HTTP {response.status_code} from {model}]"
+            else:
+                for line in response.iter_lines():
+                    if not line or line.startswith(":"):
+                        continue
+
+                    if line.startswith("data: "):
+                        data_str = line[6:]
+                        if data_str.strip() == "[DONE]":
+                            break
+
+                        try:
+                            data = json_module.loads(data_str)
+                            if "error" in data:
+                                error_msg = f"[Error: {data['error'].get('message', data['error'])}]"
+                                break
+
+                            if "choices" in data and data["choices"]:
+                                delta = data["choices"][0].get("delta", {})
+                                content = delta.get("content", "")
+                                if content:
+                                    if "<think>" in content:
+                                        in_think_block = True
+                                    if in_think_block:
+                                        if "</think>" in content:
+                                            in_think_block = False
+                                            content = content.split("</think>", 1)[-1]
+                                        else:
+                                            continue
+
+                                    if content:
+                                        print(content, end="", flush=True)
+                                        full_content.append(content)
+                        except json_module.JSONDecodeError:
+                            pass
+
+    except httpx.TimeoutException:
+        error_msg = f"[Error: Timeout from {model}]"
+    except (httpx.RequestError, httpx.RemoteProtocolError) as e:
+        error_msg = f"[Error: Connection failed for {model}: {e}]"
+
+    print()
+
+    if error_msg:
+        print(error_msg)
+        return error_msg
+
+    if not full_content:
+        empty_msg = f"[No response from {model}]"
+        print(empty_msg)
+        return empty_msg
+
+    return "".join(full_content)
+
+
+async def query_model_async(
+    client: httpx.AsyncClient,
+    model: str,
+    messages: list[dict],
+    name: str,
+    fallback: tuple[str, str] | None = None,
+    google_api_key: str | None = None,
+    moonshot_api_key: str | None = None,
+    max_tokens: int = 500,
+    retries: int = 2,
+) -> tuple[str, str, str]:
+    """Async query for parallel blind phase. Returns (name, model_name, response)."""
+    if is_thinking_model(model):
+        max_tokens = max(max_tokens, 2000)
+
+    model_name = model.split("/")[-1]
+
+    for attempt in range(retries + 1):
+        try:
+            response = await client.post(
+                OPENROUTER_URL,
+                json={
+                    "model": model,
+                    "messages": messages,
+                    "max_tokens": max_tokens,
+                },
+            )
+
+            if response.status_code != 200:
+                if attempt < retries:
+                    continue
+                break
+
+            data = response.json()
+
+            if "error" in data:
+                if attempt < retries:
+                    continue
+                break
+
+            if "choices" not in data or not data["choices"]:
+                if attempt < retries:
+                    continue
+                break
+
+            content = data["choices"][0]["message"]["content"]
+
+            if not content or not content.strip():
+                reasoning = data["choices"][0]["message"].get("reasoning", "")
+                if reasoning and reasoning.strip():
+                    if attempt < retries:
+                        continue
+                    return (name, model_name, f"[Model still thinking - increase max_tokens. Partial: {reasoning[:200]}...]")
+                if attempt < retries:
+                    continue
+                break
+
+            if "<think>" in content:
+                content = re.sub(r'<think>.*?</think>', '', content, flags=re.DOTALL).strip()
+
+            return (name, model_name, content)
+
+        except (httpx.RequestError, httpx.RemoteProtocolError):
+            if attempt < retries:
+                continue
+            break
+
+    # Try fallbacks synchronously
+    if fallback:
+        fallback_provider, fallback_model = fallback
+        if fallback_provider == "google" and google_api_key:
+            response = query_google_ai_studio(google_api_key, fallback_model, messages, max_tokens=max_tokens)
+            return (name, fallback_model, response)
+        elif fallback_provider == "moonshot" and moonshot_api_key:
+            response = query_moonshot(moonshot_api_key, fallback_model, messages, max_tokens=max_tokens)
+            return (name, fallback_model, response)
+
+    return (name, model_name, f"[No response from {model_name} after {retries + 1} attempts]")
+
+
+async def run_blind_phase_parallel(
+    question: str,
+    council_config: list[tuple[str, str, tuple[str, str] | None]],
+    api_key: str,
+    google_api_key: str | None = None,
+    moonshot_api_key: str | None = None,
+    verbose: bool = True,
+    persona: str | None = None,
+) -> list[tuple[str, str, str]]:
+    """Parallel blind first-pass: all models stake claims simultaneously."""
+    blind_system = """You are participating in the BLIND PHASE of a council deliberation.
+
+Stake your initial position on the question BEFORE seeing what others think.
+This prevents anchoring bias.
+
+Provide a CLAIM SKETCH (not a full response):
+1. Your core position (1-2 sentences)
+2. Top 3 supporting claims or considerations
+3. Key assumption or uncertainty
+
+Keep it concise (~100 words). The full deliberation comes later."""
+
+    if persona:
+        blind_system += f"""
+
+IMPORTANT CONTEXT about the person asking:
+{persona}
+
+Factor this into your advice — don't just give strategically optimal answers, consider what fits THIS person."""
+
+    if verbose:
+        print("=" * 60)
+        print("BLIND PHASE (independent claims)")
+        print("=" * 60)
+        print()
+
+    messages = [
+        {"role": "system", "content": blind_system},
+        {"role": "user", "content": f"Question:\n\n{question}"},
+    ]
+
+    async with httpx.AsyncClient(
+        headers={"Authorization": f"Bearer {api_key}"},
+        timeout=120.0,
+    ) as client:
+        tasks = [
+            query_model_async(
+                client, model, messages, name, fallback,
+                google_api_key, moonshot_api_key
+            )
+            for name, model, fallback in council_config
+        ]
+
+        if verbose:
+            print("(querying all models in parallel...)")
+
+        results = await asyncio.gather(*tasks, return_exceptions=True)
+
+    blind_claims = []
+    for i, result in enumerate(results):
+        name, model, _ = council_config[i]
+        model_name = model.split("/")[-1]
+
+        if isinstance(result, Exception):
+            blind_claims.append((name, model_name, f"[Error: {result}]"))
+        else:
+            blind_claims.append(result)
+
+    if verbose:
+        print()
+        for name, model_name, claims in blind_claims:
+            print(f"### {model_name} (blind)")
+            print(claims)
+            print()
+
+    return blind_claims
+
+
+def sanitize_speaker_content(content: str) -> str:
+    """Sanitize speaker content to prevent prompt injection."""
+    sanitized = content.replace("SYSTEM:", "[SYSTEM]:")
+    sanitized = sanitized.replace("INSTRUCTION:", "[INSTRUCTION]:")
+    sanitized = sanitized.replace("IGNORE PREVIOUS", "[IGNORE PREVIOUS]")
+    sanitized = sanitized.replace("OVERRIDE:", "[OVERRIDE]:")
+    return sanitized
+
+
+def detect_consensus(conversation: list[tuple[str, str]], council_size: int) -> tuple[bool, str]:
+    """Detect if council has converged. Returns (converged, reason)."""
+    if len(conversation) < council_size:
+        return False, "insufficient responses"
+
+    recent = [text for _, text in conversation[-council_size:]]
+
+    consensus_count = sum(1 for text in recent if "CONSENSUS:" in text.upper())
+    if consensus_count >= council_size - 1:
+        return True, "explicit consensus signals"
+
+    agreement_phrases = ["i agree with", "i concur", "we all agree", "consensus emerging"]
+    agreement_count = sum(
+        1 for text in recent
+        if any(phrase in text.lower() for phrase in agreement_phrases)
+    )
+    if agreement_count >= council_size - 1:
+        return True, "agreement language detected"
+
+    return False, "no consensus"
+
+
+def run_council(
+    question: str,
+    council_config: list[tuple[str, str, tuple[str, str] | None]],
+    api_key: str,
+    google_api_key: str | None = None,
+    moonshot_api_key: str | None = None,
+    rounds: int = 1,
+    verbose: bool = True,
+    anonymous: bool = True,
+    blind: bool = True,
+    context: str | None = None,
+    social_mode: bool = False,
+    persona: str | None = None,
+    advocate_idx: int | None = None,
+) -> tuple[str, list[str]]:
+    """Run the council deliberation. Returns (transcript, failed_models)."""
+
+    council_names = [name for name, _, _ in council_config]
+    blind_claims = []
+    failed_models = []
+
+    if blind:
+        blind_claims = asyncio.run(run_blind_phase_parallel(
+            question, council_config, api_key, google_api_key, moonshot_api_key, verbose, persona
+        ))
+        for name, model_name, claims in blind_claims:
+            if claims.startswith("["):
+                failed_models.append(f"{model_name} (blind): {claims}")
+
+    if anonymous:
+        display_names = {name: f"Speaker {i+1}" for i, (name, _, _) in enumerate(council_config)}
+    else:
+        display_names = {name: name for name, _, _ in council_config}
+
+    if verbose:
+        print(f"Council members: {council_names}")
+        if anonymous:
+            print("(Models see each other as Speaker 1, 2, etc. to prevent bias)")
+        print(f"Rounds: {rounds}")
+        print(f"Question: {question[:100]}{'...' if len(question) > 100 else ''}")
+        print()
+        print("=" * 60)
+        print("COUNCIL DELIBERATION")
+        print("=" * 60)
+        print()
+
+    conversation = []
+    output_parts = []
+
+    if blind_claims:
+        for name, model_name, claims in blind_claims:
+            output_parts.append(f"### {model_name} (blind)\n{claims}")
+
+    blind_context = ""
+    if blind_claims:
+        blind_lines = []
+        for name, _, claims in blind_claims:
+            dname = display_names[name]
+            blind_lines.append(f"**{dname}**: {sanitize_speaker_content(claims)}")
+        blind_context = "\n\n".join(blind_lines)
+
+    social_constraint = """
+
+SOCIAL CALIBRATION: This is a social/conversational context (interview, networking, outreach).
+Your output should feel natural in conversation - something you'd actually say over coffee.
+Avoid structured, multi-part diagnostic questions that sound like interrogation.
+Simple and human beats strategic and comprehensive. Optimize for being relatable, not thorough."""
+
+    devils_advocate_addition = """
+
+SPECIAL ROLE: You are the DEVIL'S ADVOCATE. Your job is to push back HARD.
+
+REQUIREMENTS:
+1. You MUST explicitly DISAGREE with at least one major point from the other speakers
+2. Identify the weakest assumption in the emerging consensus and attack it
+3. Consider: What would make this advice WRONG? What's the contrarian take?
+4. If everyone is converging too fast, that's a red flag — find the hidden complexity
+
+Don't just "add nuance" or "build on" — find something to genuinely challenge.
+If you can't find real disagreement, say why the consensus might be groupthink."""
+
+    first_speaker_with_blind = """You are {name}, speaking first in Round {round_num} of a council deliberation.
+
+You've seen everyone's BLIND CLAIMS (their independent initial positions). Now engage:
+1. Reference at least ONE other speaker's blind claim
+2. Agree, disagree, or build on their position
+3. Develop your own position further based on what you've learned
+
+Be direct. Challenge weak arguments. Don't be sycophantic."""
+
+    first_speaker_system = """You are {name}, speaking first in Round {round_num} of a council deliberation.
+
+As the first speaker, stake a clear position on the question. Be specific and substantive so others can engage with your points.
+
+End with 2-3 key claims that others should respond to."""
+
+    council_system = """You are {name}, participating in Round {round_num} of a council deliberation.
+
+REQUIREMENTS for your response:
+1. Reference at least ONE previous speaker by name (e.g., "I agree with Speaker 1 that..." or "Speaker 2's point about X overlooks...")
+2. State explicitly: AGREE, DISAGREE, or BUILD ON their specific point
+3. Add ONE new consideration not yet raised
+4. Keep response under 250 words — be concise and practical
+
+If you fully agree with emerging consensus, say: "CONSENSUS: [the agreed position]"
+
+Previous speakers this round: {previous_speakers}
+
+Be direct. Challenge weak arguments. Don't be sycophantic.
+Prioritize PRACTICAL, ACTIONABLE advice over academic observations. Avoid jargon."""
+
+    for round_num in range(rounds):
+        round_speakers = []
+        for idx, (name, model, fallback) in enumerate(council_config):
+            dname = display_names[name]
+
+            if idx == 0 and round_num == 0:
+                if blind_claims:
+                    system_prompt = first_speaker_with_blind.format(name=dname, round_num=round_num + 1)
+                else:
+                    system_prompt = first_speaker_system.format(name=dname, round_num=round_num + 1)
+            else:
+                if round_speakers:
+                    previous = ", ".join(round_speakers)
+                else:
+                    previous = ", ".join([display_names[n] for n, _, _ in council_config])
+                system_prompt = council_system.format(
+                    name=dname,
+                    round_num=round_num + 1,
+                    previous_speakers=previous
+                )
+
+            if social_mode:
+                system_prompt += social_constraint
+
+            if persona:
+                system_prompt += f"""
+
+IMPORTANT CONTEXT about the person asking:
+{persona}
+
+Factor this into your advice — don't just give strategically optimal answers, consider what fits THIS person."""
+
+            if idx == advocate_idx and round_num == 0:
+                system_prompt += devils_advocate_addition
+
+            user_content = f"Question for the council:\n\n{question}"
+            if blind_context:
+                user_content += f"\n\n---\n\nBLIND CLAIMS (independent initial positions):\n\n{blind_context}"
+
+            messages = [
+                {"role": "system", "content": system_prompt},
+                {"role": "user", "content": user_content},
+            ]
+
+            for speaker, text in conversation:
+                speaker_dname = display_names[speaker]
+                sanitized_text = sanitize_speaker_content(text)
+                messages.append({
+                    "role": "assistant" if speaker == name else "user",
+                    "content": f"[{speaker_dname}]: {sanitized_text}" if speaker != name else sanitized_text,
+                })
+
+            model_name = model.split("/")[-1]
+
+            if verbose:
+                print(f"### {model_name}")
+                if is_thinking_model(model):
+                    print("(thinking...)", flush=True)
+
+            response = query_model(api_key, model, messages, stream=verbose)
+
+            used_fallback = False
+            if response.startswith("[") and fallback:
+                fallback_provider, fallback_model = fallback
+
+                if fallback_provider == "google" and google_api_key:
+                    if verbose:
+                        print(f"(OpenRouter failed, trying AI Studio fallback: {fallback_model}...)", flush=True)
+                    response = query_google_ai_studio(google_api_key, fallback_model, messages)
+                    used_fallback = True
+                    model_name = fallback_model
+
+                elif fallback_provider == "moonshot" and moonshot_api_key:
+                    if verbose:
+                        print(f"(OpenRouter failed, trying Moonshot fallback: {fallback_model}...)", flush=True)
+                    response = query_moonshot(moonshot_api_key, fallback_model, messages)
+                    used_fallback = True
+                    model_name = fallback_model
+
+            if verbose and (is_thinking_model(model) or used_fallback):
+                print(response)
+
+            if response.startswith("["):
+                failed_models.append(f"{model_name}: {response}")
+
+            conversation.append((name, response))
+            round_speakers.append(dname)
+
+            if verbose:
+                print()
+
+            output_parts.append(f"### {model_name}\n{response}")
+
+        converged, reason = detect_consensus(conversation, len(council_config))
+        if converged:
+            if verbose:
+                print(f">>> CONSENSUS DETECTED ({reason}) - proceeding to judge\n")
+            break
+
+    # Judge synthesis
+    context_hint = ""
+    if context:
+        context_hint = f"\n\nContext about this question: {context}\nConsider this context when weighing perspectives and forming recommendations."
+
+    social_judge_section = ""
+    if social_mode:
+        social_judge_section = """
+
+## Social Calibration Check
+[Would the recommendation feel natural in conversation? Is it something you'd actually say, or does it sound like strategic over-optimization? If the council produced something too formal/structured, suggest a simpler, more human alternative.]"""
+
+    judge_system = f"""You are the Judge, responsible for synthesizing the council's deliberation.{context_hint}
+
+After the council members have shared their perspectives, you:
+1. Identify points of AGREEMENT across all members
+2. Identify points of DISAGREEMENT and explain the different views
+3. Provide a SYNTHESIS that captures the council's collective wisdom
+4. Give a final RECOMMENDATION based on the deliberation
+{"5. SOCIAL CALIBRATION: Check if the recommendation would feel natural in actual conversation" if social_mode else ""}
+
+Format your response as:
+
+## Points of Agreement
+[What the council agrees on]
+
+## Points of Disagreement
+[Where views differ and why]
+
+## Synthesis
+[The integrated perspective]
+
+## Recommendation
+[Your final recommendation based on the deliberation]
+{social_judge_section}
+Be balanced and fair. Acknowledge minority views. Don't just pick a winner.{" For social contexts, prioritize natural/human output over strategic optimization." if social_mode else ""}
+
+IMPORTANT: In your Recommendation, clearly distinguish:
+- **Do Now** — practical actions the user can take immediately
+- **Consider Later** — interesting ideas that require more infrastructure or scale
+
+Don't recommend building infrastructure for problems that don't exist yet."""
+
+    deliberation_text = "\n\n".join(
+        f"**{display_names[speaker]}**: {sanitize_speaker_content(text)}" for speaker, text in conversation
+    )
+
+    judge_messages = [
+        {"role": "system", "content": judge_system},
+        {"role": "user", "content": f"Question:\n{question}\n\n---\n\nCouncil Deliberation:\n\n{deliberation_text}"},
+    ]
+
+    judge_model_name = JUDGE_MODEL.split("/")[-1]
+
+    if verbose:
+        print(f"### Judge ({judge_model_name})")
+
+    judge_response = query_model(api_key, JUDGE_MODEL, judge_messages, max_tokens=1200, stream=verbose)
+
+    if verbose:
+        print()
+
+    output_parts.append(f"### Judge ({judge_model_name})\n{judge_response}")
+
+    if anonymous:
+        final_output = "\n\n".join(output_parts)
+        for name, model, _ in council_config:
+            anon_name = display_names[name]
+            model_name = model.split("/")[-1]
+            final_output = final_output.replace(f"### {anon_name}", f"### {model_name}")
+            final_output = final_output.replace(f"[{anon_name}]", f"[{model_name}]")
+            final_output = final_output.replace(f"**{anon_name}**", f"**{model_name}**")
+            final_output = final_output.replace(f"with {anon_name}", f"with {model_name}")
+            final_output = final_output.replace(f"{anon_name}'s", f"{model_name}'s")
+        return final_output, failed_models
+
+    return "\n\n".join(output_parts), failed_models

frontier_council-0.1.0.dist-info/METADATA

@@ -0,0 +1,150 @@
+Metadata-Version: 2.4
+Name: frontier-council
+Version: 0.1.0
+Summary: Multi-model deliberation for important decisions. 5 frontier LLMs debate, then a judge synthesizes consensus.
+Project-URL: Homepage, https://github.com/terry-li-hm/skills
+Author-email: Terry Li <terry.li.hm@gmail.com>
+License-Expression: MIT
+Keywords: ai,council,debate,deliberation,frontier,llm,multi-model,openrouter
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.25.0
+Description-Content-Type: text/markdown
+
+# Frontier Council
+
+Multi-model deliberation for important decisions. 5 frontier LLMs debate a question, then a judge synthesizes consensus.
+
+Inspired by [Andrej Karpathy's LLM Council](https://github.com/karpathy/llm-council), with added blind phase (anti-anchoring), explicit engagement requirements, devil's advocate role, and social calibration mode.
+
+## Models
+
+- Claude (claude-opus-4.5)
+- GPT (gpt-5.2-pro)
+- Gemini (gemini-3-pro-preview)
+- Grok (grok-4)
+- Kimi (kimi-k2.5)
+- Judge: Claude Opus 4.5
+
+## Installation
+
+```bash
+pip install frontier-council
+```
+
+Or with uv:
+```bash
+uv tool install frontier-council
+```
+
+## Setup
+
+Set your OpenRouter API key:
+```bash
+export OPENROUTER_API_KEY=sk-or-v1-...
+```
+
+Optional fallback keys (for flaky models):
+```bash
+export GOOGLE_API_KEY=AIza...      # Gemini fallback
+export MOONSHOT_API_KEY=sk-...     # Kimi fallback
+```
+
+## Usage
+
+```bash
+# Basic question
+frontier-council "Should we use microservices or monolith?"
+
+# With social calibration (for interview/networking questions)
+frontier-council "What questions should I ask in the interview?" --social
+
+# With persona context
+frontier-council "Should I take the job?" --persona "builder who hates process work"
+
+# Multiple rounds
+frontier-council "Architecture decision" --rounds 3
+
+# Save transcript
+frontier-council "Career question" --output transcript.md
+
+# Share via GitHub Gist
+frontier-council "Important decision" --share
+```
+
+## Options
+
+| Flag | Description |
+|------|-------------|
+| `--rounds N` | Number of deliberation rounds (default: 2, exits early on consensus) |
+| `--output FILE` | Save transcript to file |
+| `--named` | Let models see real names during deliberation (may increase bias) |
+| `--no-blind` | Skip blind first-pass (faster, but first speaker anchors others) |
+| `--context TEXT` | Context hint for judge (e.g., "architecture decision") |
+| `--share` | Upload transcript to secret GitHub Gist |
+| `--social` | Enable social calibration mode (auto-detected for interview/networking) |
+| `--persona TEXT` | Context about the person asking |
+| `--advocate N` | Which speaker (1-5) should be devil's advocate (default: random) |
+| `--quiet` | Suppress progress output |
+
+## How It Works
+
+**Blind First-Pass (Anti-Anchoring):**
+1. All models generate short "claim sketches" independently and in parallel
+2. This prevents the "first speaker lottery" where whoever speaks first anchors the debate
+3. Each model commits to an initial position before seeing any other responses
+
+**Deliberation Protocol:**
+1. All models see everyone's blind claims, then deliberate
+2. Each model MUST explicitly AGREE, DISAGREE, or BUILD ON previous speakers by name
+3. After each round, the system checks for consensus (4/5 agreement triggers early exit)
+4. Judge synthesizes the full deliberation
+
+**Anonymous Deliberation:**
+- Models see each other as "Speaker 1", "Speaker 2", etc. during deliberation
+- Prevents models from playing favorites based on vendor reputation
+- Output transcript shows real model names for readability
+
+## When to Use
+
+Use the council when:
+- Making an important decision that benefits from diverse perspectives
+- You want models to actually debate, not just answer in parallel
+- You need a synthesized recommendation, not raw comparison
+- Exploring trade-offs where different viewpoints matter
+
+Skip the council when:
+- You're just thinking out loud (exploratory discussions)
+- The answer depends on personal preference more than objective trade-offs
+- Speed matters (council takes 60-90 seconds)
+
+## Python API
+
+```python
+from frontier_council import run_council, COUNCIL
+import os
+
+api_key = os.environ["OPENROUTER_API_KEY"]
+
+transcript, failed_models = run_council(
+    question="Should we use microservices or monolith?",
+    council_config=COUNCIL,
+    api_key=api_key,
+    rounds=2,
+    verbose=True,
+    social_mode=False,
+)
+
+print(transcript)
+```
+
+## License
+
+MIT

frontier_council-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+frontier_council/__init__.py,sha256=VfpeWHijQ1z8zd_ecKPIjI6S9VT3E6yAQ1PVt8-eExU,357
+frontier_council/cli.py,sha256=BbM1cHWjAA0DBn4uyGKajaNAMxhKYQt-ZGNQ6hTnlkc,7337
+frontier_council/council.py,sha256=u2ir34dNostBOhXUi1R0wFEfBIEgiRX8thiS5lRFnnU,30226
+frontier_council-0.1.0.dist-info/METADATA,sha256=hZGQzWU0DUtuexLkKR4sXVHFjDbw75bYg02uQ8dFAB4,4792
+frontier_council-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+frontier_council-0.1.0.dist-info/entry_points.txt,sha256=I3xjPK-nupfQz5PANVXUnXjuxlP-4-mykkA3wXhFOGY,63
+frontier_council-0.1.0.dist-info/RECORD,,

frontier_council-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

frontier_council-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+frontier-council = frontier_council.cli:main