agent-data-cli 0.1.0__py3-none-any.whl

agent_data_cli/PYPI_README.md

@@ -0,0 +1,72 @@
+# agent-data-cli
+
+`agent-data-cli` is a unified multi-source content CLI for discovery, sync, local query, and explicit interaction.
+
+It is designed for agent workflows and human operators who want one stable command surface across news, RSS, social media, market data, and other content sources that fit the `source/channel/content` model.
+
+## Install
+
+Recommended:
+
+```bash
+uv tool install agent-data-cli
+```
+
+PyPA-standard CLI install:
+
+```bash
+pipx install agent-data-cli
+```
+
+If you also want the dashboard:
+
+```bash
+uv tool install "agent-data-cli[dashboard]"
+```
+
+or:
+
+```bash
+pipx install "agent-data-cli[dashboard]"
+```
+
+## Quick Start
+
+```bash
+adc init --defaults
+adc help
+adc source list
+```
+
+`adc init` creates the local runtime home at `~/.adc`, initializes the database, and prepares the default `source_workspace`.
+
+## Typical Flow
+
+```bash
+adc hub search --query xiaohongshu
+adc hub install xiaohongshu
+adc source list
+adc channel search --source xiaohongshu --query 咖啡
+adc sub add --source xiaohongshu --channel <channel>
+adc content update --source xiaohongshu
+adc content query --source xiaohongshu --limit 20
+```
+
+## Dashboard
+
+```bash
+adc dashboard
+adc dashboard start --daemon
+adc dashboard status
+adc dashboard stop
+```
+
+## Python Version
+
+- Python `3.12+`
+
+## Links
+
+- Source: <https://github.com/severinzhong/agent-data-cli>
+- Issues: <https://github.com/severinzhong/agent-data-cli/issues>
+- Companion source workspace: <https://github.com/severinzhong/agent-data-hub>

agent_data_cli/__init__.py

@@ -0,0 +1,2 @@
+from __future__ import annotations
+

agent_data_cli/__main__.py

@@ -0,0 +1,7 @@
+from __future__ import annotations
+
+from .main import console_main
+
+
+if __name__ == "__main__":
+    console_main()

agent_data_cli/cli/__init__.py

@@ -0,0 +1,2 @@
+from __future__ import annotations
+

agent_data_cli/cli/__main__.py

@@ -0,0 +1,7 @@
+from __future__ import annotations
+
+from .main import console_main
+
+
+if __name__ == "__main__":
+    console_main()

agent_data_cli/cli/commands/__init__.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+from agent_data_cli.cli.commands.channel import CHANNEL_COMMAND
+from agent_data_cli.cli.commands.config import CONFIG_COMMAND
+from agent_data_cli.cli.commands.content import CONTENT_COMMAND
+from agent_data_cli.cli.commands.dashboard import DASHBOARD_COMMAND
+from agent_data_cli.cli.commands.group import GROUP_COMMAND
+from agent_data_cli.cli.commands.help import make_help_command
+from agent_data_cli.cli.commands.hub import HUB_COMMAND
+from agent_data_cli.cli.commands.init import INIT_COMMAND
+from agent_data_cli.cli.commands.source import SOURCE_COMMAND
+from agent_data_cli.cli.commands.specs import (
+    CommandContext,
+    CommandNodeSpec,
+    build_command_help_doc as _build_command_help_doc,
+    build_global_help_doc as _build_global_help_doc,
+    build_root_parser,
+    dispatch_command,
+    parse_command_argv,
+)
+from agent_data_cli.cli.commands.sub import SUB_COMMAND
+from agent_data_cli.core.help import HelpSection
+
+
+_BASE_COMMANDS: tuple[CommandNodeSpec, ...] = (
+    INIT_COMMAND,
+    HUB_COMMAND,
+    SOURCE_COMMAND,
+    CHANNEL_COMMAND,
+    CONTENT_COMMAND,
+    SUB_COMMAND,
+    GROUP_COMMAND,
+    CONFIG_COMMAND,
+    DASHBOARD_COMMAND,
+)
+
+GLOBAL_HELP_SECTIONS = (
+    HelpSection(
+        title="Examples",
+        lines=[
+            "init --defaults",
+            "hub search --query <query>",
+            "help content search",
+            "source list",
+            "channel search --source <source> --query <query>",
+            "content update --group <group> --dry-run",
+            "dashboard --daemon",
+        ],
+    ),
+)
+
+HELP_COMMAND = make_help_command(
+    build_global_help_doc=lambda: build_global_help_doc(),
+    build_command_help_doc=lambda topic: build_command_help_doc(topic),
+)
+
+ROOT_COMMANDS: tuple[CommandNodeSpec, ...] = (*_BASE_COMMANDS, HELP_COMMAND)
+
+
+def build_parser():
+    return build_root_parser(ROOT_COMMANDS)
+
+
+def build_global_help_doc():
+    return _build_global_help_doc(
+        title="agent-data-cli",
+        summary="Unified multi-source content CLI.",
+        commands=ROOT_COMMANDS,
+        sections=GLOBAL_HELP_SECTIONS,
+    )
+
+
+def build_command_help_doc(topic: str):
+    return _build_command_help_doc(ROOT_COMMANDS, topic)
+
+
+__all__ = [
+    "CommandContext",
+    "ROOT_COMMANDS",
+    "build_command_help_doc",
+    "build_global_help_doc",
+    "build_parser",
+    "dispatch_command",
+    "parse_command_argv",
+]

agent_data_cli/cli/commands/channel.py

@@ -0,0 +1,78 @@
+from __future__ import annotations
+
+from agent_data_cli.cli.formatters import build_channel_json_rows, print_channels, print_csv_rows, print_jsonl_rows
+from agent_data_cli.cli.commands.common import require_action, require_option, resolve_limit
+from agent_data_cli.cli.commands.specs import CommandArgSpec, CommandContext, CommandNodeSpec
+from agent_data_cli.core.help import HelpSection
+
+
+def _run_channel_list(args, extras: list[str], ctx: CommandContext) -> int:
+    _ = extras
+    source = ctx.registry.build(args.source)
+    require_action(ctx.registry, args.source, "channel.list")
+    print_channels(source.list_channels())
+    return 0
+
+
+def _run_channel_search(args, extras: list[str], ctx: CommandContext) -> int:
+    _ = extras
+    source = ctx.registry.build(args.source)
+    require_action(ctx.registry, args.source, "channel.search")
+    require_option(ctx.registry, args.source, "channel.search", "query")
+    if args.limit is not None:
+        require_option(ctx.registry, args.source, "channel.search", "limit")
+    limit = resolve_limit(args.limit)
+    channels = source.search_channels(query=args.query, limit=limit)
+    view = source.get_channel_search_view()
+    rows = build_channel_json_rows(channels, view=view)
+    if args.jsonl:
+        print_jsonl_rows(rows)
+        return 0
+    if args.csv:
+        print_csv_rows(rows)
+        return 0
+    print_channels(channels, view=view)
+    return 0
+
+
+CHANNEL_COMMAND = CommandNodeSpec(
+    name="channel",
+    summary="List or discover channels.",
+    child_dest="channel_command",
+    children=(
+        CommandNodeSpec(
+            name="list",
+            summary="List built-in channels for a source.",
+            arg_specs=(CommandArgSpec(names=("source",), value_name="source"),),
+            run=_run_channel_list,
+        ),
+        CommandNodeSpec(
+            name="search",
+            summary="Discover remote channels without persistence.",
+            sections=(
+                HelpSection(
+                    title="Semantics",
+                    lines=[
+                        "--source is required",
+                        "--query is required",
+                        "Returns channel results only and does not write to the local database",
+                    ],
+                ),
+                HelpSection(
+                    title="Examples",
+                    lines=[
+                        "channel search --source <source> --query <query> --limit <n>",
+                    ],
+                ),
+            ),
+            arg_specs=(
+                CommandArgSpec(names=("--source",), value_name="source", required=True),
+                CommandArgSpec(names=("--query",), value_name="query", required=True),
+                CommandArgSpec(names=("--limit",), value_name="n", type=int),
+                CommandArgSpec(names=("--jsonl",), action="store_true", exclusive_group="machine_output"),
+                CommandArgSpec(names=("--csv",), action="store_true", exclusive_group="machine_output"),
+            ),
+            run=_run_channel_search,
+        ),
+    ),
+)

agent_data_cli/cli/commands/common.py

@@ -0,0 +1,97 @@
+from __future__ import annotations
+
+from datetime import datetime
+
+from agent_data_cli.core.models import ActionAuditRecord
+from agent_data_cli.core.protocol import UnsupportedActionError
+from agent_data_cli.store.db import Store
+from agent_data_cli.utils.time import parse_since_expr, since_datetime_to_iso, utc_now_iso
+
+
+DEFAULT_LIMIT = 20
+
+
+def require_action(registry, source_name: str, action_id: str) -> None:
+    status = registry.get_resolver(source_name).action_status(action_id)
+    if status.status == "supported":
+        return
+    if status.status == "mode_unsupported":
+        raise RuntimeError(f"{source_name} {action_id} is not supported in current mode")
+    if status.status == "requires_config":
+        raise RuntimeError(f"{source_name} {action_id} requires config: {', '.join(status.missing_keys)}")
+    raise UnsupportedActionError(f"{source_name} does not support {action_id}")
+
+
+def require_option(registry, source_name: str, action_id: str, option_name: str) -> None:
+    status = registry.get_resolver(source_name).option_status(action_id, option_name)
+    if status.status == "supported":
+        return
+    if status.status == "mode_unsupported":
+        raise RuntimeError(f"{source_name} {action_id} option {option_name} is not supported in current mode")
+    if status.status == "requires_config":
+        raise RuntimeError(
+            f"{source_name} {action_id} {option_name} requires config: {', '.join(status.missing_keys)}"
+        )
+    raise RuntimeError(f"{source_name} does not support option {option_name} for {action_id}")
+
+
+def resolve_limit(raw_limit: int | None) -> int:
+    return DEFAULT_LIMIT if raw_limit is None else raw_limit
+
+
+def parse_since(raw_since: str) -> datetime:
+    from agent_data_cli.cli import main as cli_main
+
+    try:
+        return cli_main.parse_since_expr(raw_since)
+    except ValueError as exc:
+        raise RuntimeError(f"invalid --since value: {raw_since}") from exc
+
+
+def write_audit(
+    store: Store,
+    source,
+    *,
+    action: str,
+    target_kind: str,
+    targets: tuple[str, ...],
+    dry_run: bool,
+    params_summary: str,
+    status: str,
+    error: str | None,
+) -> None:
+    store.insert_action_audit(
+        ActionAuditRecord(
+            executed_at=utc_now_iso(),
+            action=action,
+            source=source.name,
+            mode=source.resolve_mode() or None,
+            target_kind=target_kind,
+            targets=targets,
+            params_summary=params_summary,
+            status=status,
+            error=error,
+            dry_run=dry_run,
+        )
+    )
+
+
+def summarize_update_params(*, limit: int | None, since: datetime | None, fetch_all: bool) -> str:
+    parts = []
+    if limit is not None:
+        parts.append(f"limit={limit}")
+    if since is not None:
+        parts.append(f"since={since_datetime_to_iso(since)}")
+    if fetch_all:
+        parts.append("all=1")
+    return ",".join(parts)
+
+
+def summarize_interact_params(verb: str, params: dict[str, object]) -> str:
+    parts = [f"verb={verb}"]
+    for key in sorted(params):
+        value = params[key]
+        if value in (None, False, [], ""):
+            continue
+        parts.append(f"{key}={value}")
+    return ",".join(parts)

agent_data_cli/cli/commands/config.py

@@ -0,0 +1,270 @@
+from __future__ import annotations
+
+from agent_data_cli.cli.formatters import print_cli_config_entries, print_config_check, print_config_entries
+from agent_data_cli.cli.commands.specs import CommandArgSpec, CommandContext, CommandNodeSpec
+from agent_data_cli.core.config import validate_config_value
+from agent_data_cli.core.help import HelpSection
+from agent_data_cli.core.manifest import CORE_ACTION_NAMES, SOURCE_ACTION_NAMES
+from agent_data_cli.migration import migrate_home, migrate_source_workspace
+from agent_data_cli.runtime_paths import RuntimePaths, resolve_runtime_paths
+from agent_data_cli.store.db import Store
+
+
+CONFIG_CHECK_ACTION_IDS = CORE_ACTION_NAMES | SOURCE_ACTION_NAMES
+
+
+def _run_config_cli_list(args, extras: list[str], ctx: CommandContext) -> int:
+    _ = args, extras
+    _print_cli_config_entries(ctx)
+    return 0
+
+
+def _run_config_cli_set(args, extras: list[str], ctx: CommandContext) -> int:
+    _ = extras
+    spec = ctx.registry.get_cli_config_field_spec(args.key)
+    validate_config_value(spec, args.value, owner="cli")
+    current_paths = _resolve_active_runtime_paths(ctx)
+    if args.key == "home":
+        migrated_paths = migrate_home(current_paths, args.value)
+        _print_cli_config_entries_with_paths(ctx, migrated_paths)
+        return 0
+    if args.key == "source_workspace":
+        migrated_paths = migrate_source_workspace(current_paths, args.value)
+        _print_cli_config_entries_with_paths(ctx, migrated_paths)
+        return 0
+    ctx.store.set_cli_config(args.key, args.value, spec.type, spec.secret)
+    _print_cli_config_entries_with_paths(ctx, current_paths)
+    return 0
+
+
+def _run_config_cli_unset(args, extras: list[str], ctx: CommandContext) -> int:
+    _ = extras
+    ctx.store.unset_cli_config(args.key)
+    _print_cli_config_entries_with_paths(ctx, _resolve_active_runtime_paths(ctx))
+    return 0
+
+
+def _run_config_cli_explain(args, extras: list[str], ctx: CommandContext) -> int:
+    _ = extras
+    _print_config_explain("cli", ctx.registry.get_cli_config_field_spec(args.key))
+    return 0
+
+
+def _run_config_source_list(args, extras: list[str], ctx: CommandContext) -> int:
+    _ = extras
+    print_config_entries(ctx.store.list_source_configs(args.source))
+    return 0
+
+
+def _run_config_source_set(args, extras: list[str], ctx: CommandContext) -> int:
+    _ = extras
+    spec = ctx.registry.get_source_config_field_spec(args.source, args.key)
+    validate_config_value(spec, args.value, owner=args.source)
+    ctx.store.set_source_config(args.source, args.key, args.value, spec.type, spec.secret)
+    print_config_entries(ctx.store.list_source_configs(args.source))
+    return 0
+
+
+def _run_config_source_unset(args, extras: list[str], ctx: CommandContext) -> int:
+    _ = extras
+    ctx.store.unset_source_config(args.source, args.key)
+    print_config_entries(ctx.store.list_source_configs(args.source))
+    return 0
+
+
+def _run_config_source_explain(args, extras: list[str], ctx: CommandContext) -> int:
+    _ = extras
+    _print_config_explain(args.source, ctx.registry.get_source_config_field_spec(args.source, args.key))
+    return 0
+
+
+def _run_config_source_check(args, extras: list[str], ctx: CommandContext) -> int:
+    _ = extras
+    _validate_config_check_action_id(args.action_id)
+    if args.action_id == "content.interact" and not args.verb:
+        raise RuntimeError("config source check --for content.interact requires --verb")
+    print_config_check(ctx.registry.config_check(args.source, action_id=args.action_id, verb=args.verb))
+    return 0
+
+
+def _print_config_explain(owner: str, spec) -> None:
+    print(f"{owner}.{spec.key}")
+    print(f"type: {spec.type}")
+    print(f"secret: {int(spec.secret)}")
+    print(f"description: {spec.description}")
+    if spec.inherits_from_cli:
+        print(f"inherits_from_cli: {spec.inherits_from_cli}")
+    if spec.choices:
+        print(f"choices: {', '.join(spec.choices)}")
+    if spec.obtain_hint:
+        print(f"obtain_hint: {spec.obtain_hint}")
+    if spec.example:
+        print(f"example: {spec.example}")
+
+
+def _print_cli_config_entries(ctx: CommandContext) -> None:
+    _print_cli_config_entries_with_paths(ctx, _resolve_active_runtime_paths(ctx))
+
+
+def _print_cli_config_entries_with_paths(ctx: CommandContext, paths: RuntimePaths) -> None:
+    store = ctx.store
+    if str(paths.db_path) != getattr(ctx.store, "path", "") and paths.db_path.exists():
+        store = Store(str(paths.db_path))
+    defaults_by_key = {
+        spec.key: ctx.registry.get_cli_config_default(spec.key)
+        for spec in ctx.registry.get_cli_config_specs()
+    }
+    defaults_by_key["home"] = str(paths.home)
+    defaults_by_key["source_workspace"] = str(paths.source_workspace)
+    print_cli_config_entries(
+        ctx.registry.get_cli_config_specs(),
+        store.list_cli_configs(),
+        defaults_by_key,
+    )
+
+
+def _resolve_active_runtime_paths(ctx: CommandContext) -> RuntimePaths:
+    paths = resolve_runtime_paths()
+    source_workspace_entry = ctx.store.get_cli_config_map().get("source_workspace")
+    if source_workspace_entry is None:
+        return paths
+    return RuntimePaths(
+        home=paths.home,
+        db_path=paths.db_path,
+        source_workspace=resolve_runtime_paths(source_workspace_override=source_workspace_entry.value).source_workspace,
+        runtime_dir=paths.runtime_dir,
+        launcher_path=paths.launcher_path,
+    )
+
+
+def _validate_config_check_action_id(action_id: str | None) -> None:
+    if action_id is None:
+        return
+    if action_id not in CONFIG_CHECK_ACTION_IDS:
+        raise RuntimeError(f"unknown action id: {action_id}")
+
+
+CONFIG_COMMAND = CommandNodeSpec(
+    name="config",
+    summary="Inspect and modify CLI or source configuration.",
+    sections=(
+        HelpSection(
+            title="Scopes",
+            lines=[
+                "config cli ... manages ADC-level settings",
+                "config source ... manages one source's settings",
+            ],
+        ),
+        HelpSection(
+            title="Common Commands",
+            lines=[
+                "config cli list",
+                "config cli explain <key>",
+                "config cli set <key> <value>",
+                "config cli unset <key>",
+                "config source list <source>",
+                "config source explain <source> <key>",
+                "config source set <source> <key> <value>",
+                "config source unset <source> <key>",
+                "config source check <source> [--for <action-id>] [--verb <verb>]",
+            ],
+        ),
+        HelpSection(
+            title="Typical Flow",
+            lines=[
+                "List current values first",
+                "Use explain before setting a key you do not recognize",
+                "Set the value",
+                "Run config source check when a source action still says it requires config",
+            ],
+        ),
+    ),
+    child_dest="config_scope",
+    children=(
+        CommandNodeSpec(
+            name="cli",
+            summary="Manage CLI-level configuration.",
+            child_dest="config_command",
+            children=(
+                CommandNodeSpec(
+                    name="list",
+                    summary="List CLI configuration.",
+                    run=_run_config_cli_list,
+                ),
+                CommandNodeSpec(
+                    name="set",
+                    summary="Set a CLI configuration value.",
+                    arg_specs=(
+                        CommandArgSpec(names=("key",), value_name="key"),
+                        CommandArgSpec(names=("value",), value_name="value"),
+                    ),
+                    run=_run_config_cli_set,
+                ),
+                CommandNodeSpec(
+                    name="unset",
+                    summary="Unset a CLI configuration value.",
+                    arg_specs=(CommandArgSpec(names=("key",), value_name="key"),),
+                    run=_run_config_cli_unset,
+                ),
+                CommandNodeSpec(
+                    name="explain",
+                    summary="Explain a CLI configuration field.",
+                    arg_specs=(CommandArgSpec(names=("key",), value_name="key"),),
+                    run=_run_config_cli_explain,
+                ),
+            ),
+        ),
+        CommandNodeSpec(
+            name="source",
+            summary="Manage source configuration.",
+            child_dest="config_command",
+            children=(
+                CommandNodeSpec(
+                    name="list",
+                    summary="List configuration for a source.",
+                    arg_specs=(CommandArgSpec(names=("source",), value_name="source"),),
+                    run=_run_config_source_list,
+                ),
+                CommandNodeSpec(
+                    name="set",
+                    summary="Set a source configuration value.",
+                    arg_specs=(
+                        CommandArgSpec(names=("source",), value_name="source"),
+                        CommandArgSpec(names=("key",), value_name="key"),
+                        CommandArgSpec(names=("value",), value_name="value"),
+                    ),
+                    run=_run_config_source_set,
+                ),
+                CommandNodeSpec(
+                    name="unset",
+                    summary="Unset a source configuration value.",
+                    arg_specs=(
+                        CommandArgSpec(names=("source",), value_name="source"),
+                        CommandArgSpec(names=("key",), value_name="key"),
+                    ),
+                    run=_run_config_source_unset,
+                ),
+                CommandNodeSpec(
+                    name="explain",
+                    summary="Explain a source configuration field.",
+                    arg_specs=(
+                        CommandArgSpec(names=("source",), value_name="source"),
+                        CommandArgSpec(names=("key",), value_name="key"),
+                    ),
+                    run=_run_config_source_explain,
+                ),
+                CommandNodeSpec(
+                    name="check",
+                    summary="Check configuration status for a source.",
+                    usage_override="config source check <source> [--for <action-id>] [--verb <verb>]",
+                    arg_specs=(
+                        CommandArgSpec(names=("source",), value_name="source"),
+                        CommandArgSpec(names=("--for",), value_name="action-id", dest="action_id"),
+                        CommandArgSpec(names=("--verb",), value_name="verb"),
+                    ),
+                    run=_run_config_source_check,
+                ),
+            ),
+        ),
+    ),
+)

agent_data_cli/cli/commands/content/__init__.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+from agent_data_cli.cli.commands.content.interact import CONTENT_INTERACT_COMMAND, run_content_interact
+from agent_data_cli.cli.commands.content.query import CONTENT_QUERY_COMMAND, run_content_query
+from agent_data_cli.cli.commands.content.search import CONTENT_SEARCH_COMMAND, run_content_search
+from agent_data_cli.cli.commands.content.update import CONTENT_UPDATE_COMMAND, run_content_update
+from agent_data_cli.cli.commands.specs import CommandNodeSpec
+
+
+CONTENT_COMMAND = CommandNodeSpec(
+    name="content",
+    summary="Unified content operations.",
+    child_dest="content_command",
+    children=(
+        CONTENT_SEARCH_COMMAND,
+        CONTENT_UPDATE_COMMAND,
+        CONTENT_QUERY_COMMAND,
+        CONTENT_INTERACT_COMMAND,
+    ),
+)
+
+
+__all__ = [
+    "CONTENT_COMMAND",
+    "run_content_interact",
+    "run_content_query",
+    "run_content_search",
+    "run_content_update",
+]