humancli 0.1.0__py3-none-any.whl

agentcli/_parser.py

@@ -0,0 +1,417 @@
+from __future__ import annotations
+
+import enum
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Callable, Mapping, get_args, get_origin
+
+from ._errors import AgentCliError, ParseError, ValidationError, suggest_matches
+from ._types import BuiltinFlags, CommandSchema, MISSING, ParameterSpec
+
+
+@dataclass(frozen=True)
+class ParsedCommand:
+    values: dict[str, Any]
+
+
+def extract_builtins(argv: list[str]) -> tuple[BuiltinFlags, list[str]]:
+    flags = BuiltinFlags()
+    remaining: list[str] = []
+    index = 0
+    while index < len(argv):
+        token = argv[index]
+        if token == "--format":
+            if index + 1 >= len(argv):
+                raise ParseError("Missing value for --format", code="MISSING_OPTION")
+            flags = BuiltinFlags(
+                format=argv[index + 1],
+                verbose=flags.verbose,
+                help=flags.help,
+                version=flags.version,
+                llms=flags.llms,
+                llms_full=flags.llms_full,
+                mcp=flags.mcp,
+                wizard=flags.wizard,
+            )
+            index += 2
+            continue
+        if token.startswith("--format="):
+            flags = BuiltinFlags(
+                format=token.split("=", 1)[1],
+                verbose=flags.verbose,
+                help=flags.help,
+                version=flags.version,
+                llms=flags.llms,
+                llms_full=flags.llms_full,
+                mcp=flags.mcp,
+                wizard=flags.wizard,
+            )
+            index += 1
+            continue
+        if token == "--json":
+            flags = BuiltinFlags(
+                format="json",
+                verbose=flags.verbose,
+                help=flags.help,
+                version=flags.version,
+                llms=flags.llms,
+                llms_full=flags.llms_full,
+                mcp=flags.mcp,
+                wizard=flags.wizard,
+            )
+            index += 1
+            continue
+        if token == "--verbose":
+            flags = BuiltinFlags(
+                format=flags.format,
+                verbose=True,
+                help=flags.help,
+                version=flags.version,
+                llms=flags.llms,
+                llms_full=flags.llms_full,
+                mcp=flags.mcp,
+                wizard=flags.wizard,
+            )
+            index += 1
+            continue
+        if token in {"--help", "-h"}:
+            flags = BuiltinFlags(
+                format=flags.format,
+                verbose=flags.verbose,
+                help=True,
+                version=flags.version,
+                llms=flags.llms,
+                llms_full=flags.llms_full,
+                mcp=flags.mcp,
+                wizard=flags.wizard,
+            )
+            index += 1
+            continue
+        if token == "--version":
+            flags = BuiltinFlags(
+                format=flags.format,
+                verbose=flags.verbose,
+                help=flags.help,
+                version=True,
+                llms=flags.llms,
+                llms_full=flags.llms_full,
+                mcp=flags.mcp,
+                wizard=flags.wizard,
+            )
+            index += 1
+            continue
+        if token == "--llms":
+            flags = BuiltinFlags(
+                format=flags.format,
+                verbose=flags.verbose,
+                help=flags.help,
+                version=flags.version,
+                llms=True,
+                llms_full=flags.llms_full,
+                mcp=flags.mcp,
+                wizard=flags.wizard,
+            )
+            index += 1
+            continue
+        if token == "--llms-full":
+            flags = BuiltinFlags(
+                format=flags.format,
+                verbose=flags.verbose,
+                help=flags.help,
+                version=flags.version,
+                llms=flags.llms,
+                llms_full=True,
+                mcp=flags.mcp,
+                wizard=flags.wizard,
+            )
+            index += 1
+            continue
+        if token == "--mcp":
+            flags = BuiltinFlags(
+                format=flags.format,
+                verbose=flags.verbose,
+                help=flags.help,
+                version=flags.version,
+                llms=flags.llms,
+                llms_full=flags.llms_full,
+                mcp=True,
+                wizard=flags.wizard,
+            )
+            index += 1
+            continue
+        if token == "--wizard":
+            flags = BuiltinFlags(
+                format=flags.format,
+                verbose=flags.verbose,
+                help=flags.help,
+                version=flags.version,
+                llms=flags.llms,
+                llms_full=flags.llms_full,
+                mcp=flags.mcp,
+                wizard=True,
+            )
+            index += 1
+            continue
+        remaining.append(token)
+        index += 1
+    return flags, remaining
+
+
+def parse_command(
+    schema: CommandSchema,
+    argv: list[str],
+    *,
+    env: Mapping[str, str] | None = None,
+    is_tty: bool,
+    resolve_prompt_value: Callable[..., Any] | None = None,
+) -> ParsedCommand:
+    env_map = env or {}
+    option_by_name = {spec.cli_name: spec for spec in schema.options}
+    option_by_alias = {spec.alias: spec for spec in schema.options if spec.alias}
+    raw_values: dict[str, Any] = {}
+    positionals: list[str] = []
+    index = 0
+    literal_mode = False
+
+    while index < len(argv):
+        token = argv[index]
+        if literal_mode:
+            positionals.append(token)
+            index += 1
+            continue
+        if token == "--":
+            literal_mode = True
+            index += 1
+            continue
+        if token.startswith("--"):
+            name, has_inline, inline_value = token[2:].partition("=")
+            negate = False
+            if name.startswith("no-"):
+                name = name[3:]
+                negate = True
+            spec = option_by_name.get(name)
+            if spec is None:
+                suggestions = suggest_matches(name, option_by_name)
+                hint = (
+                    f" Did you mean: {', '.join(f'--{item}' for item in suggestions)}?"
+                    if suggestions
+                    else ""
+                )
+                raise ParseError(
+                    f'Unknown option "--{name}".{hint}', code="UNKNOWN_OPTION"
+                )
+            if negate:
+                if not spec.is_bool:
+                    raise ParseError(
+                        f'Option "--{name}" does not support --no- form',
+                        code="UNKNOWN_OPTION",
+                    )
+                raw_values[spec.name] = False
+                index += 1
+                continue
+            if spec.is_bool and not has_inline:
+                raw_values[spec.name] = True
+                index += 1
+                continue
+            value = (
+                inline_value if has_inline else _next_value(argv, index, f"--{name}")
+            )
+            _store_value(raw_values, spec, coerce_value(spec, value))
+            index += 1 if has_inline else 2
+            continue
+        if token.startswith("-") and token != "-":
+            short = token[1:]
+            if "=" in short:
+                alias, value = short.split("=", 1)
+                spec = option_by_alias.get(alias)
+                if spec is None:
+                    raise ParseError(
+                        f'Unknown option "-{alias}"', code="UNKNOWN_OPTION"
+                    )
+                _store_value(raw_values, spec, coerce_value(spec, value))
+                index += 1
+                continue
+            if len(short) > 1 and all(
+                option_by_alias.get(char) and option_by_alias[char].is_bool
+                for char in short
+            ):
+                for char in short:
+                    raw_values[option_by_alias[char].name] = True
+                index += 1
+                continue
+            spec = option_by_alias.get(short)
+            if spec is None:
+                raise ParseError(f'Unknown option "-{short}"', code="UNKNOWN_OPTION")
+            if spec.is_bool:
+                raw_values[spec.name] = True
+                index += 1
+                continue
+            value = _next_value(argv, index, f"-{short}")
+            _store_value(raw_values, spec, coerce_value(spec, value))
+            index += 2
+            continue
+        positionals.append(token)
+        index += 1
+
+    if len(positionals) > len(schema.arguments):
+        raise ParseError("Too many positional arguments", code="TOO_MANY_ARGS")
+
+    values: dict[str, Any] = {}
+    for spec, raw in zip(schema.arguments, positionals):
+        values[spec.name] = coerce_value(spec, raw)
+    for spec in schema.arguments[len(positionals) :]:
+        values[spec.name] = resolve_missing(
+            spec,
+            env_map,
+            is_tty=is_tty,
+            resolve_prompt_value=resolve_prompt_value,
+        )
+    for spec in schema.options:
+        if spec.name in raw_values:
+            values[spec.name] = raw_values[spec.name]
+            continue
+        values[spec.name] = resolve_missing(
+            spec,
+            env_map,
+            is_tty=is_tty,
+            resolve_prompt_value=resolve_prompt_value,
+        )
+    return ParsedCommand(values=values)
+
+
+def resolve_missing(
+    spec: ParameterSpec,
+    env: Mapping[str, str],
+    *,
+    is_tty: bool,
+    resolve_prompt_value: Callable[..., Any] | None,
+) -> Any:
+    if spec.env and spec.env in env:
+        return coerce_value(spec, env[spec.env])
+    value = spec.default
+    if resolve_prompt_value is not None:
+        value = resolve_prompt_value(
+            spec,
+            current_value=value,
+            is_tty=is_tty,
+        )
+    if value is not MISSING:
+        return value
+    code = "MISSING_OPTION" if spec.kind == "option" else "MISSING_ARG"
+    subject = "option" if spec.kind == "option" else "argument"
+    label = f"--{spec.cli_name}" if spec.kind == "option" else spec.name
+    raise ParseError(f'Missing required {subject} "{label}"', code=code)
+
+
+def coerce_value(spec: ParameterSpec, value: Any) -> Any:
+    annotation = spec.annotation
+    if spec.is_list:
+        inner = get_args(annotation)
+        inner_type = inner[0] if inner else str
+        raw_values = value if isinstance(value, list) else [value]
+        return [_coerce_with_type(item, inner_type, spec.name) for item in raw_values]
+    return _coerce_with_type(value, annotation, spec.name, choices=spec.choices)
+
+
+def _coerce_with_type(
+    value: Any,
+    annotation: Any,
+    field_name: str,
+    *,
+    choices: tuple[Any, ...] = (),
+) -> Any:
+    if choices:
+        mapping = {str(item).lower(): item for item in choices}
+        lowered = str(value).lower()
+        if lowered in mapping:
+            return mapping[lowered]
+        joined = ", ".join(str(item) for item in choices)
+        raise ValidationError(
+            message=f'Invalid value "{value}" for {field_name}. Expected one of: {joined}'
+        )
+    if annotation in (Any, str):
+        return value
+    if annotation is Path:
+        return Path(value)
+    if annotation is int:
+        try:
+            return int(str(value), 0)
+        except ValueError as exc:
+            raise ValidationError(
+                message=f"Invalid integer for {field_name}: {value}"
+            ) from exc
+    if annotation is float:
+        try:
+            return float(str(value))
+        except ValueError as exc:
+            raise ValidationError(
+                message=f"Invalid float for {field_name}: {value}"
+            ) from exc
+    if annotation is bool:
+        if isinstance(value, bool):
+            return value
+        lowered = str(value).strip().lower()
+        if lowered in {"1", "true", "yes", "y", "on"}:
+            return True
+        if lowered in {"0", "false", "no", "n", "off"}:
+            return False
+        raise ValidationError(message=f"Invalid boolean for {field_name}: {value}")
+    origin = get_origin(annotation)
+    if origin and "Union" in str(origin):
+        for branch in get_args(annotation):
+            if branch is type(None):
+                continue
+            try:
+                return _coerce_with_type(value, branch, field_name)
+            except AgentCliError:
+                continue
+        raise ValidationError(message=f'Invalid value "{value}" for {field_name}')
+    if isinstance(annotation, type) and issubclass(annotation, enum.Enum):
+        lowered = str(value).lower()
+        for member in annotation:
+            if member.name.lower() == lowered:
+                return member
+        raise ValidationError(message=f'Invalid value "{value}" for {field_name}')
+    return value
+
+
+def _store_value(target: dict[str, Any], spec: ParameterSpec, value: Any) -> None:
+    if spec.is_list:
+        target.setdefault(spec.name, []).extend(
+            value if isinstance(value, list) else [value]
+        )
+        return
+    target[spec.name] = value
+
+
+def _next_value(argv: list[str], index: int, label: str) -> str:
+    if index + 1 >= len(argv):
+        raise ParseError(f"Missing value for {label}", code="MISSING_OPTION")
+    return argv[index + 1]
+
+
+def strip_builtin_flags(argv: list[str]) -> tuple[BuiltinFlags, list[str]]:
+    return extract_builtins(argv)
+
+
+def normalize_format(explicit: str | None, *, tty: bool) -> str:
+    if explicit:
+        return explicit
+    return "human" if tty else "toon"
+
+
+def parse_values(
+    argv: list[str],
+    schema: CommandSchema,
+    *,
+    env: Mapping[str, str] | None = None,
+    tty: bool,
+    prompt_value: Callable[..., Any] | None,
+) -> dict[str, Any]:
+    return parse_command(
+        schema,
+        argv,
+        env=env,
+        is_tty=tty,
+        resolve_prompt_value=prompt_value,
+    ).values

agentcli/_schema.py

@@ -0,0 +1,142 @@
+from __future__ import annotations
+
+import inspect
+from typing import Annotated, Any, get_args, get_origin, get_type_hints
+
+import docstring_parser
+
+from ._context import Context
+from ._errors import ConfigError
+from ._types import CommandSchema, MISSING, Param, ParameterSpec
+
+
+def snake_to_kebab(value: str) -> str:
+    return value.rstrip("_").replace("_", "-")
+
+
+def command_name_for(value: str) -> str:
+    return snake_to_kebab(value)
+
+
+def extract_command_schema(
+    fn: Any,
+    *,
+    name: str | None = None,
+    output: Any = None,
+    path: tuple[str, ...] = (),
+) -> CommandSchema:
+    signature = inspect.signature(fn)
+    hints = get_type_hints(fn, include_extras=True)
+    descriptions = _docstring_param_descriptions(fn)
+    arguments: list[ParameterSpec] = []
+    options: list[ParameterSpec] = []
+    positional_names: list[str] = []
+    keyword_names: list[str] = []
+    context_name: str | None = None
+
+    for parameter in signature.parameters.values():
+        if parameter.kind in (
+            inspect.Parameter.VAR_POSITIONAL,
+            inspect.Parameter.VAR_KEYWORD,
+        ):
+            raise ConfigError(f"Unsupported parameter kind for {parameter.name}")
+        annotation = hints.get(parameter.name, parameter.annotation)
+        annotation, metadata = unwrap_annotation(annotation)
+        if annotation is Context:
+            context_name = parameter.name
+            if parameter.kind is inspect.Parameter.KEYWORD_ONLY:
+                keyword_names.append(parameter.name)
+            else:
+                positional_names.append(parameter.name)
+            continue
+        default = (
+            parameter.default if parameter.default is not inspect._empty else MISSING
+        )
+        help_text = (
+            metadata.help
+            if metadata and metadata.help
+            else descriptions.get(parameter.name)
+        )
+        spec = ParameterSpec(
+            name=parameter.name,
+            kind="option"
+            if parameter.kind is inspect.Parameter.KEYWORD_ONLY
+            else "argument",
+            annotation=annotation,
+            cli_name=snake_to_kebab(parameter.name),
+            default=default,
+            required=default is MISSING,
+            help=help_text,
+            alias=metadata.alias if metadata else None,
+            env=metadata.env if metadata else None,
+            prompt=metadata.prompt if metadata else None,
+            secret=metadata.secret if metadata else False,
+            deprecated=metadata.deprecated if metadata else False,
+            hidden=metadata.hidden if metadata else False,
+            choices=literal_choices(annotation),
+            is_list=is_list(annotation),
+            is_bool=annotation is bool,
+        )
+        if spec.kind == "argument":
+            arguments.append(spec)
+            positional_names.append(parameter.name)
+        else:
+            options.append(spec)
+            keyword_names.append(parameter.name)
+
+    description = inspect.getdoc(fn)
+    short_description = description.splitlines()[0] if description else None
+    return CommandSchema(
+        name=snake_to_kebab(name or fn.__name__),
+        full_path=path + (snake_to_kebab(name or fn.__name__),),
+        description=short_description,
+        handler=fn,
+        positionals=tuple(arguments),
+        options=tuple(options),
+        positional_names=tuple(positional_names),
+        keyword_names=tuple(keyword_names),
+        context_name=context_name,
+        output=output,
+    )
+
+
+def build_command_schema(
+    fn: Any,
+    *,
+    name: str | None = None,
+    full_path: tuple[str, ...] = (),
+    output_type: Any = None,
+) -> CommandSchema:
+    path = full_path[:-1] if full_path else ()
+    return extract_command_schema(fn, name=name, output=output_type, path=path)
+
+
+def unwrap_annotation(annotation: Any) -> tuple[Any, Param | None]:
+    if get_origin(annotation) is Annotated:
+        base, *metadata = get_args(annotation)
+        param = next((item for item in metadata if isinstance(item, Param)), None)
+        return base, param
+    return annotation, None
+
+
+def literal_choices(annotation: Any) -> tuple[Any, ...]:
+    origin = get_origin(annotation)
+    if origin is None or "Literal" not in str(origin):
+        return ()
+    return tuple(get_args(annotation))
+
+
+def is_list(annotation: Any) -> bool:
+    return get_origin(annotation) in (list, tuple)
+
+
+def _docstring_param_descriptions(fn: Any) -> dict[str, str]:
+    docstring = inspect.getdoc(fn)
+    if not docstring:
+        return {}
+    parsed = docstring_parser.parse(docstring)
+    return {
+        item.arg_name: item.description
+        for item in parsed.params
+        if item.arg_name and item.description
+    }

agentcli/_types.py

@@ -0,0 +1,142 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Callable, Literal
+
+
+class _Missing:
+    def __bool__(self) -> bool:
+        return False
+
+    def __repr__(self) -> str:
+        return "MISSING"
+
+
+MISSING = _Missing()
+
+OutputFormat = Literal["human", "toon", "json", "yaml", "md", "jsonl"]
+
+
+@dataclass(frozen=True)
+class Param:
+    help: str | None = None
+    alias: str | None = None
+    env: str | None = None
+    prompt: str | None = None
+    secret: bool = False
+    deprecated: bool = False
+    hidden: bool = False
+
+
+@dataclass(frozen=True)
+class Result:
+    data: Any
+    cta: list[str] | None = None
+
+
+@dataclass(frozen=True)
+class ParameterSpec:
+    name: str
+    kind: str
+    annotation: Any
+    cli_name: str
+    default: Any = MISSING
+    required: bool = True
+    help: str | None = None
+    alias: str | None = None
+    env: str | None = None
+    prompt: str | None = None
+    secret: bool = False
+    deprecated: bool = False
+    hidden: bool = False
+    choices: tuple[Any, ...] = ()
+    is_list: bool = False
+    is_bool: bool = False
+
+    @property
+    def description(self) -> str | None:
+        return self.help
+
+    @property
+    def has_default(self) -> bool:
+        return self.default is not MISSING
+
+    @property
+    def display_name(self) -> str:
+        return self.name if self.kind == "argument" else f"--{self.cli_name}"
+
+
+@dataclass
+class CommandSchema:
+    name: str
+    full_path: tuple[str, ...]
+    description: str | None
+    handler: Callable[..., Any]
+    positionals: tuple[ParameterSpec, ...]
+    options: tuple[ParameterSpec, ...]
+    positional_names: tuple[str, ...]
+    keyword_names: tuple[str, ...]
+    context_name: str | None = None
+    output: Any = None
+
+    @property
+    def path(self) -> tuple[str, ...]:
+        return self.full_path
+
+    @property
+    def arguments(self) -> tuple[ParameterSpec, ...]:
+        return self.positionals
+
+    @property
+    def context_parameter(self) -> str | None:
+        return self.context_name
+
+    @property
+    def callback(self) -> Callable[..., Any]:
+        return self.handler
+
+    @property
+    def command(self) -> str:
+        return " ".join(self.full_path)
+
+    @property
+    def all_parameters(self) -> list[ParameterSpec]:
+        return [*self.positionals, *self.options]
+
+
+@dataclass(frozen=True)
+class BuiltinFlags:
+    format: str | None = None
+    verbose: bool = False
+    help: bool = False
+    version: bool = False
+    llms: bool = False
+    llms_full: bool = False
+    mcp: bool = False
+    wizard: bool = False
+
+
+@dataclass
+class InvocationResult:
+    exit_code: int
+    output: str = ""
+    envelope: Any | None = None
+    data: Any = None
+    error: Any = None
+
+
+@dataclass
+class ExecutionResult:
+    exit_code: int
+    envelope: Any
+    output: str
+    format: OutputFormat
+    streamed: list[Any] = field(default_factory=list)
+
+    @property
+    def data(self) -> Any:
+        return None if self.envelope is None else self.envelope.data
+
+    @property
+    def error(self) -> Any:
+        return None if self.envelope is None else self.envelope.error