extropy-run 0.2.2__py3-none-any.whl

extropy/__init__.py

@@ -0,0 +1,3 @@
+"""Extropy: Simulate how populations respond to scenarios."""
+
+__version__ = "0.2.2"

extropy/cli/__init__.py

@@ -0,0 +1,23 @@
+"""CLI package for Extropy.
+
+Supports dual-mode output:
+- Human mode (default): Rich formatting with colors, tables, progress bars
+- Machine mode (--json): Structured JSON output for AI coding tools
+
+Exit codes:
+    0 = Success
+    1 = Validation error
+    2 = File not found
+    3 = Sampling error
+    4 = Network error
+    5 = Simulation error
+    6 = Scenario error
+    10 = User cancelled
+"""
+
+from .app import app
+
+# Import commands to register them with the app
+from . import commands  # noqa: F401
+
+__all__ = ["app"]

extropy/cli/app.py

@@ -0,0 +1,74 @@
+"""Core CLI app definition and global state."""
+
+from typing import Annotated
+
+import typer
+from rich.console import Console
+
+app = typer.Typer(
+    name="extropy",
+    help="Generate population specs for agent-based simulation.",
+    no_args_is_help=True,
+)
+
+console = Console()
+
+# Global state for JSON mode (set by callback)
+_json_mode = False
+
+
+def get_json_mode() -> bool:
+    """Get current JSON mode state."""
+    return _json_mode
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        from .. import __version__
+
+        print(f"extropy {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main_callback(
+    json_output: Annotated[
+        bool,
+        typer.Option(
+            "--json",
+            help="Output machine-readable JSON instead of human-friendly text",
+            is_eager=True,
+        ),
+    ] = False,
+    version: Annotated[
+        bool,
+        typer.Option(
+            "--version",
+            help="Show version and exit",
+            callback=_version_callback,
+            is_eager=True,
+        ),
+    ] = False,
+):
+    """Extropy: Population simulation engine for agent-based modeling.
+
+    Use --json for machine-readable output suitable for scripting and AI tools.
+    """
+    global _json_mode
+    _json_mode = json_output
+
+
+# Import commands to register them with the app
+from .commands import (  # noqa: E402, F401
+    validate,
+    extend,
+    spec,
+    sample,
+    network,
+    persona,
+    scenario,
+    simulate,
+    estimate,
+    results,
+    config_cmd,
+)

extropy/cli/commands/__init__.py

@@ -0,0 +1,29 @@
+"""CLI commands for Extropy."""
+
+from . import (
+    validate,
+    extend,
+    spec,
+    sample,
+    network,
+    persona,
+    scenario,
+    simulate,
+    estimate,
+    results,
+    config_cmd,
+)
+
+__all__ = [
+    "validate",
+    "extend",
+    "spec",
+    "sample",
+    "network",
+    "persona",
+    "scenario",
+    "simulate",
+    "estimate",
+    "results",
+    "config_cmd",
+]

extropy/cli/commands/config_cmd.py

@@ -0,0 +1,210 @@
+"""Config command for viewing and managing extropy configuration."""
+
+import typer
+
+from ..app import app, console
+from ...config import (
+    get_config,
+    reset_config,
+    CONFIG_FILE,
+    get_api_key,
+    get_azure_config,
+)
+
+
+VALID_KEYS = {
+    "pipeline.provider",
+    "pipeline.model_simple",
+    "pipeline.model_reasoning",
+    "pipeline.model_research",
+    "simulation.provider",
+    "simulation.model",
+    "simulation.pivotal_model",
+    "simulation.routine_model",
+    "simulation.max_concurrent",
+    "simulation.rate_tier",
+    "simulation.rpm_override",
+    "simulation.tpm_override",
+    "simulation.api_format",
+}
+
+INT_FIELDS = {"max_concurrent", "rate_tier", "rpm_override", "tpm_override"}
+
+
+@app.command("config")
+def config_command(
+    action: str = typer.Argument(
+        ...,
+        help="Action: show, set, reset",
+    ),
+    key: str | None = typer.Argument(
+        None,
+        help="Config key (e.g. pipeline.provider, simulation.model)",
+    ),
+    value: str | None = typer.Argument(
+        None,
+        help="Value to set",
+    ),
+):
+    """View or modify extropy configuration.
+
+    Examples:
+        extropy config show
+        extropy config set pipeline.provider claude
+        extropy config set simulation.provider openai
+        extropy config set simulation.model gpt-5-mini
+        extropy config reset
+    """
+    if action == "show":
+        _show_config()
+    elif action == "set":
+        if not key or value is None:
+            console.print("[red]Usage:[/red] extropy config set <key> <value>")
+            console.print()
+            console.print("Available keys:")
+            for k in sorted(VALID_KEYS):
+                console.print(f"  {k}")
+            raise typer.Exit(1)
+        _set_config(key, value)
+    elif action == "reset":
+        _reset_config()
+    else:
+        console.print(f"[red]Unknown action:[/red] {action}")
+        console.print("Valid actions: show, set, reset")
+        raise typer.Exit(1)
+
+
+def _show_config():
+    """Display current resolved configuration."""
+    config = get_config()
+
+    console.print()
+    console.print("[bold]Extropy Configuration[/bold]")
+    console.print("─" * 40)
+
+    # Pipeline zone
+    console.print()
+    console.print("[bold cyan]Pipeline[/bold cyan] (spec, extend, persona, scenario)")
+    console.print(f"  provider        = {config.pipeline.provider}")
+    console.print(
+        f"  model_simple    = {config.pipeline.model_simple or '[dim](provider default)[/dim]'}"
+    )
+    console.print(
+        f"  model_reasoning = {config.pipeline.model_reasoning or '[dim](provider default)[/dim]'}"
+    )
+    console.print(
+        f"  model_research  = {config.pipeline.model_research or '[dim](provider default)[/dim]'}"
+    )
+
+    # Simulation zone
+    console.print()
+    console.print("[bold cyan]Simulation[/bold cyan] (agent reasoning)")
+    console.print(f"  provider        = {config.simulation.provider}")
+    console.print(
+        f"  model           = {config.simulation.model or '[dim](provider default)[/dim]'}"
+    )
+    console.print(
+        f"  pivotal_model   = {config.simulation.pivotal_model or '[dim](same as model)[/dim]'}"
+    )
+    console.print(
+        f"  routine_model   = {config.simulation.routine_model or '[dim](provider default)[/dim]'}"
+    )
+    console.print(
+        f"  api_format      = {config.simulation.api_format or '[dim](auto)[/dim]'}"
+    )
+    console.print(f"  max_concurrent  = {config.simulation.max_concurrent}")
+    console.print(
+        f"  rate_tier       = {config.simulation.rate_tier or '[dim](tier 1)[/dim]'}"
+    )
+    if config.simulation.rpm_override:
+        console.print(f"  rpm_override    = {config.simulation.rpm_override}")
+    if config.simulation.tpm_override:
+        console.print(f"  tpm_override    = {config.simulation.tpm_override}")
+
+    # API keys status
+    console.print()
+    console.print("[bold cyan]API Keys[/bold cyan] (from env vars)")
+    _show_key_status("openai", "OPENAI_API_KEY")
+    _show_key_status("claude", "ANTHROPIC_API_KEY")
+    _show_key_status("azure_openai", "AZURE_OPENAI_API_KEY")
+
+    # Azure-specific config (show when Azure provider is in use)
+    active_providers = {config.pipeline.provider, config.simulation.provider}
+    if "azure_openai" in active_providers:
+        azure_cfg = get_azure_config("azure_openai")
+        console.print()
+        console.print("[bold cyan]Azure OpenAI[/bold cyan]")
+        console.print(
+            f"  endpoint          = {azure_cfg['azure_endpoint'] or '[dim]not set[/dim]'}"
+        )
+        console.print(f"  api_version       = {azure_cfg['api_version']}")
+        if azure_cfg["azure_deployment"]:
+            console.print(f"  deployment        = {azure_cfg['azure_deployment']}")
+
+    # Config file
+    console.print()
+    if CONFIG_FILE.exists():
+        console.print(f"Config file: {CONFIG_FILE}")
+    else:
+        console.print(f"Config file: [dim]not created yet[/dim] ({CONFIG_FILE})")
+    console.print()
+
+
+def _show_key_status(provider: str, env_var_label: str):
+    """Show whether an API key is configured."""
+    key = get_api_key(provider)
+    if key:
+        masked = key[:8] + "..." + key[-4:] if len(key) > 16 else "***"
+        console.print(f"  {env_var_label}: [green]{masked}[/green]")
+    else:
+        console.print(f"  {env_var_label}: [dim]not set[/dim]")
+
+
+def _set_config(key: str, value: str):
+    """Set a config value and save."""
+    if key not in VALID_KEYS:
+        console.print(f"[red]Unknown key:[/red] {key}")
+        console.print()
+        console.print("Available keys:")
+        for k in sorted(VALID_KEYS):
+            console.print(f"  {k}")
+        raise typer.Exit(1)
+
+    # Load current config (or defaults if no file)
+    config = get_config()
+
+    zone, field = key.split(".", 1)
+    if zone == "pipeline":
+        target = config.pipeline
+    elif zone == "simulation":
+        target = config.simulation
+    else:
+        console.print(f"[red]Unknown zone:[/red] {zone}")
+        raise typer.Exit(1)
+
+    # Type coercion
+    if field in INT_FIELDS:
+        try:
+            setattr(target, field, int(value))
+        except ValueError:
+            console.print(f"[red]Invalid integer value:[/red] {value}")
+            raise typer.Exit(1)
+    else:
+        setattr(target, field, value)
+
+    config.save()
+    reset_config()  # Clear cached singleton so next get_config() reloads
+
+    console.print(f"[green]✓[/green] Set {key} = {value}")
+    console.print(f"  Saved to {CONFIG_FILE}")
+
+
+def _reset_config():
+    """Reset config to defaults."""
+    if CONFIG_FILE.exists():
+        CONFIG_FILE.unlink()
+        reset_config()
+        console.print("[green]✓[/green] Config reset to defaults")
+        console.print(f"  Removed {CONFIG_FILE}")
+    else:
+        console.print("Config already at defaults (no config file exists)")

extropy/cli/commands/estimate.py

@@ -0,0 +1,216 @@
+"""Estimate command for predicting simulation costs before running."""
+
+import json
+from pathlib import Path
+
+import typer
+
+from ..app import app, console
+
+
+@app.command("estimate")
+def estimate_command(
+    scenario_file: Path = typer.Argument(..., help="Scenario spec YAML file"),
+    model: str = typer.Option(
+        "",
+        "--model",
+        "-m",
+        help="LLM model for agent reasoning (empty = use config default)",
+    ),
+    pivotal_model: str = typer.Option(
+        "",
+        "--pivotal-model",
+        help="Model for pivotal/first-pass reasoning (default: same as --model)",
+    ),
+    routine_model: str = typer.Option(
+        "",
+        "--routine-model",
+        help="Cheap model for classification pass (default: provider cheap tier)",
+    ),
+    threshold: int = typer.Option(
+        3, "--threshold", "-t", help="Multi-touch threshold for re-reasoning"
+    ),
+    verbose: bool = typer.Option(
+        False, "--verbose", "-v", help="Show per-timestep breakdown"
+    ),
+):
+    """
+    Estimate simulation cost without running it.
+
+    Loads the scenario and population files, runs a simplified propagation
+    model, and predicts LLM calls, tokens, and USD cost. No API keys required.
+
+    Example:
+        extropy estimate scenario.yaml
+        extropy estimate scenario.yaml --model gpt-5-mini
+        extropy estimate scenario.yaml --pivotal-model gpt-5 --routine-model gpt-5-mini -v
+    """
+    from ...config import get_config
+    from ...core.models import ScenarioSpec, PopulationSpec
+    from ...population.network import load_agents_json
+    from ...simulation.estimator import estimate_simulation_cost
+
+    # Validate input file
+    if not scenario_file.exists():
+        console.print(f"[red]x[/red] Scenario file not found: {scenario_file}")
+        raise typer.Exit(1)
+
+    # Load scenario
+    try:
+        scenario = ScenarioSpec.from_yaml(scenario_file)
+    except Exception as e:
+        console.print(f"[red]x[/red] Failed to load scenario: {e}")
+        raise typer.Exit(1)
+
+    # Load population spec
+    pop_path = Path(scenario.meta.population_spec)
+    if not pop_path.is_absolute():
+        pop_path = scenario_file.parent / pop_path
+    if not pop_path.exists():
+        console.print(f"[red]x[/red] Population spec not found: {pop_path}")
+        raise typer.Exit(1)
+    population_spec = PopulationSpec.from_yaml(pop_path)
+
+    # Load agents
+    agents_path = Path(scenario.meta.agents_file)
+    if not agents_path.is_absolute():
+        agents_path = scenario_file.parent / agents_path
+    if not agents_path.exists():
+        console.print(f"[red]x[/red] Agents file not found: {agents_path}")
+        raise typer.Exit(1)
+    agents = load_agents_json(agents_path)
+
+    # Load network
+    network_path = Path(scenario.meta.network_file)
+    if not network_path.is_absolute():
+        network_path = scenario_file.parent / network_path
+    if not network_path.exists():
+        console.print(f"[red]x[/red] Network file not found: {network_path}")
+        raise typer.Exit(1)
+    with open(network_path) as f:
+        network = json.load(f)
+
+    # Resolve config
+    config = get_config()
+    provider = config.simulation.provider
+
+    eff_model = model or config.simulation.model
+    eff_pivotal = pivotal_model or config.simulation.pivotal_model or eff_model
+    eff_routine = routine_model or config.simulation.routine_model
+
+    # Run estimation
+    est = estimate_simulation_cost(
+        scenario=scenario,
+        population_spec=population_spec,
+        agents=agents,
+        network=network,
+        provider=provider,
+        pivotal_model=eff_pivotal,
+        routine_model=eff_routine,
+        multi_touch_threshold=threshold,
+    )
+
+    # Display results
+    console.print()
+    console.print("[bold]Simulation Cost Estimate[/bold]")
+    console.print()
+
+    early_stop = (
+        f" (early stop at ~{est.per_timestep[-1]['exposure_rate']:.0%} exposure)"
+        if est.effective_timesteps < est.max_timesteps and est.per_timestep
+        else ""
+    )
+    console.print(
+        f"Population: {est.population_size} agents | "
+        f"Avg degree: {est.avg_degree:.1f} | "
+        f"Max timesteps: {est.max_timesteps}"
+    )
+    console.print(f"Effective timesteps: ~{est.effective_timesteps}{early_stop}")
+    console.print()
+
+    # Models section
+    console.print("[bold]Models[/bold]")
+    _print_model_line(
+        console, "Pass 1 (pivotal)", est.pivotal_model, est.pivotal_pricing
+    )
+    _print_model_line(
+        console, "Pass 2 (routine)", est.routine_model, est.routine_pricing
+    )
+    console.print()
+
+    # Calls table
+    console.print("[bold]Estimated LLM Calls[/bold]")
+    console.print(
+        f"  {'':16s} {'Calls':>8s}   {'Input Tok':>12s}   {'Output Tok':>12s}"
+    )
+    console.print(
+        f"  {'Pass 1':16s} {est.pass1_calls:>8,}   "
+        f"{'~' + f'{est.pass1_input_tokens:,}':>12s}   "
+        f"{'~' + f'{est.pass1_output_tokens:,}':>12s}"
+    )
+    console.print(
+        f"  {'Pass 2':16s} {est.pass2_calls:>8,}   "
+        f"{'~' + f'{est.pass2_input_tokens:,}':>12s}   "
+        f"{'~' + f'{est.pass2_output_tokens:,}':>12s}"
+    )
+    total_input = est.pass1_input_tokens + est.pass2_input_tokens
+    total_output = est.pass1_output_tokens + est.pass2_output_tokens
+    console.print(
+        f"  {'Total':16s} {est.pass1_calls + est.pass2_calls:>8,}   "
+        f"{'~' + f'{total_input:,}':>12s}   "
+        f"{'~' + f'{total_output:,}':>12s}"
+    )
+    console.print()
+
+    # Cost section
+    console.print("[bold]Estimated Cost[/bold]")
+    if est.pass1_cost is not None:
+        console.print(f"  Pass 1:  ${est.pass1_cost:.2f}")
+    else:
+        console.print(
+            f"  Pass 1:  [dim]pricing not available for {est.pivotal_model}[/dim]"
+        )
+
+    if est.pass2_cost is not None:
+        console.print(f"  Pass 2:  ${est.pass2_cost:.2f}")
+    else:
+        console.print(
+            f"  Pass 2:  [dim]pricing not available for {est.routine_model}[/dim]"
+        )
+
+    if est.total_cost is not None:
+        console.print(f"  [bold]Total:   ${est.total_cost:.2f}[/bold]")
+    console.print()
+
+    console.print(
+        "[dim]Estimates are approximate. Actual costs vary with prompt length "
+        "and simulation dynamics.[/dim]"
+    )
+
+    # Verbose per-timestep breakdown
+    if verbose and est.per_timestep:
+        console.print()
+        console.print("[bold]Per-Timestep Breakdown[/bold]")
+        console.print(
+            f"  {'Step':>6s}   {'Exposure':>9s}   {'New Exp':>8s}   {'Reasoning':>10s}"
+        )
+        for row in est.per_timestep:
+            if row["new_exposures"] > 0 or row["reasoning_calls"] > 0:
+                console.print(
+                    f"  {row['timestep']:>6d}   "
+                    f"{row['exposure_rate']:>8.1%}   "
+                    f"{row['new_exposures']:>8d}   "
+                    f"{row['reasoning_calls']:>10d}"
+                )
+    console.print()
+
+
+def _print_model_line(console, label: str, model: str, pricing):
+    """Print a model info line with optional pricing."""
+    if pricing:
+        console.print(
+            f"  {label}:  {model}  "
+            f"(${pricing.input_per_mtok:.2f} / ${pricing.output_per_mtok:.2f} per MTok in/out)"
+        )
+    else:
+        console.print(f"  {label}:  {model}  [dim](pricing not available)[/dim]")