agentirc-cli 7.3.0__tar.gz → 7.4.0__tar.gz

{agentirc_cli-7.3.0 → agentirc_cli-7.4.0}/CHANGELOG.md

@@ -4,6 +4,14 @@ All notable changes to this project will be documented in this file.
 
 Format follows [Keep a Changelog](https://keepachangelog.com/).
 
+## [7.4.0] - 2026-04-22
+
+### Added
+
+- culture agex passthrough to the standalone agex CLI (new subcommand embedding agex via typer)
+- Universal verbs culture explain, culture overview, culture learn at the CLI root, with a per-topic handler registry (culture/cli/introspect.py)
+- agex-cli>=0.13,<1.0 as a library dependency
+
 ## [7.3.0] - 2026-04-21
 
 ### Added

{agentirc_cli-7.3.0 → agentirc_cli-7.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentirc-cli
-Version: 7.3.0
+Version: 7.4.0
 Summary: Legacy alias for culture — install culture instead
 Project-URL: Homepage, https://github.com/OriNachum/culture
 Author: Ori Nachum
@@ -12,6 +12,7 @@ Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Communications :: Chat :: Internet Relay Chat
 Requires-Python: >=3.12
+Requires-Dist: agex-cli<1.0,>=0.13
 Requires-Dist: aiohttp>=3.9
 Requires-Dist: anthropic>=0.40
 Requires-Dist: claude-agent-sdk>=0.1

{agentirc_cli-7.3.0 → agentirc_cli-7.4.0}/_config.culture.yml

@@ -36,6 +36,8 @@ aux_links:
     - "/agentirc/"
   "Agent Experience":
     - "https://culture.dev/agex/"
+  "Citation CLI":
+    - "/citation-cli/"
   "GitHub":
     - "https://github.com/OriNachum/culture"
 
@@ -45,4 +47,5 @@ footer_content: >-
   Culture — human-agent collaboration built around
   <a href="/agentirc/">AgentIRC</a>.
   Agent Experience via <a href="https://culture.dev/agex/">agex-cli</a>.
+  Code distribution via <a href="/citation-cli/">Citation CLI</a>.
   Source on <a href="https://github.com/OriNachum/culture">GitHub</a>.

{agentirc_cli-7.3.0 → agentirc_cli-7.4.0}/_data/sites.yml

@@ -1,3 +1,4 @@
 agentirc: https://culture.dev/agentirc/
 agex: https://culture.dev/agex/
+citation_cli: https://culture.dev/citation-cli/
 culture: https://culture.dev

{agentirc_cli-7.3.0 → agentirc_cli-7.4.0}/_includes/head_custom.html

@@ -4,3 +4,4 @@
 <link rel="icon" type="image/png" sizes="16x16" href="{{ '/assets/images/favicon-16x16.png' | relative_url }}">
 <link rel="apple-touch-icon" sizes="180x180" href="{{ '/assets/images/apple-touch-icon.png' | relative_url }}">
 <link rel="related" href="{{ site.data.sites.agex }}" title="Agent Experience">
+<link rel="related" href="{{ site.data.sites.citation_cli }}" title="Citation CLI">

{agentirc_cli-7.3.0 → agentirc_cli-7.4.0}/culture/cli/__init__.py

@@ -7,6 +7,12 @@ Commands are organized into noun-based groups:
     culture channel  {list,read,message,who}
     culture bot      {create,start,stop,list,inspect,archive,unarchive}
     culture skills   {install}
+    culture agex     {...full passthrough to the standalone `agex` CLI...}
+
+Universal verbs (available at the root):
+    culture explain [topic]    full description of topic (default: culture)
+    culture overview [topic]   shallow summary
+    culture learn [topic]      agent-facing onboarding prompt
 """
 
 from __future__ import annotations
@@ -16,9 +22,16 @@ import logging
 import sys
 
 from culture import __version__
-from culture.cli import agent, bot, channel, mesh, server, skills
+from culture.cli import agent, agex, bot, channel, introspect, mesh, server, skills
+
+GROUPS = [agent, server, mesh, channel, bot, skills, agex, introspect]
+
 
-GROUPS = [agent, server, mesh, channel, bot, skills]
+def _names_of(group) -> set[str]:
+    names = getattr(group, "NAMES", None)
+    if names is not None:
+        return set(names)
+    return {group.NAME}
 
 
 def _build_parser() -> argparse.ArgumentParser:
@@ -48,7 +61,7 @@ def main() -> None:
 
     try:
         for group in GROUPS:
-            if args.command == group.NAME:
+            if args.command in _names_of(group):
                 group.dispatch(args)
                 return
         parser.print_help()

agentirc_cli-7.4.0/culture/cli/agex.py

@@ -0,0 +1,101 @@
+"""`culture agex` — passthrough to the standalone agex CLI.
+
+Also registers universal-verb handlers for the ``agex`` topic so
+``culture explain agex`` / ``culture overview agex`` / ``culture learn agex``
+route through culture's universal-verb path.
+"""
+
+from __future__ import annotations
+
+import argparse
+import contextlib
+import io
+import sys
+
+from culture.cli import introspect
+
+NAME = "agex"
+
+
+def _run_agex(argv: list[str]) -> None:
+    """Invoke agex's typer app in-process.
+
+    Uses standalone_mode=True (the typer default) so typer's own --help,
+    --version, and Exit handling work unchanged. Typer calls ``sys.exit``
+    when done, raising ``SystemExit``; this function lets that propagate
+    so the caller (the ``culture agex`` passthrough) exits with the code
+    the user expects. Callers that need to capture output and translate
+    the exit into a return value should use :func:`_capture_agex` instead.
+    """
+    try:
+        from agent_experience.cli import app
+    except ImportError as exc:  # pragma: no cover — declared dep
+        print(f"agex-cli is not installed: {exc}", file=sys.stderr)
+        sys.exit(2)
+    app(args=argv)
+
+
+def _capture_agex(argv: list[str]) -> tuple[str, int]:
+    """Run agex with stdout + stderr captured, translating SystemExit.
+
+    The universal-verb handlers need ``(output, exit_code)`` rather than a
+    process-level exit, so we deliberately catch ``SystemExit`` here and
+    translate it into a return value. The :func:`_run_agex` variant is for
+    the passthrough path where the exit must propagate.
+    """
+    buf = io.StringIO()
+    try:
+        with contextlib.redirect_stdout(buf), contextlib.redirect_stderr(buf):
+            _run_agex(argv)
+    except SystemExit as exc:  # NOSONAR S5754 — see docstring
+        code = exc.code
+        if code is None:
+            return buf.getvalue(), 0
+        if isinstance(code, int):
+            return buf.getvalue(), code
+        return buf.getvalue() + str(code), 1
+    return buf.getvalue(), 0
+
+
+# --- universal-verb topic handlers for ``agex`` ---------------------------
+
+
+def _agex_explain(_topic: str | None) -> tuple[str, int]:
+    return _capture_agex(["explain", "agex"])
+
+
+def _agex_overview(_topic: str | None) -> tuple[str, int]:
+    return _capture_agex(["overview", "--agent", "claude-code"])
+
+
+def _agex_learn(_topic: str | None) -> tuple[str, int]:
+    return _capture_agex(["learn", "--agent", "claude-code"])
+
+
+introspect.register_topic(
+    "agex",
+    explain=_agex_explain,
+    overview=_agex_overview,
+    learn=_agex_learn,
+)
+
+
+# --- CLI group protocol ---------------------------------------------------
+
+
+def register(subparsers: "argparse._SubParsersAction") -> None:
+    # prefix_chars=chr(0) means the agex subparser has no recognized flag
+    # prefix character, so every token (including --help, --version) is
+    # treated as positional and captured in agex_args for typer to handle.
+    p = subparsers.add_parser(
+        NAME,
+        help="Run agex (agent-experience CLI) via passthrough",
+        add_help=False,
+        prefix_chars=chr(0),
+    )
+    p.add_argument("agex_args", nargs=argparse.REMAINDER, help="Arguments passed to agex")
+
+
+def dispatch(args: argparse.Namespace) -> None:
+    rest = list(getattr(args, "agex_args", []) or [])
+    _run_agex(rest)

agentirc_cli-7.4.0/culture/cli/introspect.py

@@ -0,0 +1,166 @@
+"""Universal introspection verb dispatcher.
+
+Registers three top-level verbs (``explain``, ``overview``, ``learn``)
+on the culture CLI and dispatches each to a per-topic handler.
+
+The module conforms to the extended culture CLI group protocol:
+exports ``NAMES`` (frozenset) instead of the singular ``NAME``.
+"""
+
+from __future__ import annotations
+
+import argparse
+import logging
+from typing import Callable
+
+_log = logging.getLogger(__name__)
+
+Handler = Callable[[str | None], tuple[str, int]]
+
+NAMES = frozenset({"explain", "overview", "learn"})
+
+_explain: dict[str, Handler] = {}
+_overview: dict[str, Handler] = {}
+_learn: dict[str, Handler] = {}
+
+_REGISTRIES: dict[str, dict[str, Handler]] = {
+    "explain": _explain,
+    "overview": _overview,
+    "learn": _learn,
+}
+
+
+def register_topic(
+    topic: str,
+    *,
+    explain: Handler | None = None,
+    overview: Handler | None = None,
+    learn: Handler | None = None,
+) -> None:
+    """Register handlers for a topic. Any verb may be omitted.
+
+    Re-registration is last-write-wins; a warning is logged when an existing
+    handler is overwritten so accidental double-registration is visible at
+    culture's default INFO log level.
+    """
+    for verb, handler, registry in (
+        ("explain", explain, _explain),
+        ("overview", overview, _overview),
+        ("learn", learn, _learn),
+    ):
+        if handler is None:
+            continue
+        if topic in registry:
+            _log.warning("overriding %s handler for topic %r", verb, topic)
+        registry[topic] = handler
+
+
+def _clear_registry() -> None:
+    """Test-only: wipe all registries, then re-register the root handlers."""
+    _explain.clear()
+    _overview.clear()
+    _learn.clear()
+    _register_root()
+
+
+def _resolve(verb: str, topic: str | None) -> tuple[str, int]:
+    registry = _REGISTRIES[verb]
+    effective = topic if topic is not None else "culture"
+    handler = registry.get(effective)
+    if handler is None:
+        available = sorted(registry.keys())
+        msg = (
+            f"unknown topic '{effective}' for {verb};"
+            f" available: {', '.join(available) or '(none)'}"
+        )
+        return msg, 1
+    return handler(topic)
+
+
+def explain(topic: str | None) -> tuple[str, int]:
+    return _resolve("explain", topic)
+
+
+def overview(topic: str | None) -> tuple[str, int]:
+    return _resolve("overview", topic)
+
+
+def learn(topic: str | None) -> tuple[str, int]:
+    return _resolve("learn", topic)
+
+
+_NAMESPACES = ("agex", "server", "agent", "mesh", "bot", "channel", "skills")
+
+
+def _culture_explain(_topic: str | None) -> tuple[str, int]:
+    lines = [
+        "# Culture",
+        "",
+        "Culture is the framework of agreements that makes agent behavior",
+        "portable, inspectable, and effective. It hosts a mesh of IRC servers",
+        "where AI agents collaborate, share knowledge, and coordinate work.",
+        "",
+        "## Namespaces",
+        "",
+    ]
+    for ns in _NAMESPACES:
+        registered = any(ns in registry for registry in _REGISTRIES.values())
+        marker = "" if registered else "  (coming soon)"
+        lines.append(f"- `culture {ns}`{marker}")
+    lines.append("")
+    lines.append("## Universal verbs")
+    lines.append("")
+    lines.append("- `culture explain [topic]` — deep description")
+    lines.append("- `culture overview [topic]` — shallow map")
+    lines.append("- `culture learn [topic]` — agent onboarding prompt")
+    return "\n".join(lines) + "\n", 0
+
+
+def _culture_overview(_topic: str | None) -> tuple[str, int]:
+    return (
+        "Culture: agent IRC mesh. Namespaces: "
+        + ", ".join(_NAMESPACES)
+        + ". Universal verbs: explain, overview, learn.\n",
+        0,
+    )
+
+
+def _culture_learn(_topic: str | None) -> tuple[str, int]:
+    from culture.learn_prompt import generate_learn_prompt
+
+    return generate_learn_prompt(), 0
+
+
+def _register_root() -> None:
+    register_topic(
+        "culture",
+        explain=_culture_explain,
+        overview=_culture_overview,
+        learn=_culture_learn,
+    )
+
+
+_register_root()
+
+
+# --- CLI group protocol ---------------------------------------------------
+
+
+def register(subparsers: "argparse._SubParsersAction") -> None:
+    for verb in ("explain", "overview", "learn"):
+        p = subparsers.add_parser(verb, help=f"{verb.capitalize()} a topic (culture by default)")
+        p.add_argument("topic", nargs="?", default=None, help="Topic to inspect")
+
+
+def dispatch(args: argparse.Namespace) -> None:
+    import sys
+
+    verb = args.command
+    topic = getattr(args, "topic", None)
+    stdout, code = _resolve(verb, topic)
+    if stdout:
+        stream = sys.stdout if code == 0 else sys.stderr
+        end = "" if stdout.endswith("\n") else "\n"
+        print(stdout, end=end, file=stream)
+    if code != 0:
+        sys.exit(code)

agentirc_cli-7.4.0/docs/reference/cli/agex.md

@@ -0,0 +1,103 @@
+---
+title: "culture agex"
+parent: "CLI"
+grand_parent: "Reference"
+nav_order: 10
+sites: [agentirc, culture]
+description: "Agex passthrough and universal introspection verbs."
+permalink: /reference/cli/agex/
+---
+
+# `culture agex` and universal verbs
+
+Culture ships [agex](https://agex.culture.dev) as a first-class
+citizen. Two affordances:
+
+## `culture agex <anything>`
+
+A full passthrough to the standalone [`agex`](https://agex.culture.dev) CLI.
+Everything after `culture agex` is forwarded verbatim to agex's typer app.
+Exit codes propagate.
+
+```bash
+culture agex --version
+culture agex explain agex
+culture agex overview --agent claude-code
+culture agex learn --agent claude-code
+```
+
+`culture agex --help` shows agex's help, not culture's.
+
+## Universal verbs: `explain` / `overview` / `learn`
+
+Three verbs live at the root of the culture command tree. Each takes an
+optional `topic`; when omitted, the topic defaults to `culture`.
+
+| Verb | Meaning |
+|------|---------|
+| `explain X` | Full description of X and everything under X (deep) |
+| `overview X` | Summary of X (shallow map view) |
+| `learn X` | Agent-facing onboarding prompt for operating X |
+
+```bash
+culture explain           # describes culture + its namespaces
+culture explain agex      # routes to agex explain
+culture overview          # culture map
+culture learn             # agent onboarding prompt for culture
+culture learn agex        # agent onboarding for agex
+```
+
+`learn` produces an agent-facing self-teaching prompt so an agent doesn't
+have to re-explore a tool every time. This matches agex's `agex learn`
+verb semantically.
+
+## Each namespace owns its own
+
+Culture is pure plumbing: a tiny internal dispatcher
+(`culture/cli/introspect.py`) maps topics to handlers. Each namespace that
+wants to participate registers its own handlers on import. For `agex`,
+the agex-cli library already implements the three verbs — culture just
+routes. Native namespaces (`mesh`, `server`, `agent`, …) will add their
+own handlers in a future release.
+
+## For namespace authors
+
+A new namespace plugs into the universal verbs by calling
+`introspect.register_topic(...)` at module import time:
+
+```python
+# culture/cli/mycmd.py
+from culture.cli import introspect
+
+
+def _explain(_topic):
+    return "markdown describing mycmd ...\n", 0
+
+
+def _overview(_topic):
+    return "one-line summary of mycmd\n", 0
+
+
+def _learn(_topic):
+    return "agent onboarding prompt for mycmd\n", 0
+
+
+introspect.register_topic(
+    "mycmd",
+    explain=_explain,
+    overview=_overview,
+    learn=_learn,
+)
+```
+
+Each handler has signature `Handler = Callable[[str | None], tuple[str, int]]` —
+it receives the topic (may be `None`) and returns `(stdout, exit_code)`.
+
+### CLI group protocol: `NAME` vs `NAMES`
+
+A normal group module (e.g. `server`, `agent`) exports a singular
+`NAME: str` — the subcommand noun. A group that owns multiple top-level
+verbs (e.g. `introspect`, which owns all three of `explain`/`overview`/
+`learn`) exports a plural `NAMES: frozenset[str]` instead. The dispatch
+loop in `culture/cli/__init__.py` honors both — `NAMES` takes priority
+with `{NAME}` as the fallback — so most groups only need `NAME`.

{agentirc_cli-7.3.0 → agentirc_cli-7.4.0}/docs/reference/cli/index.md

@@ -391,3 +391,13 @@ culture bot unarchive spark-ori-ghci
 
 All commands use `~/.culture/server.yaml` by default. Override with `--config`.
 The legacy `~/.culture/agents.yaml` format is still supported; use `culture agent migrate` to convert.
+
+## Universal verbs
+
+Available at the root of the command tree. See
+[`culture agex`](./agex/) for detail.
+
+- `culture explain [topic]` — deep description
+- `culture overview [topic]` — shallow summary
+- `culture learn [topic]` — agent onboarding prompt
+- `culture agex <anything>` — passthrough to the agex CLI