agentlings 0.2.0__py3-none-any.whl

agentlings/__init__.py

@@ -0,0 +1,3 @@
+"""Agentlings — lightweight A2A + MCP single-process agent framework."""
+
+__version__ = "0.1.0"

agentlings/__main__.py

@@ -0,0 +1,238 @@
+"""CLI entry point: subcommand router for ``agentling``.
+
+Subcommands:
+
+- ``run`` (default)  — start the agent server using ``agent.yaml``/``.env`` from CWD or ``--dir``
+- ``init <name>``    — scaffold a new agent directory
+- ``upgrade``        — apply pending data migrations, advance the framework-version stamp
+- ``memory show``    — print the current memory store
+- ``sleep [--date]`` — run a sleep cycle for the agent in CWD
+- ``--list-tools``   — print bundled tool registry
+
+``--dir <PATH>`` works on ``run`` and ``upgrade`` to operate on a directory
+other than CWD.
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import os
+import sys
+from pathlib import Path
+
+
+def main() -> None:
+    """Entry-point dispatcher for the ``agentling`` console script."""
+    parser = _build_parser()
+    args = parser.parse_args()
+
+    if getattr(args, "legacy_list_tools", False):
+        _list_tools()
+        return
+    if args.command in (None, "run"):
+        _run(getattr(args, "dir", None))
+    elif args.command == "init":
+        _init(args)
+    elif args.command == "upgrade":
+        _upgrade(args)
+    elif args.command == "memory":
+        _memory_command(args.subcommand)
+    elif args.command == "sleep":
+        _sleep_command(args.date)
+    elif args.command == "list-tools":
+        _list_tools()
+    else:
+        parser.print_help()
+        sys.exit(2)
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="agentling", description=__doc__)
+    sub = parser.add_subparsers(dest="command")
+
+    run_p = sub.add_parser("run", help="start the agent server (default if no subcommand)")
+    run_p.add_argument("--dir", type=Path, default=None, help="agent directory (defaults to CWD)")
+
+    init_p = sub.add_parser("init", help="scaffold a new agent directory")
+    init_p.add_argument("name", help="agent name (also default directory name)")
+    init_p.add_argument("--dir", type=Path, default=None, help="output directory (default: ./<name>)")
+    init_p.add_argument("--template", default="default", help="bundled template to scaffold from")
+    init_p.add_argument("--api-key", default=None, help="AGENT_API_KEY value (auto-generated if omitted)")
+    init_p.add_argument("--anthropic-api-key", default=None, help="pre-populate ANTHROPIC_API_KEY")
+    init_p.add_argument("--anthropic-base-url", default=None, help="pre-populate ANTHROPIC_BASE_URL")
+    init_p.add_argument("--force", action="store_true", help="overwrite an existing non-empty directory")
+
+    upg_p = sub.add_parser("upgrade", help="apply data migrations against the installed framework")
+    upg_p.add_argument("--dir", type=Path, default=None, help="agent directory (defaults to CWD)")
+    upg_p.add_argument("--dry-run", action="store_true", help="report pending migrations without running them")
+
+    mem_p = sub.add_parser("memory", help="memory store inspection")
+    mem_p.add_argument("subcommand", choices=["show"])
+
+    slp_p = sub.add_parser("sleep", help="run a one-off sleep cycle")
+    slp_p.add_argument("--date", default=None, help="YYYY-MM-DD (defaults to today)")
+
+    sub.add_parser("list-tools", help="print bundled tool registry")
+
+    # Back-compat: older docs and habits use `--list-tools` at top level.
+    parser.add_argument("--list-tools", dest="legacy_list_tools", action="store_true", help=argparse.SUPPRESS)
+
+    return parser
+
+
+def _run(agent_dir: Path | None) -> None:
+    """Run the server with optional directory pinning.
+
+    Sets ``AGENT_CONFIG`` and ``AGENT_DATA_DIR`` to point at the directory's
+    artefacts before constructing ``AgentConfig``. The ``.env`` file inside
+    the directory is loaded by ``pydantic-settings`` automatically because
+    we change CWD before AgentConfig is created.
+    """
+    if agent_dir is not None:
+        target = agent_dir.resolve()
+        os.environ.setdefault("AGENT_CONFIG", str(target / "agent.yaml"))
+        os.environ.setdefault("AGENT_DATA_DIR", str(target / "data"))
+        os.chdir(target)
+
+    from agentlings.server import run
+
+    run()
+
+
+def _init(args: argparse.Namespace) -> None:
+    from agentlings.cli.init import init_agent
+
+    try:
+        result = init_agent(
+            args.name,
+            dir=args.dir,
+            template=args.template,
+            api_key=args.api_key,
+            anthropic_api_key=args.anthropic_api_key,
+            anthropic_base_url=args.anthropic_base_url,
+            force=args.force,
+        )
+    except (FileExistsError, ValueError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        sys.exit(1)
+
+    print(f"created agent at {result.agent_dir}")
+    print(f"  template:          {result.template}")
+    print(f"  framework version: {result.framework_version}")
+    print(f"  generated AGENT_API_KEY (rotate by editing .env)")
+    print()
+    print("next steps:")
+    print(f"  cd {result.agent_dir}")
+    print("  # add ANTHROPIC_API_KEY to .env if you need it")
+    print("  agentling run")
+
+
+def _upgrade(args: argparse.Namespace) -> None:
+    from agentlings.cli.upgrade import upgrade_agent
+
+    try:
+        result = upgrade_agent(args.dir, dry_run=args.dry_run)
+    except (FileNotFoundError, RuntimeError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        sys.exit(1)
+
+    print(f"recorded version:  {result.recorded_version or '(none)'}")
+    print(f"installed version: {result.installed_version}")
+    if not result.applied:
+        print("no migrations to apply.")
+        return
+    label = "would apply" if args.dry_run else "applied"
+    for m in result.applied:
+        print(f"  {label} {m.id}: {m.description}")
+
+
+def _list_tools() -> None:
+    from agentlings.tools.builtins import BUILTIN_REGISTRY
+    from agentlings.tools.memory import MEMORY_TOOL_DEFINITION
+    from agentlings.tools.registry import TOOL_GROUPS
+
+    print("Available tool groups:\n")
+    all_tools = {**BUILTIN_REGISTRY, MEMORY_TOOL_DEFINITION["name"]: MEMORY_TOOL_DEFINITION}
+    for group, tools in TOOL_GROUPS.items():
+        print(f"  {group}")
+        for tool in tools:
+            desc = all_tools.get(tool, {}).get("description", "")
+            print(f"    {tool:20s} {desc}")
+        print()
+
+    standalone = set(all_tools.keys())
+    for tools in TOOL_GROUPS.values():
+        standalone -= set(tools)
+    if standalone:
+        print("Standalone tools:\n")
+        for name in sorted(standalone):
+            desc = all_tools.get(name, {}).get("description", "")
+            print(f"  {name:22s} {desc}")
+        print()
+
+    print("Enable via agent YAML 'tools' list or AGENT_TOOLS env var.")
+    print("Examples:")
+    print("  tools: [bash, filesystem, memory]")
+
+
+def _memory_command(subcommand: str) -> None:
+    if subcommand != "show":
+        print("Usage: agentling memory show", file=sys.stderr)
+        sys.exit(1)
+
+    from agentlings.config import AgentConfig
+    from agentlings.core.memory_store import MemoryFileStore
+
+    config = AgentConfig()
+    store = MemoryFileStore(config.agent_data_dir)
+    memory = store.load()
+
+    if not memory.entries:
+        print("Memory is empty.")
+        return
+
+    for entry in memory.entries:
+        print(f"  {entry.key}: {entry.value}")
+        print(f"    recorded: {entry.recorded.isoformat()}")
+
+
+def _sleep_command(date_str: str | None) -> None:
+    from datetime import datetime, timezone
+
+    date = None
+    if date_str:
+        try:
+            date = datetime.strptime(date_str, "%Y-%m-%d").replace(tzinfo=timezone.utc)
+        except ValueError:
+            print(f"Invalid date format: {date_str} (expected YYYY-MM-DD)", file=sys.stderr)
+            sys.exit(1)
+
+    from agentlings.config import AgentConfig
+    from agentlings.core.llm import create_llm_client
+    from agentlings.core.memory_store import MemoryFileStore
+    from agentlings.core.sleep import SleepCycle
+    from agentlings.core.store import JournalStore
+    from agentlings.log import setup_logging
+
+    config = AgentConfig()
+    setup_logging(config.agent_log_level)
+
+    memory_store = MemoryFileStore(config.agent_data_dir)
+    journal_store = JournalStore(config.agent_data_dir)
+    llm = create_llm_client(
+        backend=config.agent_llm_backend,
+        api_key=config.anthropic_api_key,
+        model=config.agent_model,
+        max_tokens=config.agent_max_tokens,
+        base_url=config.anthropic_base_url,
+    )
+
+    cycle = SleepCycle(
+        config=config, llm=llm, memory_store=memory_store, store=journal_store,
+    )
+    asyncio.run(cycle.run(date=date))
+
+
+if __name__ == "__main__":
+    main()

agentlings/cli/__init__.py

@@ -0,0 +1 @@
+"""Operator-facing CLI: scaffold, run, upgrade an agent directory."""

agentlings/cli/_migrations.py

@@ -0,0 +1,78 @@
+"""Migration log + runner for ``agentling upgrade``.
+
+The log lives at ``<data_dir>/.migrations`` — one applied migration ID per
+line. Pending migrations are those discovered on disk that are not yet
+present in the log. A failed migration leaves the log unchanged so the next
+run picks up where the previous left off.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from pathlib import Path
+
+from agentlings import migrations as migrations_pkg
+
+logger = logging.getLogger(__name__)
+
+LOG_NAME = ".migrations"
+
+
+@dataclass
+class MigrationResult:
+    id: str
+    description: str
+    status: str  # "applied" | "skipped"
+
+
+def read_log(data_dir: Path) -> list[str]:
+    """Return the IDs of migrations already applied to ``data_dir``."""
+    path = data_dir / LOG_NAME
+    if not path.exists():
+        return []
+    return [line.strip() for line in path.read_text(encoding="utf-8").splitlines() if line.strip()]
+
+
+def append_log(data_dir: Path, migration_id: str) -> None:
+    """Atomically append a migration ID to the log."""
+    path = data_dir / LOG_NAME
+    existing = path.read_text(encoding="utf-8") if path.exists() else ""
+    path.write_text(existing + migration_id + "\n", encoding="utf-8")
+
+
+def pending(data_dir: Path) -> list[object]:
+    """Return migration modules not yet recorded in the log."""
+    applied = set(read_log(data_dir))
+    return [m for m in migrations_pkg.discover() if m.ID not in applied]
+
+
+def run_pending(data_dir: Path, *, dry_run: bool = False) -> list[MigrationResult]:
+    """Apply every pending migration, recording each in the log on success.
+
+    ``dry_run`` reports what would run without executing or modifying the log.
+    Raises whatever the migration raises; callers decide how to surface it.
+    """
+    results: list[MigrationResult] = []
+    for migration in pending(data_dir):
+        if dry_run:
+            results.append(MigrationResult(migration.ID, migration.DESCRIPTION, "skipped"))
+            continue
+        logger.info("applying migration %s: %s", migration.ID, migration.DESCRIPTION)
+        migration.apply(data_dir)
+        append_log(data_dir, migration.ID)
+        results.append(MigrationResult(migration.ID, migration.DESCRIPTION, "applied"))
+    return results
+
+
+def stamp_all_applied(data_dir: Path) -> None:
+    """Record every known migration as already applied without running any.
+
+    Called by ``init`` so a fresh agent dir starts with the current migration
+    set marked complete — only future migrations need to run on later upgrades.
+    """
+    path = data_dir / LOG_NAME
+    if path.exists():
+        return
+    ids = [m.ID for m in migrations_pkg.discover()]
+    path.write_text("\n".join(ids) + ("\n" if ids else ""), encoding="utf-8")

agentlings/cli/_templates.py

@@ -0,0 +1,57 @@
+"""Bundled-template lookup for ``agentling init``.
+
+Templates ship as package data under ``src/agentlings/templates/<name>/``.
+Each template directory contains an ``agent.yaml`` (with ``{{NAME}}`` and
+optional ``{{API_KEY}}`` placeholders substituted at scaffold time) and an
+``.env.example`` file. ``--from-git`` is a future milestone; v1 only loads
+from this bundled directory.
+"""
+
+from __future__ import annotations
+
+from importlib import resources
+from importlib.resources.abc import Traversable
+
+TEMPLATES_PACKAGE = "agentlings.templates"
+
+
+def list_templates() -> list[str]:
+    """Return the names of all bundled templates.
+
+    A template is any subdirectory of the ``agentlings.templates`` package
+    that contains an ``agent.yaml``.
+    """
+    root = resources.files(TEMPLATES_PACKAGE)
+    names = []
+    for entry in root.iterdir():
+        if entry.is_dir() and (entry / "agent.yaml").is_file():
+            names.append(entry.name)
+    return sorted(names)
+
+
+def template_root(name: str) -> Traversable:
+    """Return the resource root for a named template, raising if missing."""
+    root = resources.files(TEMPLATES_PACKAGE) / name
+    if not (root / "agent.yaml").is_file():
+        available = ", ".join(list_templates()) or "(none)"
+        raise ValueError(
+            f"unknown template '{name}'; available templates: {available}"
+        )
+    return root
+
+
+def render_yaml(name: str, agent_name: str) -> str:
+    """Load ``agent.yaml`` from the named template and substitute placeholders."""
+    raw = (template_root(name) / "agent.yaml").read_text(encoding="utf-8")
+    return raw.replace("{{NAME}}", agent_name)
+
+
+def env_example(name: str) -> str:
+    """Return the contents of the template's ``.env.example`` file.
+
+    Templates without an ``.env.example`` return a minimal default.
+    """
+    path = template_root(name) / ".env.example"
+    if path.is_file():
+        return path.read_text(encoding="utf-8")
+    return "ANTHROPIC_API_KEY=\nAGENT_API_KEY=\n"

agentlings/cli/_version.py

@@ -0,0 +1,33 @@
+"""Framework version detection and per-agent-dir version stamping."""
+
+from __future__ import annotations
+
+from importlib import metadata
+from pathlib import Path
+
+VERSION_FILE = ".framework-version"
+
+
+def installed_version() -> str:
+    """Return the version of the currently-installed ``agentlings`` package."""
+    return metadata.version("agentlings")
+
+
+def read_dir_version(agent_dir: Path) -> str | None:
+    """Return the framework version recorded in ``<agent_dir>/.framework-version``.
+
+    Returns ``None`` when the file is missing or empty — callers treat that as
+    "this dir was set up before version stamping existed" and fall back to
+    running every migration.
+    """
+    path = agent_dir / VERSION_FILE
+    if not path.exists():
+        return None
+    text = path.read_text(encoding="utf-8").strip()
+    return text or None
+
+
+def write_dir_version(agent_dir: Path, version: str) -> None:
+    """Stamp ``version`` into ``<agent_dir>/.framework-version``."""
+    path = agent_dir / VERSION_FILE
+    path.write_text(version + "\n", encoding="utf-8")

agentlings/cli/init.py

@@ -0,0 +1,122 @@
+"""``agentling init`` — scaffold a new agent directory.
+
+Produces a self-contained directory the operator can ``cd`` into and run
+``agentling run`` against. Does not install the framework — that's already
+installed (it's the binary running). Does not touch the network in v1; only
+bundled templates are supported.
+"""
+
+from __future__ import annotations
+
+import logging
+import secrets
+from dataclasses import dataclass
+from pathlib import Path
+
+from agentlings.cli import _migrations, _templates, _version
+
+logger = logging.getLogger(__name__)
+
+DATA_DIRNAME = "data"
+ENV_FILENAME = ".env"
+ENV_EXAMPLE_FILENAME = ".env.example"
+YAML_FILENAME = "agent.yaml"
+
+
+@dataclass
+class InitResult:
+    agent_dir: Path
+    template: str
+    framework_version: str
+    generated_api_key: str
+
+
+def init_agent(
+    name: str,
+    *,
+    dir: Path | None = None,
+    template: str = "default",
+    api_key: str | None = None,
+    anthropic_api_key: str | None = None,
+    anthropic_base_url: str | None = None,
+    force: bool = False,
+) -> InitResult:
+    """Scaffold a new agent directory.
+
+    Args:
+        name: Agent name. Used as the default directory name and substituted
+            into the template's ``agent.yaml``.
+        dir: Output directory. Defaults to ``./<name>``.
+        template: Bundled template to scaffold from.
+        api_key: ``AGENT_API_KEY`` value to write into ``.env``. Auto-generated
+            if not supplied.
+        anthropic_api_key: Optional Anthropic key to pre-populate ``.env``.
+        anthropic_base_url: Optional Anthropic base URL to pre-populate.
+        force: Allow scaffolding into an existing directory. Files that already
+            exist are overwritten *except* ``data/`` and ``.env``, which are
+            never touched once they exist.
+    """
+    target = (dir or Path.cwd() / name).resolve()
+    if target.exists() and not force and any(target.iterdir()):
+        raise FileExistsError(
+            f"{target} already exists and is non-empty (pass --force to overwrite)"
+        )
+
+    target.mkdir(parents=True, exist_ok=True)
+    (target / DATA_DIRNAME).mkdir(exist_ok=True)
+
+    yaml_path = target / YAML_FILENAME
+    if not yaml_path.exists() or force:
+        yaml_path.write_text(_templates.render_yaml(template, name), encoding="utf-8")
+
+    env_example = _templates.env_example(template)
+    (target / ENV_EXAMPLE_FILENAME).write_text(env_example, encoding="utf-8")
+
+    generated = api_key or _generate_api_key()
+    env_path = target / ENV_FILENAME
+    if not env_path.exists():
+        env_path.write_text(
+            _render_env(env_example, generated, anthropic_api_key, anthropic_base_url),
+            encoding="utf-8",
+        )
+
+    framework_version = _version.installed_version()
+    _version.write_dir_version(target, framework_version)
+    _migrations.stamp_all_applied(target / DATA_DIRNAME)
+
+    return InitResult(
+        agent_dir=target,
+        template=template,
+        framework_version=framework_version,
+        generated_api_key=generated,
+    )
+
+
+def _generate_api_key() -> str:
+    """Return a 32-byte URL-safe random string for ``AGENT_API_KEY``."""
+    return secrets.token_urlsafe(32)
+
+
+def _render_env(
+    env_example: str,
+    agent_api_key: str,
+    anthropic_api_key: str | None,
+    anthropic_base_url: str | None,
+) -> str:
+    """Substitute populated values into the ``.env.example`` template."""
+    lines = []
+    for line in env_example.splitlines():
+        stripped = line.strip()
+        if stripped.startswith("AGENT_API_KEY=") and not stripped.startswith("#"):
+            lines.append(f"AGENT_API_KEY={agent_api_key}")
+        elif stripped.startswith("ANTHROPIC_API_KEY=") and not stripped.startswith("#"):
+            value = anthropic_api_key or ""
+            lines.append(f"ANTHROPIC_API_KEY={value}")
+        elif (
+            anthropic_base_url
+            and stripped.startswith("# ANTHROPIC_BASE_URL=")
+        ):
+            lines.append(f"ANTHROPIC_BASE_URL={anthropic_base_url}")
+        else:
+            lines.append(line)
+    return "\n".join(lines) + "\n"

agentlings/cli/upgrade.py

@@ -0,0 +1,89 @@
+"""``agentling upgrade`` — reconcile a dir's data against the installed framework.
+
+The CLI never installs or upgrades the package itself — that's the package
+manager's job (``uv pip install --upgrade agentlings`` or equivalent). This
+command applies any pending data-layout migrations and bumps the dir's
+``.framework-version`` stamp once they all succeed.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from pathlib import Path
+
+from agentlings.cli import _migrations, _version
+from agentlings.cli.init import DATA_DIRNAME
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class UpgradeResult:
+    recorded_version: str | None
+    installed_version: str
+    applied: list[_migrations.MigrationResult]
+    pending_count: int
+
+
+def upgrade_agent(agent_dir: Path | None = None, *, dry_run: bool = False) -> UpgradeResult:
+    """Run pending migrations and stamp the new framework version.
+
+    Args:
+        agent_dir: Directory containing ``agent.yaml`` and ``data/``. Defaults
+            to CWD.
+        dry_run: Report what would run without executing migrations or
+            advancing ``.framework-version``.
+
+    Raises:
+        FileNotFoundError: When the directory has no ``data/``.
+        RuntimeError: When the installed framework is older than what
+            scaffolded the directory — downgrades are not supported.
+    """
+    target = (agent_dir or Path.cwd()).resolve()
+    data_dir = target / DATA_DIRNAME
+    if not data_dir.exists():
+        raise FileNotFoundError(
+            f"{target} does not look like an agent dir (no {DATA_DIRNAME}/ subdirectory)"
+        )
+
+    recorded = _version.read_dir_version(target)
+    installed = _version.installed_version()
+
+    if recorded and _is_newer(recorded, installed):
+        raise RuntimeError(
+            f"installed framework ({installed}) is older than what scaffolded "
+            f"this directory ({recorded}); downgrades are not supported. "
+            f"Run 'pip install agentlings=={recorded}' to restore."
+        )
+
+    pending = _migrations.pending(data_dir)
+    applied = _migrations.run_pending(data_dir, dry_run=dry_run)
+
+    if not dry_run and applied:
+        _version.write_dir_version(target, installed)
+    elif not dry_run and not applied and recorded != installed:
+        # No migrations to run, but the version stamp is stale — bump it so
+        # the next upgrade has an accurate baseline.
+        _version.write_dir_version(target, installed)
+
+    return UpgradeResult(
+        recorded_version=recorded,
+        installed_version=installed,
+        applied=applied,
+        pending_count=len(pending),
+    )
+
+
+def _is_newer(a: str, b: str) -> bool:
+    """Return True when ``a`` parses to a strictly newer semver than ``b``.
+
+    Falls back to lexicographic compare when either side is unparseable —
+    rare in practice (PEP 440 versions always parse) but safe.
+    """
+    try:
+        ta = tuple(int(p) for p in a.split(".")[:3])
+        tb = tuple(int(p) for p in b.split(".")[:3])
+        return ta > tb
+    except ValueError:
+        return a > b