adversarial-workflow 0.6.6__py3-none-any.whl → 0.9.0__py3-none-any.whl

adversarial_workflow/__init__.py

@@ -12,7 +12,7 @@ Usage:
     adversarial validate "pytest"
 """
 
-__version__ = "0.6.6"
+__version__ = "0.9.0"
 __author__ = "Fredrik Matheson"
 __license__ = "MIT"
 

adversarial_workflow/cli.py

@@ -13,6 +13,7 @@ Commands:
     review - Run Phase 3: Code review
     validate - Run Phase 4: Test validation
     split - Split large task files into smaller evaluable chunks
+    check-citations - Verify URLs in documents before evaluation
 """
 
 import argparse
@@ -29,7 +30,7 @@ from typing import Dict, List, Optional, Tuple
 import yaml
 from dotenv import dotenv_values, load_dotenv
 
-__version__ = "0.6.6"
+__version__ = "0.9.0"
 
 # ANSI color codes for better output
 RESET = "\033[0m"
@@ -2819,6 +2820,106 @@ def list_evaluators() -> int:
     return 0
 
 
+def check_citations(
+    file_path: str,
+    output_tasks: Optional[str] = None,
+    mark_inline: bool = False,
+    concurrency: int = 10,
+    timeout: int = 10,
+) -> int:
+    """
+    Check citations (URLs) in a document.
+
+    Args:
+        file_path: Path to document to check
+        output_tasks: Optional path to write blocked URL tasks
+        mark_inline: Whether to mark URLs inline with status badges
+        concurrency: Maximum concurrent URL checks
+        timeout: Timeout per URL in seconds
+
+    Returns:
+        0 on success, 1 on error
+    """
+    from adversarial_workflow.utils.citations import (
+        URLStatus,
+        check_urls,
+        extract_urls,
+        generate_blocked_tasks,
+        mark_urls_inline,
+        print_verification_summary,
+    )
+
+    # Check file exists
+    if not os.path.exists(file_path):
+        print(f"{RED}Error: File not found: {file_path}{RESET}")
+        return 1
+
+    # Validate parameters
+    if concurrency < 1:
+        print(f"{RED}Error: Concurrency must be at least 1, got {concurrency}{RESET}")
+        return 1
+    if timeout < 1:
+        print(f"{RED}Error: Timeout must be at least 1 second, got {timeout}{RESET}")
+        return 1
+
+    print(f"🔗 Checking citations in: {file_path}")
+    print()
+
+    # Read document
+    with open(file_path, encoding="utf-8") as f:
+        document = f.read()
+
+    # Extract URLs
+    extracted = extract_urls(document)
+    urls = [e.url for e in extracted]
+
+    if not urls:
+        print(f"{YELLOW}No URLs found in document.{RESET}")
+        return 0
+
+    print(f"   Found {len(urls)} URLs to check")
+    print(f"   Checking with concurrency={concurrency}, timeout={timeout}s...")
+    print()
+
+    # Check URLs
+    results = check_urls(
+        urls,
+        concurrency=concurrency,
+        timeout=timeout,
+    )
+
+    # Print summary
+    print_verification_summary(results)
+
+    # Count blocked/broken
+    blocked_count = sum(1 for r in results if r.status in (URLStatus.BLOCKED, URLStatus.BROKEN))
+
+    # Mark document inline if requested
+    if mark_inline and results:
+        marked_document = mark_urls_inline(document, results)
+        if marked_document != document:
+            with open(file_path, "w", encoding="utf-8") as f:
+                f.write(marked_document)
+            print("\n   ✅ Updated document with status badges")
+
+    # Generate blocked tasks if requested or if there are blocked URLs
+    if blocked_count > 0:
+        if output_tasks:
+            output_path = Path(output_tasks)
+        else:
+            # Default to .adversarial/blocked-citations/
+            output_dir = Path.cwd() / ".adversarial" / "blocked-citations"
+            output_dir.mkdir(parents=True, exist_ok=True)
+            base_name = Path(file_path).stem
+            output_path = output_dir / f"{base_name}-blocked-urls.md"
+
+        task_content = generate_blocked_tasks(results, file_path, output_path)
+        if task_content:
+            print(f"   📋 Blocked URL tasks: {output_path}")
+
+    return 0
+
+
 def main():
     """Main CLI entry point."""
     import logging
@@ -2843,6 +2944,7 @@ def main():
 
     from adversarial_workflow.evaluators import (
         BUILTIN_EVALUATORS,
+        discover_local_evaluators,
         get_all_evaluators,
         run_evaluator,
     )
@@ -2858,10 +2960,12 @@ def main():
         "health",
         "quickstart",
         "agent",
+        "library",
         "split",
         "validate",
         "review",
         "list-evaluators",
+        "check-citations",
     }
 
     parser = argparse.ArgumentParser(
@@ -2879,6 +2983,9 @@ Examples:
   adversarial review                    # Review implementation
   adversarial validate "npm test"       # Validate with tests
   adversarial split large-task.md       # Split large files
+  adversarial check-citations doc.md    # Verify URLs in document
+  adversarial library list              # Browse available evaluators
+  adversarial library install google/gemini-flash  # Install evaluator
 
 For more information: https://github.com/movito/adversarial-workflow
         """,
@@ -2925,6 +3032,98 @@ For more information: https://github.com/movito/adversarial-workflow
         "--path", default=".", help="Project path (default: current directory)"
     )
 
+    # library command (with subcommands)
+    library_parser = subparsers.add_parser(
+        "library", help="Browse and install evaluators from the community library"
+    )
+    library_subparsers = library_parser.add_subparsers(
+        dest="library_subcommand", help="Library subcommand"
+    )
+
+    # library list subcommand
+    library_list_parser = library_subparsers.add_parser(
+        "list", help="List available evaluators from the library"
+    )
+    library_list_parser.add_argument(
+        "--provider", "-p", help="Filter by provider (e.g., google, openai)"
+    )
+    library_list_parser.add_argument(
+        "--category", "-c", help="Filter by category (e.g., quick-check, deep-reasoning)"
+    )
+    library_list_parser.add_argument(
+        "--verbose", "-v", action="store_true", help="Show detailed information"
+    )
+    library_list_parser.add_argument(
+        "--no-cache", action="store_true", help="Bypass cache and fetch fresh data"
+    )
+
+    # library info subcommand
+    library_info_parser = library_subparsers.add_parser(
+        "info", help="Show detailed information about an evaluator"
+    )
+    library_info_parser.add_argument(
+        "evaluator_spec", help="Evaluator to show info for (format: provider/name)"
+    )
+
+    # library install subcommand
+    library_install_parser = library_subparsers.add_parser(
+        "install", help="Install evaluator(s) from the library"
+    )
+    library_install_parser.add_argument(
+        "evaluators", nargs="*", help="Evaluator(s) to install (format: provider/name)"
+    )
+    library_install_parser.add_argument(
+        "--force", "-f", action="store_true", help="Overwrite existing files"
+    )
+    library_install_parser.add_argument(
+        "--skip-validation", action="store_true", help="Skip YAML validation (advanced)"
+    )
+    library_install_parser.add_argument(
+        "--dry-run", action="store_true", help="Preview without making changes"
+    )
+    library_install_parser.add_argument("--category", help="Install all evaluators in a category")
+    library_install_parser.add_argument(
+        "--yes", "-y", action="store_true", help="Skip confirmation prompts (required for CI/CD)"
+    )
+
+    # library check-updates subcommand
+    library_check_parser = library_subparsers.add_parser(
+        "check-updates", help="Check for updates to installed evaluators"
+    )
+    library_check_parser.add_argument(
+        "name", nargs="?", help="Specific evaluator to check (optional)"
+    )
+    library_check_parser.add_argument(
+        "--no-cache", action="store_true", help="Bypass cache and fetch fresh data"
+    )
+
+    # library update subcommand
+    library_update_parser = library_subparsers.add_parser(
+        "update", help="Update installed evaluator(s) to newer versions"
+    )
+    library_update_parser.add_argument("name", nargs="?", help="Evaluator name to update")
+    library_update_parser.add_argument(
+        "--all",
+        "-a",
+        action="store_true",
+        dest="all_evaluators",
+        help="Update all outdated evaluators",
+    )
+    library_update_parser.add_argument(
+        "--yes", "-y", action="store_true", help="Skip confirmation prompts"
+    )
+    library_update_parser.add_argument(
+        "--diff-only", action="store_true", help="Show diff without applying changes"
+    )
+    library_update_parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Preview without making changes (same as --diff-only)",
+    )
+    library_update_parser.add_argument(
+        "--no-cache", action="store_true", help="Bypass cache and fetch fresh data"
+    )
+
     # review command (static - reviews git changes, no file argument)
     subparsers.add_parser("review", help="Run Phase 3: Code review")
 
@@ -2961,6 +3160,38 @@ For more information: https://github.com/movito/adversarial-workflow
         help="List all available evaluators (built-in and local)",
     )
 
+    # check-citations command
+    citations_parser = subparsers.add_parser(
+        "check-citations",
+        help="Verify URLs in a document before evaluation",
+    )
+    citations_parser.add_argument("file", help="Document to check citations in")
+    citations_parser.add_argument(
+        "--output-tasks",
+        "-o",
+        help="Output file for blocked URL tasks (markdown)",
+    )
+    citations_parser.add_argument(
+        "--mark-inline",
+        action="store_true",
+        default=False,
+        help="Mark URLs inline with status badges (modifies document)",
+    )
+    citations_parser.add_argument(
+        "--concurrency",
+        "-c",
+        type=int,
+        default=10,
+        help="Maximum concurrent URL checks (default: 10)",
+    )
+    citations_parser.add_argument(
+        "--timeout",
+        "-t",
+        type=int,
+        default=10,
+        help="Timeout per URL in seconds (default: 10)",
+    )
+
     # Dynamic evaluator registration
     try:
         evaluators = get_all_evaluators()
@@ -3009,6 +3240,20 @@ For more information: https://github.com/movito/adversarial-workflow
             default=None,
             help="Timeout in seconds (default: from evaluator config or 180, max: 600)",
         )
+        eval_parser.add_argument(
+            "--check-citations",
+            action="store_true",
+            help="Verify URLs in document before evaluation",
+        )
+        # Add --evaluator flag for the "evaluate" command only
+        # This allows selecting a library-installed evaluator
+        if config.name == "evaluate":
+            eval_parser.add_argument(
+                "--evaluator",
+                "-e",
+                metavar="NAME",
+                help="Use a specific evaluator from .adversarial/evaluators/",
+            )
         # Store config for later execution
         eval_parser.set_defaults(evaluator_config=config)
 
@@ -3020,15 +3265,45 @@ For more information: https://github.com/movito/adversarial-workflow
 
     # Check for evaluator command first (has evaluator_config attribute)
     if hasattr(args, "evaluator_config"):
+        # Default to the command's evaluator config
+        config_to_use = args.evaluator_config
+
+        # Check if --evaluator flag was specified (only on evaluate command)
+        evaluator_override = getattr(args, "evaluator", None)
+        if evaluator_override:
+            local_evaluators = discover_local_evaluators()
+
+            if not local_evaluators:
+                print(f"{RED}Error: No evaluators installed.{RESET}")
+                print("Install evaluators with: adversarial library install <name>")
+                return 1
+
+            if evaluator_override not in local_evaluators:
+                print(f"{RED}Error: Evaluator '{evaluator_override}' not found.{RESET}")
+                print()
+                print("Available evaluators:")
+                # Show unique evaluators (avoid duplicates from aliases)
+                seen = set()
+                for _, cfg in sorted(local_evaluators.items()):
+                    if id(cfg) not in seen:
+                        print(f"  {cfg.name}")
+                        if cfg.aliases:
+                            print(f"    aliases: {', '.join(cfg.aliases)}")
+                        seen.add(id(cfg))
+                return 1
+
+            config_to_use = local_evaluators[evaluator_override]
+            print(f"Using evaluator: {config_to_use.name}")
+
         # Determine timeout: CLI flag > YAML config > default (180s)
         if args.timeout is not None:
             timeout = args.timeout
             source = "CLI override"
-        elif args.evaluator_config.timeout != 180:
-            timeout = args.evaluator_config.timeout
+        elif config_to_use.timeout != 180:
+            timeout = config_to_use.timeout
             source = "evaluator config"
         else:
-            timeout = args.evaluator_config.timeout  # 180 (default)
+            timeout = config_to_use.timeout  # 180 (default)
             source = "default"
 
         # Validate CLI timeout (consistent with YAML validation)
@@ -3044,8 +3319,18 @@ For more information: https://github.com/movito/adversarial-workflow
         # Log actual timeout and source
         print(f"Using timeout: {timeout}s ({source})")
 
+        # Check citations first if requested (read-only, doesn't modify file)
+        if getattr(args, "check_citations", False):
+            print()
+            result = check_citations(args.file, mark_inline=False)
+            if result != 0:
+                print(
+                    f"{YELLOW}Warning: Citation check had issues, continuing with evaluation...{RESET}"
+                )
+            print()
+
         return run_evaluator(
-            args.evaluator_config,
+            config_to_use,
             args.file,
             timeout=timeout,
         )
@@ -3070,6 +3355,59 @@ For more information: https://github.com/movito/adversarial-workflow
             print(f"{RED}Error: agent command requires a subcommand{RESET}")
             print("Usage: adversarial agent onboard")
             return 1
+    elif args.command == "library":
+        from adversarial_workflow.library import (
+            library_check_updates,
+            library_info,
+            library_install,
+            library_list,
+            library_update,
+        )
+
+        if args.library_subcommand == "list":
+            return library_list(
+                provider=args.provider,
+                category=args.category,
+                verbose=args.verbose,
+                no_cache=args.no_cache,
+            )
+        elif args.library_subcommand == "info":
+            return library_info(
+                evaluator_spec=args.evaluator_spec,
+            )
+        elif args.library_subcommand == "install":
+            return library_install(
+                evaluator_specs=args.evaluators,
+                force=args.force,
+                skip_validation=args.skip_validation,
+                dry_run=args.dry_run,
+                category=args.category,
+                yes=args.yes,
+            )
+        elif args.library_subcommand == "check-updates":
+            return library_check_updates(
+                name=args.name,
+                no_cache=args.no_cache,
+            )
+        elif args.library_subcommand == "update":
+            return library_update(
+                name=args.name,
+                all_evaluators=args.all_evaluators,
+                yes=args.yes,
+                diff_only=args.diff_only,
+                no_cache=args.no_cache,
+                dry_run=args.dry_run,
+            )
+        else:
+            # No subcommand provided
+            print(f"{RED}Error: library command requires a subcommand{RESET}")
+            print("Usage:")
+            print("  adversarial library list")
+            print("  adversarial library info <provider>/<name>")
+            print("  adversarial library install <provider>/<name>")
+            print("  adversarial library check-updates")
+            print("  adversarial library update <name>")
+            return 1
     elif args.command == "review":
         return review()
     elif args.command == "validate":
@@ -3083,6 +3421,14 @@ For more information: https://github.com/movito/adversarial-workflow
         )
     elif args.command == "list-evaluators":
         return list_evaluators()
+    elif args.command == "check-citations":
+        return check_citations(
+            args.file,
+            output_tasks=args.output_tasks,
+            mark_inline=args.mark_inline,
+            concurrency=args.concurrency,
+            timeout=args.timeout,
+        )
     else:
         parser.print_help()
         return 1

adversarial_workflow/evaluators/__init__.py

@@ -1,12 +1,18 @@
-"""Evaluators module for adversarial-workflow plugin architecture."""
+"""Evaluators module for adversarial-workflow plugin architecture.
+
+Supports dual-field model specification (ADV-0015):
+- Legacy: model + api_key_env fields (backwards compatible)
+- New: model_requirement field (resolved via ModelResolver)
+"""
 
 from .builtins import BUILTIN_EVALUATORS
-from .config import EvaluatorConfig
+from .config import EvaluatorConfig, ModelRequirement
 from .discovery import (
     EvaluatorParseError,
     discover_local_evaluators,
     parse_evaluator_yaml,
 )
+from .resolver import ModelResolver, ResolutionError
 from .runner import run_evaluator
 
 
@@ -38,6 +44,9 @@ def get_all_evaluators() -> dict[str, EvaluatorConfig]:
 __all__ = [
     "EvaluatorConfig",
     "EvaluatorParseError",
+    "ModelRequirement",
+    "ModelResolver",
+    "ResolutionError",
     "run_evaluator",
     "get_all_evaluators",
     "discover_local_evaluators",

adversarial_workflow/evaluators/config.py

@@ -1,5 +1,9 @@
 """
 EvaluatorConfig dataclass for evaluator definitions.
+
+Supports dual-field model specification (ADV-0015):
+- Legacy: model + api_key_env fields (backwards compatible)
+- New: model_requirement field (structured capability requirements)
 """
 
 from __future__ import annotations
@@ -7,6 +11,27 @@ from __future__ import annotations
 from dataclasses import dataclass, field
 
 
+@dataclass
+class ModelRequirement:
+    """Model capability requirements (from library).
+
+    This dataclass represents structured model requirements that can be
+    resolved to actual model IDs via the ModelResolver. It separates
+    WHAT capability is needed from HOW to access it.
+
+    Attributes:
+        family: Model family (e.g., "claude", "gpt", "o", "gemini", "mistral", "codestral", "llama")
+        tier: Performance tier (e.g., "opus", "sonnet", "haiku", "flagship", "mini", "latest")
+        min_version: Optional minimum model generation (e.g., "4" for Claude 4+)
+        min_context: Optional minimum context window in tokens (e.g., 128000)
+    """
+
+    family: str
+    tier: str
+    min_version: str = ""
+    min_context: int = 0
+
+
 @dataclass
 class EvaluatorConfig:
     """Configuration for an evaluator (built-in or custom).
@@ -15,11 +40,18 @@ class EvaluatorConfig:
     whether built-in (evaluate, proofread, review) or custom
     (defined in .adversarial/evaluators/*.yml).
 
+    Supports dual-field model specification (ADV-0015):
+    - Legacy: model + api_key_env fields (always backwards compatible)
+    - New: model_requirement field (resolved via ModelResolver)
+
+    When both are present, model_requirement takes precedence. If resolution
+    fails, falls back to legacy model field with a warning.
+
     Attributes:
         name: Command name (e.g., "evaluate", "athena")
         description: Help text shown in CLI
-        model: Model to use (e.g., "gpt-4o", "gemini-2.5-pro")
-        api_key_env: Environment variable name for API key
+        model: Model to use (e.g., "gpt-4o", "gemini-2.5-pro") - legacy field
+        api_key_env: Environment variable name for API key - legacy field
         prompt: The evaluation prompt template
         output_suffix: Log file suffix (e.g., "PLAN-EVALUATION")
         log_prefix: CLI output prefix (e.g., "ATHENA")
@@ -27,6 +59,7 @@ class EvaluatorConfig:
         aliases: Alternative command names
         version: Evaluator version
         timeout: Timeout in seconds (default: 180, max: 600)
+        model_requirement: Structured model requirement (resolved via ModelResolver)
         source: "builtin" or "local" (set internally)
         config_file: Path to YAML file if local (set internally)
     """
@@ -46,6 +79,10 @@ class EvaluatorConfig:
     version: str = "1.0.0"
     timeout: int = 180  # Timeout in seconds (default: 180, max: 600)
 
+    # NEW: Structured model requirement (Phase 1 - ADV-0015)
+    # When present, resolved via ModelResolver to actual model ID
+    model_requirement: ModelRequirement | None = None
+
     # Metadata (set internally during discovery, not from YAML)
     source: str = "builtin"
     config_file: str | None = None