Buckets:

download
raw
43.2 kB
""" effGen CLI - Command-line interface for the effGen framework. This module provides a comprehensive CLI for interacting with effGen: - Run agents with tasks (with interactive wizard support) - Interactive chat mode - API server mode - Configuration management - Tool listing and testing - Model management - Example runner Usage: # Direct task execution effgen run "What is 2+2?" --model Qwen/Qwen2.5-1.5B-Instruct # Interactive wizard (launches when no task provided) effgen run effgen # Same as above # effgen-agent command (similar to smolagent) effgen-agent "Plan a trip to Tokyo" --model Qwen/Qwen2.5-1.5B-Instruct --tools web_search effgen-agent # Interactive mode # Chat mode effgen chat --model Qwen/Qwen2.5-3B-Instruct # Other commands effgen serve --port 8000 effgen config show effgen tools list effgen models list effgen examples run basic_agent Interactive mode guides you through: - Agent type selection (CodeAgent vs ToolCallingAgent vs ReActAgent) - Tool selection from available toolbox - Model configuration (type, ID, API settings) - Advanced options (temperature, max iterations, etc.) - Task prompt input """ from __future__ import annotations import argparse import asyncio # noqa: F401 - module attribute for command modules that import it from here import importlib.util # noqa: F401 - module attribute for command modules import json # noqa: F401 - module attribute for command modules import logging import os import sys from datetime import datetime # noqa: F401 - module attribute for command modules from pathlib import Path from typing import Any # Rich terminal output (fallback to basic if not available) try: from rich import print as rprint # noqa: F401 from rich.console import Console from rich.layout import Layout # noqa: F401 from rich.live import Live # noqa: F401 from rich.markdown import Markdown # noqa: F401 - module attribute for command modules from rich.panel import Panel # noqa: F401 - module attribute for command modules from rich.progress import Progress, SpinnerColumn, TextColumn # noqa: F401 - module attrs from rich.syntax import Syntax # noqa: F401 - availability shim / module attribute from rich.table import Table # noqa: F401 - module attribute for command modules RICH_AVAILABLE = True except ImportError: RICH_AVAILABLE = False Console = None # Import effGen components try: from effgen import ( # noqa: F401 Agent, AgentConfig, ConfigLoader, __version__, get_tool_registry, load_model, ) from effgen.core.agent import AgentMode # noqa: F401 - read as a module attribute except ImportError: print("Error: effGen package not found. Please install it first.") sys.exit(1) # .env discovery + loading is shared with the library-facing ``effgen.load_env()`` # so the CLI and a script/notebook resolve keys the same way. These aliases keep # the historical CLI-internal names (used by tests and callers) working. from effgen._env import dotenv_disabled as _dotenv_disabled # noqa: F401 - re-export from effgen._env import env_search_paths as _env_search_paths # noqa: F401 - re-export from effgen._env import load_env as load_env_files # Branded bare-command landing (TTY-only; falls through to the wizard otherwise). from effgen.cli import landing as _landing # Tips, first-run welcome, "did you mean?" and teaching-error helpers. from effgen.cli import onboarding as _onboarding # Live status / progress presentation (TTY-aware; degrades to plain text). from effgen.cli import progress as _progress # noqa: F401 - module attribute # The methods ``CLIInterface`` prints through. Mixed into the class below so a # caller keeps reaching them as ``CLIInterface.print`` / ``.print_error`` / …. from effgen.cli._console import CLIConsoleMixin # Logging setup and the echoed-error console filter, re-exported so # ``effgen.cli._main.setup_logging`` keeps resolving. from effgen.cli._logging import ( # noqa: F401 - re-export _SELF_RENDERING_ERROR_COMMANDS, _CLIEchoedErrorFilter, _suppress_echoed_error_logs, setup_logging, ) # Helpers shared by several commands. They live in ``effgen.cli.commands._shared`` # and are re-exported here so ``effgen.cli._main`` stays the import path callers # and tests use. from effgen.cli.commands._shared import ( # noqa: F401 - re-export _QUICKSTART_CLOUD_MODELS, _QUICKSTART_LOCAL_MODEL, _RUN_CONFIG_APPLIED_KEYS, KNOWN_PROVIDERS, PROVIDER_ALIASES, _checkpoint_run_kwargs, _invoked_command, _preflight_model_hint, _print_group_help, _quickstart_suggest_model, _warn_unapplied_config_keys, filter_incompatible_tools, resolve_provider_name, ) # The ``batch`` command. Imported at module scope so the handler is an attribute # of this module as soon as it finishes importing. from effgen.cli.commands.batch import ( # noqa: F401 - re-export _batch_structured_kwargs, _handle_batch_command, _read_done_indices, ) # The ``compare`` command handler and its per-metric terminal tables. # Module-level free functions; imported at module scope + re-exported (tests # reach ``_main._handle_compare_command`` / ``_render_comparison_tables``). from effgen.cli.commands.compare import ( # noqa: F401 - re-export _handle_compare_command, _render_comparison_tables, ) # The ``cost`` command handler (spend dashboard + budget). Imported at module # scope + re-exported; ``effgen.cli.__init__`` re-exports it from here, so # ``from effgen.cli import _handle_cost_command`` keeps resolving. from effgen.cli.commands.cost import _handle_cost_command # noqa: F401 - re-export # The ``doctor`` command handler and its report builders. Imported at module # scope + re-exported: ``effgen chat`` and ``effgen code``'s ``/doctor`` import # ``_handle_doctor_command`` from here at call time, and the report builders are # read back through this module so replacing one changes what doctor renders. from effgen.cli.commands.doctor import ( # noqa: F401 - re-export _doctor_code_report, _doctor_exit_code, _doctor_live_probe, _doctor_reliability_report, _doctor_system_report, _env_template_hint, _handle_doctor_command, ) # The ``eval`` command handler plus ``--suite`` resolution. Module-level free # functions taking ``(args, cli)``; imported at module scope + re-exported (tests # reach ``_main._handle_eval_command`` / ``_resolve_eval_suite``). from effgen.cli.commands.eval import ( # noqa: F401 - re-export _handle_eval_command, _resolve_eval_suite, ) # The ``create-plugin`` scaffold generator and its template renderer. Imported # at module scope + re-exported (tests reach ``_main._create_plugin_scaffold``). from effgen.cli.commands.plugin import ( # noqa: F401 - re-export _create_plugin_scaffold, _render_plugin_template, ) # The ``prompts`` command handler. Imported at module scope + re-exported; # ``effgen.cli.__init__`` re-exports it from here, so # ``from effgen.cli import _handle_prompts_command`` keeps resolving. from effgen.cli.commands.prompts import _handle_prompts_command # noqa: F401 - re-export # The ``quickstart``/``tutorial`` guided run, its project scaffold and its # coding step. Imported at module scope + re-exported; the scaffold and the # coding step are called back through this module so replacing either here # changes what the guided run does. from effgen.cli.commands.quickstart import ( # noqa: F401 - re-export _QUICKSTART_CODE_TASK, _handle_quickstart_command, _quickstart_code_step, _quickstart_code_wanted, _quickstart_init_step, ) # The ``report`` command handler and the ``-o``/``--report`` artifact writers # shared by ``eval``/``compare``/``cost``. Imported at module scope so the names # are attributes of this module (tests reach ``_main._artifact_format`` / # ``_write_result_artifact`` and the ``eval``/``compare``/``cost`` handlers call # the bare names). from effgen.cli.commands.report import ( # noqa: F401 - re-export _artifact_format, _handle_report_command, _write_html_report_arg, _write_result_artifact, ) # The ``resume`` command handler (continue a run from a checkpoint snapshot). # Imported at module scope + re-exported. from effgen.cli.commands.resume import _handle_resume_command # noqa: F401 - re-export # The ``serve`` command launcher and its ``/run``, ``/tools``, ``/``, ``/slo``, # ``/ws`` convenience routes. ``CLIInterface.serve_api`` / # ``._register_convenience_routes`` delegate there. The request models, # ``WebSocket`` type, and default-tool helper are re-exported so FastAPI's # annotation resolution and any ``_main.TaskRequest``/``_main.WebSocket`` # reference keep working (the models must live in the handler's own module). from effgen.cli.commands.serve import ( # noqa: F401 - re-export TaskRequest, TaskResponse, WebSocket, _general_purpose_tool_names, _PydanticBaseModel, _PydanticConfigDict, ) # The ``sessions`` and ``runs`` command handlers plus their formatting helpers. # Module-level free functions taking ``(args, cli)``; imported at module scope so # every name is an attribute of this module as soon as it finishes importing # (tests reach them as ``_main._handle_sessions_command`` / ``_main._fmt_cost``). from effgen.cli.commands.sessions import ( # noqa: F401 - re-export _browse_sessions, _fmt_cost, _handle_runs_command, _handle_sessions_command, _one_line, _render_session, _session_matches, _short_ts, ) # The ``workflow`` command handler. A module-level free function taking # ``(args, cli)``; imported at module scope so it is an attribute of this module # as soon as it finishes importing (tests reach it as ``_main._handle_workflow_command``). from effgen.cli.commands.workflow import ( # noqa: F401 - re-export _handle_workflow_command, ) from effgen.ui.palette import glyph as _glyph # noqa: F401 - module attribute # JSON written to a stream that cannot encode it is escaped, not transliterated. from effgen.ui.render import json_ensure_ascii # noqa: F401 - module attribute # Shared Rich theme + console factory (one palette across the whole CLI). # ``console_is_interactive``/``render_table`` are re-exported so callers and # tests keep reaching them as ``effgen.cli._main`` attributes. from effgen.ui.tables import ( # noqa: F401 - re-export console_is_interactive, render_table, ) from effgen.ui.theme import CODE_THEME # noqa: F401 - module attribute for command modules from effgen.ui.theme import get_console as _get_console logger = logging.getLogger(__name__) class CLIInterface(CLIConsoleMixin): """Main CLI interface for effGen.""" def __init__(self) -> None: """Initialize CLI interface.""" self.console = _get_console() if RICH_AVAILABLE else None self.config_loader = ConfigLoader() self.tool_registry = get_tool_registry() # When True, all human-facing chatter is routed to stderr so stdout # carries only machine-readable output (e.g. `effgen run --json`). A # stderr-bound rich console is created lazily on first use. self._human_to_stderr = False self._err_console = None def interactive_wizard(self, args: Any) -> int | None: """ Interactive setup wizard for configuring and running agents. Similar to smolagents CLI, guides users through: - Agent type selection - Tool selection from available toolbox - Model configuration (type, ID, API settings) - Advanced options like additional imports - Task prompt input Args: args: Parsed command-line arguments (may have partial values) Returns: Exit code """ from effgen.cli.commands.run import interactive_wizard return interactive_wizard(self, args) def run_agent(self, args: argparse.Namespace) -> int | None: """ Run an agent with a task. Args: args: Parsed command-line arguments """ from effgen.cli.commands.run import run_agent return run_agent(self, args) def _handle_interrupt(self, agent) -> None: """Render a friendly Ctrl-C stop (partial trace + 'Stopped.'), no traceback.""" from effgen.cli.commands.run import handle_interrupt return handle_interrupt(self, agent) def chat_mode(self, args: argparse.Namespace) -> int | None: """Interactive chat REPL. Delegates to :class:`effgen.cli.chat.ChatREPL`, which provides streaming answers with a thinking spinner, a model/tool-aware prompt, slash commands (``/model``, ``/tools``, ``/cost``, ``/trace``, …), persistent ↑/↓ history, multiline input, and a per-turn Ctrl-C that cancels the current turn without exiting the session. """ from effgen.cli.commands.chat import chat_mode return chat_mode(self, args) def serve_api(self, args: argparse.Namespace) -> int | None: """Start the effGen API server. Serves the OpenAI-compatible ``/v1`` app plus the ``/run``, ``/tools``, ``/``, ``/slo``, ``/ws`` convenience routes. """ from effgen.cli.commands.serve import serve_api return serve_api(self, args) def _register_convenience_routes(self, app: Any) -> None: """Attach the legacy ``/run``, ``/tools``, ``/``, ``/slo``, ``/ws`` routes onto the secure app from ``create_app``.""" from effgen.cli.commands.serve import register_convenience_routes return register_convenience_routes(self, app) def config_commands(self, args: argparse.Namespace) -> int | None: """Configuration management commands.""" from effgen.cli.commands.config import config_commands return config_commands(self, args) def _config_set(self, args): """Handle 'effgen config set <key> <value>'.""" from effgen.cli.commands.config import config_set return config_set(self, args) def _config_show(self, args): """Show current configuration.""" from effgen.cli.commands.config import config_show return config_show(self, args) def _config_validate(self, args): """Validate configuration file.""" from effgen.cli.commands.config import config_validate return config_validate(self, args) def _config_init(self, args): """Initialize a new configuration file.""" from effgen.cli.commands.config import config_init return config_init(self, args) def tools_commands(self, args: argparse.Namespace) -> int | None: """Tool management commands.""" from effgen.cli.commands.tools import tools_commands return tools_commands(self, args) def _suggest_tool(self, name: str) -> None: """Print a 'tool not found' error with close-match suggestions.""" from effgen.cli.commands.tools import suggest_tool return suggest_tool(self, name) def _tools_list(self, args): """List available tools.""" from effgen.cli.commands.tools import tools_list return tools_list(self, args) def _example_input(self, metadata, tool=None) -> dict: """Build a runnable example input for a tool from its metadata.""" from effgen.cli.commands.tools import example_input return example_input(self, metadata, tool) def _print_tool_usage(self, metadata, tool=None) -> None: """Print a tool's input schema and a copy-paste runnable example.""" from effgen.cli.commands.tools import print_tool_usage return print_tool_usage(self, metadata, tool) def _tools_info(self, args: argparse.Namespace) -> int | None: """Show detailed tool information.""" from effgen.cli.commands.tools import tools_info return tools_info(self, args) def _tools_test(self, args: argparse.Namespace) -> int | None: """Test a tool with sample input.""" from effgen.cli.commands.tools import tools_test return tools_test(self, args) def models_commands(self, args: argparse.Namespace) -> int | None: """Model management commands.""" from effgen.cli.commands.models import models_commands return models_commands(self, args) @staticmethod def _price_cell(rec) -> str: """Format a model's input/output price per 1M tokens for a table cell.""" from effgen.cli.commands.models import price_cell return price_cell(rec) # File extensions that count as actual model weights (an ".index.json" is a # shard manifest, not weights — a repo with only a manifest is still partial). _WEIGHT_SUFFIXES = ( ".safetensors", ".bin", ".gguf", ".pt", ".pth", ".onnx", ".msgpack", ".h5", ".tflite", ".ot", ) def _local_cached_models(self) -> list[dict]: """Models actually downloaded in the local HuggingFace cache (on disk).""" from effgen.cli.commands.models import local_cached_models return local_cached_models(self) def _local_model_context_window(self, path: str) -> int | None: """Read the model's max context length from its on-disk ``config.json``.""" from effgen.cli.commands.models import local_model_context_window return local_model_context_window(self, path) def _models_list(self, args): """List models from the drift-aware registry (not a static yaml).""" from effgen.cli.commands.models import models_list return models_list(self, args) def _rich_tables(self) -> bool: """True when rich table rendering fits the destination (a real terminal).""" from effgen.cli.commands.models import rich_tables return rich_tables(self) @staticmethod def _browse_filter_sort(recs, args): """Apply the browse filters/sort to a list of catalog records.""" from effgen.cli.commands.models import browse_filter_sort return browse_filter_sort(recs, args) def _models_browse(self, args): """Browse the full cross-provider catalog with search/filter/sort/paging.""" from effgen.cli.commands.models import models_browse return models_browse(self, args) @classmethod def _price_in_out_cells(cls, rec) -> tuple[str, str]: """Return (input, output) price cells for the split-column browse table.""" from effgen.cli.commands.models import price_in_out_cells return price_in_out_cells(rec) def _local_model_payload(self, entry: dict) -> dict: """Build the local-cache facts for one model: engines, size, ctx, status.""" from effgen.cli.commands.models import local_model_payload return local_model_payload(self, entry) def _render_local_model_info(self, payload: dict) -> None: """Render the 'this model is in your local cache' block for `models info`.""" from effgen.cli.commands.models import render_local_model_info return render_local_model_info(self, payload) def _models_info(self, args): """Show detailed information for one model from the registry.""" from effgen.cli.commands.models import models_info return models_info(self, args) def _models_load(self, args): """Pre-load a model into the model pool.""" from effgen.cli.commands.models import models_load return models_load(self, args) def _models_unload(self, args): """Unload a model from memory.""" from effgen.cli.commands.models import models_unload return models_unload(self, args) def _models_status(self, args): """Show loaded models and GPU memory status.""" from effgen.cli.commands.models import models_status return models_status(self, args) def _models_status_json(self) -> int: """Emit the GPU table + loaded models as JSON for ops/edge tooling.""" from effgen.cli.commands.models import models_status_json return models_status_json(self) def _models_refresh(self, args): """Refresh the bundled model catalog from each provider's live API.""" from effgen.cli.commands.models import models_refresh return models_refresh(self, args) def examples_commands(self, args: argparse.Namespace) -> int | None: """Run example scripts.""" from effgen.cli.commands.examples import examples_commands return examples_commands(self, args) @staticmethod def _find_examples_dir() -> "Path | None": """Locate the bundled `examples/` directory.""" from effgen.cli.commands.examples import find_examples_dir return find_examples_dir() def _examples_list(self, args): """List available examples.""" from effgen.cli.commands.examples import examples_list return examples_list(self, args) def _examples_run(self, args): """Run an example script.""" from effgen.cli.commands.examples import examples_run return examples_run(self, args) class _EffgenArgumentParser(argparse.ArgumentParser): """ArgumentParser that turns an "invalid choice" into a teaching error. A mistyped subcommand (``effgen rnu``) or a mistyped ``choices=`` option value (``--preset codng``) gets a fuzzy "did you mean 'run'?" / "did you mean 'coding'?" suggestion instead of just dumping the usage banner, so the CLI is self-correcting like the model/tool suggesters elsewhere. Because ``add_subparsers`` inherits this parser class, the handler fires for both the top-level command and every sub-command. """ def _print_message(self, message: str, file=None): # noqa: D401 - argparse hook """Write argparse's own output, folded to ASCII when the stream needs it. Usage banners, ``--help`` and parser errors are written by argparse straight to the stream, so the em-dashes and arrows in the command descriptions reach a ``PYTHONIOENCODING=ascii`` terminal unfolded and the write raises. Folding here is a no-op on a UTF-8 stream, so the bytes a normal terminal receives are unchanged; anything the glyph table does not cover is replaced rather than allowed to raise. """ if not message: return stream = file or sys.stderr from effgen.ui.render import ascii_fold text = ascii_fold(message, stream) try: stream.write(text) except UnicodeEncodeError: encoding = getattr(stream, "encoding", None) or "ascii" stream.write(text.encode(encoding, "replace").decode(encoding)) def error(self, message: str): # noqa: D401 - argparse hook if "invalid choice:" in message: import re m_bad = re.search(r"invalid choice: '([^']*)'", message) m_arg = re.search(r"argument ([^:]+): invalid choice", message) # The offending argument's valid choices are spelled out in the # message ("(choose from 'a', 'b', …)"); fall back to the # subparsers action so an older argparse phrasing still works. choices: list[str] = [] if "choose from" in message: tail = message.split("choose from", 1)[1] choices = re.findall(r"'([^']*)'", tail) sub_action = next( (a for a in self._actions if isinstance(a, argparse._SubParsersAction)), None) if not choices and sub_action is not None: choices = list(sub_action.choices.keys()) if m_bad and choices: bad = m_bad.group(1) arg_name = m_arg.group(1) if m_arg else None hint = _onboarding.did_you_mean(bad, choices, n=1, cutoff=0.5) self.print_usage(sys.stderr) # A positional sub-command (dest matches the subparsers action) # reads best as "unknown command"; a flag value as "invalid value". is_subcommand = sub_action is not None and ( arg_name is None or arg_name in (sub_action.dest, sub_action.metavar) ) if is_subcommand: line = f"{self.prog}: error: unknown command '{bad}'." if hint: line += f" {hint}" line += f"\nAvailable commands: {', '.join(choices)}." else: label = f" for {arg_name}" if arg_name else "" line = f"{self.prog}: error: invalid value '{bad}'{label}." if hint: line += f" {hint}" line += f"\nValid choices: {', '.join(choices)}." print(line, file=sys.stderr) self.exit(2) super().error(message) def create_parser() -> argparse.ArgumentParser: """Create argument parser for CLI.""" # Drive --preset choices from the preset registry so all 9 presets are # accepted (rag/media/multimodal/notify were previously rejected). try: from effgen.presets import list_presets as _list_presets _preset_choices = sorted(_list_presets().keys()) except Exception: _preset_choices = ['math', 'research', 'coding', 'general', 'minimal'] parser = _EffgenArgumentParser( description=f"effGen v{__version__} - CLI for agent framework", formatter_class=argparse.RawDescriptionHelpFormatter, epilog=""" Examples: effgen run "What is 25 * 17?" --model Qwen/Qwen2.5-1.5B-Instruct effgen run "Summarize quantum computing" -m gpt-5-nano --provider openai effgen run "Tell me a joke" -m groq:llama-3.1-8b-instant effgen chat -m gpt-5-nano --provider openai effgen models list # provider registry overview effgen models list --provider groq # full per-model detail effgen doctor --live --cheap # confirm providers are actually usable effgen tools list Model id formats: - Local HuggingFace repo: Qwen/Qwen2.5-1.5B-Instruct - Provider-prefixed: openai:gpt-5-nano groq:llama-3.1-8b-instant - Bare id + --provider: -m gpt-5-nano --provider openai Providers: openai, anthropic, gemini, cerebras, groq, together, fireworks, replicate, hf """ ) parser.add_argument('--version', action='version', version=f'effGen {__version__}') parser.add_argument('-v', '--verbose', action='store_true', help='Verbose output (show DEBUG/INFO logs)') parser.add_argument('-q', '--quiet', action='store_true', help='Quiet output (errors only)') parser.add_argument('--log-file', help='Log file path') parser.add_argument('--no-animation', action='store_true', help='Disable live spinners/progress animation ' '(also via NO_COLOR or EFFGEN_NO_ANIM=1)') parser.add_argument('--theme', choices=['default', 'high-contrast', 'monochrome', 'light'], help='Color theme for terminal output (also via EFFGEN_THEME). ' 'high-contrast targets low-vision readers; monochrome keeps ' 'structure without hue; NO_COLOR still turns color off entirely') parser.add_argument('--completion', choices=['bash', 'zsh', 'fish'], help='Print shell completion script and exit') subparsers = parser.add_subparsers(dest='command', help='Command to run') # Each command's flags are declared in ``effgen.cli.parsers``, next to the # other flags of its family. The calls below are in the order the commands # appear in ``effgen --help``, which is the order argparse reports them in. from effgen.cli.parsers import agent, catalog, history, jobs, ops # noqa: PLC0415 agent.add_run_parser(subparsers, preset_choices=_preset_choices) agent.add_resume_parser(subparsers, preset_choices=_preset_choices) history.add_sessions_parser(subparsers) history.add_runs_parser(subparsers) agent.add_chat_parser(subparsers, preset_choices=_preset_choices) agent.add_code_parser(subparsers) ops.add_serve_parser(subparsers) ops.add_top_parsers(subparsers) catalog.add_config_parser(subparsers) catalog.add_tools_parser(subparsers) catalog.add_models_parser(subparsers) catalog.add_examples_parser(subparsers) ops.add_health_parser(subparsers) ops.add_doctor_parser(subparsers) ops.add_plugin_parser(subparsers) catalog.add_presets_parser(subparsers) agent.add_quickstart_parsers(subparsers) jobs.add_workflow_parser(subparsers) jobs.add_batch_parser(subparsers, preset_choices=_preset_choices) jobs.add_eval_parser(subparsers, preset_choices=_preset_choices) jobs.add_compare_parser(subparsers, preset_choices=_preset_choices) jobs.add_battle_parser(subparsers) agent.add_debug_parser(subparsers, preset_choices=_preset_choices) jobs.add_cost_parser(subparsers) jobs.add_report_parser(subparsers) catalog.add_prompts_parser(subparsers) # Load test command from effgen.cli.loadtest import add_loadtest_subparser # noqa: PLC0415 add_loadtest_subparser(subparsers) return parser def _extract_theme_arg(argv: list[str]) -> tuple[list[str], str | None]: """Pull a ``--theme <name>`` (any position) out of *argv*. ``--theme`` selects the terminal color theme for every command's output, so it is accepted before or after the subcommand. Returns the remaining arguments and the requested theme name (or ``None``). """ remaining: list[str] = [] theme: str | None = None i = 0 while i < len(argv): arg = argv[i] if arg == "--theme": if i + 1 < len(argv): theme = argv[i + 1] i += 2 continue i += 1 continue if arg.startswith("--theme="): theme = arg.split("=", 1)[1] i += 1 continue remaining.append(arg) i += 1 return remaining, theme def _dispatch(args: argparse.Namespace, cli: "CLIInterface", parser: argparse.ArgumentParser) -> int: """Route parsed *args* to the matching command handler and return its exit code. One routing table shared by ``main()`` and the bare-command landing, so a quick action chosen on the landing reaches the same handler as typing the command directly. """ if args.command == 'run': exit_code = cli.run_agent(args) elif args.command == 'chat': exit_code = cli.chat_mode(args) elif args.command == 'code': from effgen.cli.commands.code import run_code_command exit_code = run_code_command(cli, args) elif args.command == 'serve': exit_code = cli.serve_api(args) elif args.command == 'config': exit_code = cli.config_commands(args) elif args.command == 'tools': exit_code = cli.tools_commands(args) elif args.command == 'models': exit_code = cli.models_commands(args) elif args.command == 'examples': exit_code = cli.examples_commands(args) elif args.command == 'health': from effgen.cli.commands.health import handle_health_command exit_code = handle_health_command(args, cli) elif args.command == 'doctor': exit_code = _handle_doctor_command(args) elif args.command == 'resume': exit_code = _handle_resume_command(args, cli) elif args.command == 'sessions': exit_code = _handle_sessions_command(args, cli) elif args.command == 'runs': exit_code = _handle_runs_command(args, cli) elif args.command == 'create-plugin': exit_code = _create_plugin_scaffold(args.plugin_name, args.output_dir) elif args.command == 'presets': from effgen.cli.commands.presets import handle_presets_command exit_code = handle_presets_command(args, cli) elif args.command in ('quickstart', 'tutorial'): exit_code = _handle_quickstart_command(args, cli) elif args.command == 'workflow': exit_code = _handle_workflow_command(args, cli) elif args.command == 'batch': exit_code = _handle_batch_command(args, cli) elif args.command == 'eval': exit_code = _handle_eval_command(args, cli) elif args.command == 'compare': exit_code = _handle_compare_command(args, cli) elif args.command == 'battle': from effgen.cli.battle import run_battle_command exit_code = run_battle_command(args) elif args.command in ('top', 'monitor'): from effgen.cli.monitor import run_monitor_command exit_code = run_monitor_command(args) elif args.command == 'cost': exit_code = _handle_cost_command(args, cli) elif args.command == 'report': exit_code = _handle_report_command(args, cli) elif args.command == 'prompts': exit_code = _handle_prompts_command(args, cli) elif args.command == 'loadtest': func = getattr(args, 'func', None) if func: exit_code = func(args) else: from effgen.cli.loadtest import run_loadtest_command exit_code = run_loadtest_command(args) elif args.command == 'debug': from effgen.debug.inspector import run_debug_cli # Validate an explicit --provider up front (a typo like "grok" # should fail fast with a suggestion), mirroring `run`/`chat`. provider, prov_err = resolve_provider_name(getattr(args, 'provider', None)) if prov_err: cli.print_error(prov_err) exit_code = 1 else: exit_code = run_debug_cli( task=args.task, preset=getattr(args, 'preset', None), model=getattr(args, 'model', None), provider=provider, step=getattr(args, 'step', False), ) elif args.command is None: # No command - launch interactive wizard # Create a namespace with default values for run command class WizardArgs: task = None model = None name = None tools = None config = None system_prompt = None temperature = None max_iterations = None mode = None no_sub_agents = False stream = False output = None verbose = getattr(args, 'verbose', False) exit_code = cli.interactive_wizard(WizardArgs()) else: parser.print_help() exit_code = 0 return exit_code if exit_code is not None else 0 def _silence_broken_pipe() -> None: """Point stdout at the null device after a reader closed the pipe. ``effgen models list --json | head`` leaves the process writing into a pipe nobody reads. Without this the interpreter's exit-time flush raises again and prints ``Exception ignored ... BrokenPipeError`` after the command has already done its job. """ try: devnull = os.open(os.devnull, os.O_WRONLY) os.dup2(devnull, sys.stdout.fileno()) except (OSError, ValueError): # pragma: no cover - stdout already gone pass def _fold_output_streams(): """Route ``stdout``/``stderr`` through an ASCII fold when they need one. A console forced to a non-UTF-8 encoding cannot write the em-dashes, table rules and glyphs the listing and summary commands print, and the failed write turns a command that did its work into one that exits non-zero. This substitutes ASCII stand-ins at the single point where text becomes bytes, so every command -- including one added later -- reports its real status. A stream that can already encode those characters is left exactly as it is, so a normal terminal receives the same bytes as before. Returns a callable that puts the original streams back. """ from effgen.ui.render import ascii_folding_stream original_stdout, original_stderr = sys.stdout, sys.stderr sys.stdout = ascii_folding_stream(sys.stdout) sys.stderr = ascii_folding_stream(sys.stderr) def restore() -> None: sys.stdout, sys.stderr = original_stdout, original_stderr return restore def main() -> None: """Main entry point for CLI.""" restore_streams = _fold_output_streams() try: _run_cli() finally: restore_streams() def _run_cli() -> None: """Parse the command line and dispatch to the selected command.""" # Before anything can warn: render this package's own warnings as one line # instead of Python's file/line/source-echo block, which lands mid-answer # and points at internals the reader did not write. from effgen.cli import _warnings as _warning_render _warning_render.install() # Load .env early so all subcommands see API keys (see load_env_files). load_env_files() # A --theme selects the color theme for every console built below; accept it # in any position (EFFGEN_THEME serves the same purpose without a flag). argv, theme_arg = _extract_theme_arg(sys.argv[1:]) if theme_arg: os.environ["EFFGEN_THEME"] = theme_arg parser = create_parser() args = parser.parse_args(argv) # Handle completion script generation if getattr(args, 'completion', None): from effgen.completion import get_completion print(get_completion(args.completion)) sys.exit(0) # Setup logging. --verbose / --quiet may appear either before the # subcommand (global) or after it (per-command); honor whichever is set. _verbose = getattr(args, 'verbose', False) setup_logging( verbose=_verbose, log_file=getattr(args, 'log_file', None), quiet=getattr(args, 'quiet', False), ) # For a command that renders its own failures, keep the console free of the # duplicate raw library ERROR line at default verbosity (--verbose / a # --log-file still carry the full diagnostic stream). if not _verbose and getattr(args, 'command', None) in _SELF_RENDERING_ERROR_COMMANDS: _suppress_echoed_error_logs() # Create CLI interface cli = CLIInterface() # On a bare `effgen` at an interactive terminal, show the branded landing # (logo + quick actions) instead of dropping straight into the wizard; the # landing absorbs the first-run welcome. Every other path — a subcommand, # piped/redirected output, --quiet, CI, no rich — keeps its current behavior. show_landing = _landing.should_show(cli, args) # One-time friendly welcome on first interactive use (records a flag so it # only ever shows once). Silent under --quiet / non-interactive / CI. Skipped # when the landing will render it inline. if not show_landing: _onboarding.maybe_show_first_run_welcome(quiet=getattr(args, 'quiet', False)) # Route to appropriate handler try: if show_landing: exit_code = _landing.run(cli, parser, args, _dispatch) else: exit_code = _dispatch(args, cli, parser) # A gentle, rotating tip at a natural moment — only after the commands a # human watches finish cleanly, never under --quiet / non-interactive / # EFFGEN_TIPS=0, and only every few runs (see onboarding.maybe_print_tip). _TIP_COMMANDS = {'run', 'chat', 'code', 'quickstart', 'tutorial', 'presets', 'doctor'} if ( exit_code == 0 and args.command in _TIP_COMMANDS and not getattr(args, 'output_json', False) ): _onboarding.maybe_print_tip(quiet=getattr(args, 'quiet', False)) # Flush inside the guard: a pipe closed by the reader must be reported # here, not by the interpreter's exit-time flush where it becomes an # "Exception ignored" line no one can act on. sys.stdout.flush() sys.exit(exit_code) except BrokenPipeError: # The reader closed the pipe first (`effgen … | head`). The command did # its work; report the conventional SIGPIPE status without a traceback. _silence_broken_pipe() sys.exit(141) except KeyboardInterrupt: # Both of these are for the human, so they go to stderr: a command # interrupted or failed mid-pipeline must not put prose on stdout where # a `--json` reader or a downstream `jq` expects the result alone. print("\n\nInterrupted by user", file=sys.stderr) sys.exit(130) except Exception as e: print(f"Error: {e}", file=sys.stderr) if getattr(args, 'verbose', False): import traceback traceback.print_exc() sys.exit(1) def agent_main() -> None: """ Entry point for effgen-agent CLI (similar to smolagent). A generalist command to run a multi-step agent that can be equipped with various tools. Usage: # Run with direct prompt and options effgen-agent "Plan a trip to Tokyo" --model Qwen/Qwen2.5-1.5B-Instruct --tools web_search calculator # Run in interactive mode (launches setup wizard when no prompt provided) effgen-agent Interactive mode guides you through: - Reasoning style (auto / react / single — one Agent, different strategies) - Tool selection from available toolbox - Model configuration (type, ID, API settings) - Advanced options like additional imports - Task prompt input """ import sys if len(sys.argv) > 1 and not sys.argv[1].startswith('-'): # Direct task mode - pass to run command task = sys.argv[1] remaining_args = sys.argv[2:] # Build new argv for main() new_argv = [sys.argv[0], 'run', task] + remaining_args sys.argv = new_argv elif len(sys.argv) == 1: # No arguments - launch interactive wizard sys.argv = [sys.argv[0], 'run'] # run without task triggers wizard # else: arguments starting with '-' will be handled by argparse main() def web_agent_main() -> None: """ Entry point for web agent CLI (effgen-web). A specialized agent for web browsing tasks. Usage: effgen-web "go to example.com and get the page title" effgen-web # Interactive mode """ import sys if len(sys.argv) > 1 and not sys.argv[1].startswith('-'): # Direct task mode task = sys.argv[1] sys.argv = [sys.argv[0], 'run', task, '--tools', 'web_search'] + sys.argv[2:] else: # Interactive mode - show help print(f"effGen Web Agent v{__version__}") print() print("Usage:") print(" effgen-web \"<task>\" Run a web task") print(" effgen-web --model <model> Specify model") print() print("Example:") print(" effgen-web \"Search for the latest Python release\"") print() return main() if __name__ == "__main__": main()
"""
effGen CLI - Command-line interface for the effGen framework.
This module provides a comprehensive CLI for interacting with effGen:
- Run agents with tasks (with interactive wizard support)
- Interactive chat mode
- API server mode
- Configuration management
- Tool listing and testing
- Model management
- Example runner
Usage:
# Direct task execution
effgen run "What is 2+2?" --model Qwen/Qwen2.5-1.5B-Instruct
# Interactive wizard (launches when no task provided)
effgen run
effgen # Same as above
# effgen-agent command (similar to smolagent)
effgen-agent "Plan a trip to Tokyo" --model Qwen/Qwen2.5-1.5B-Instruct --tools web_search
effgen-agent # Interactive mode
# Chat mode
effgen chat --model Qwen/Qwen2.5-3B-Instruct
# Other commands
effgen serve --port 8000
effgen config show
effgen tools list
effgen models list
effgen examples run basic_agent
Interactive mode guides you through:
- Agent type selection (CodeAgent vs ToolCallingAgent vs ReActAgent)
- Tool selection from available toolbox
- Model configuration (type, ID, API settings)
- Advanced options (temperature, max iterations, etc.)
- Task prompt input
"""
from __future__ import annotations
import argparse
import asyncio # noqa: F401 - module attribute for command modules that import it from here
import importlib.util # noqa: F401 - module attribute for command modules
import json # noqa: F401 - module attribute for command modules
import logging
import os
import sys
from datetime import datetime # noqa: F401 - module attribute for command modules
from pathlib import Path
from typing import Any
# Rich terminal output (fallback to basic if not available)
try:
from rich import print as rprint # noqa: F401
from rich.console import Console
from rich.layout import Layout # noqa: F401
from rich.live import Live # noqa: F401
from rich.markdown import Markdown # noqa: F401 - module attribute for command modules
from rich.panel import Panel # noqa: F401 - module attribute for command modules
from rich.progress import Progress, SpinnerColumn, TextColumn # noqa: F401 - module attrs
from rich.syntax import Syntax # noqa: F401 - availability shim / module attribute
from rich.table import Table # noqa: F401 - module attribute for command modules
RICH_AVAILABLE = True
except ImportError:
RICH_AVAILABLE = False
Console = None
# Import effGen components
try:
from effgen import ( # noqa: F401
Agent,
AgentConfig,
ConfigLoader,
__version__,
get_tool_registry,
load_model,
)
from effgen.core.agent import AgentMode # noqa: F401 - read as a module attribute
except ImportError:
print("Error: effGen package not found. Please install it first.")
sys.exit(1)
# .env discovery + loading is shared with the library-facing ``effgen.load_env()``
# so the CLI and a script/notebook resolve keys the same way. These aliases keep
# the historical CLI-internal names (used by tests and callers) working.
from effgen._env import dotenv_disabled as _dotenv_disabled # noqa: F401 - re-export
from effgen._env import env_search_paths as _env_search_paths # noqa: F401 - re-export
from effgen._env import load_env as load_env_files
# Branded bare-command landing (TTY-only; falls through to the wizard otherwise).
from effgen.cli import landing as _landing
# Tips, first-run welcome, "did you mean?" and teaching-error helpers.
from effgen.cli import onboarding as _onboarding

Xet Storage Details

Size:
43.2 kB
·
Xet hash:
8e08bc3117c43a40a5a37ea30959524c0c024c83a9b4ea0f42406d9b2a85b244

Xet efficiently stores files, intelligently splitting them into unique chunks and accelerating uploads and downloads. More info.