agentic-lab 0.2.0__tar.gz → 0.3.0__tar.gz

{agentic_lab-0.2.0 → agentic_lab-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: agentic-lab
-Version: 0.2.0
+Version: 0.3.0
 Summary: Universal record-and-replay for LLM agents.
 Keywords: llm,agents,replay,tracing,evals
 Author: Ambuj Agrawal, Garima Luthra
@@ -35,6 +35,7 @@ Requires-Dist: playwright>=1.59,<2.0 ; extra == 'dev'
 Requires-Dist: langchain-core>=0.3,<1.0 ; extra == 'langchain'
 Requires-Dist: langchain-openai>=0.3.35 ; extra == 'langchain'
 Requires-Dist: langgraph>=1.0.1 ; extra == 'langchain'
+Requires-Dist: openai-agents>=0.0.1 ; extra == 'openai-agents'
 Requires-Dist: starlette>=0.40,<1.0 ; extra == 'ui'
 Requires-Dist: uvicorn>=0.30,<1.0 ; extra == 'ui'
 Requires-Dist: anyio>=4.4,<5.0 ; extra == 'ui'
@@ -50,6 +51,7 @@ Project-URL: Examples, https://github.com/ambuj-krishna-agrawal/agentlab/tree/ma
 Project-URL: Changelog, https://github.com/ambuj-krishna-agrawal/agentlab/blob/main/CHANGELOG.md
 Provides-Extra: dev
 Provides-Extra: langchain
+Provides-Extra: openai-agents
 Provides-Extra: ui
 Description-Content-Type: text/markdown
 

{agentic_lab-0.2.0 → agentic_lab-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agentic-lab"
-version = "0.2.0"
+version = "0.3.0"
 description = "Universal record-and-replay for LLM agents."
 readme = "README.md"
 requires-python = ">=3.12"
@@ -43,6 +43,9 @@ langchain = [
     "langchain-openai>=0.3.35",
     "langgraph>=1.0.1",
 ]
+openai-agents = [
+    "openai-agents>=0.0.1",
+]
 dev = [
     "pytest>=8.2,<9.0",
     "pytest-asyncio>=0.23,<1.0",
@@ -176,6 +179,9 @@ disable_error_code = [
     "no-any-return",
     "arg-type",
     "unused-ignore",
+    "untyped-decorator",
+    "union-attr",
+    "operator",
 ]
 
 [[tool.mypy.overrides]]
@@ -192,6 +198,12 @@ module = ["agentlab.examples.*"]
 ignore_errors = true
 follow_imports = "skip"
 
+[[tool.mypy.overrides]]
+# Optional integration deps that are not test/runtime dependencies of the
+# core package (imported lazily inside ``install()``).
+module = ["agents.*", "langchain_core.*"]
+ignore_missing_imports = true
+
 [tool.pytest.ini_options]
 minversion = "8.0"
 addopts = [

{agentic_lab-0.2.0 → agentic_lab-0.3.0}/src/agentlab/__init__.py

@@ -38,6 +38,10 @@ without stability guarantees.
 from importlib.metadata import PackageNotFoundError as _PackageNotFoundError
 from importlib.metadata import version as _version
 
+# Subpackage exposed for ``al.integrations.install(...)`` and lazy
+# ``al.integrations.langchain``.  The package ``__init__`` is dependency
+# free; optional adapters import their framework only inside ``install()``.
+from agentlab import integrations
 from agentlab.bridges.otel_genai import ExportTarget, export_trace
 from agentlab.core import (
     AgentHandle,
@@ -97,7 +101,6 @@ from agentlab.core import (
     ToolHandle,
     ToolKind,
     ToolSpan,
-    agent,
     continuation,
     detached,
     eval_,
@@ -112,10 +115,17 @@ from agentlab.core import (
     retriever,
     start_run,
     start_span,
-    step,
     tool,
 )
 from agentlab.core import llm as _llm_emitter
+
+# Dual-use decorators.  These shadow the bare ``agent`` / ``step``
+# context-managers imported from ``agentlab.core`` above with wrappers
+# that work as *both* context managers and (sync/async-aware)
+# decorators, and add the new ``run`` decorator.  ``with al.agent(...)``
+# behaves identically; ``@al.agent(...)`` / ``@al.step(...)`` /
+# ``@al.run(...)`` are the new spellings.
+from agentlab.decorators import agent, run, step
 from agentlab.evals import (
     AgentRunner,
     BaseEvaluator,
@@ -175,6 +185,13 @@ from agentlab.replay import (
     replay,
     replay_run,
 )
+from agentlab.session import (
+    _maybe_autostart_from_env,
+    active_recording,
+    init,
+    is_active,
+    shutdown,
+)
 from agentlab.ui import create_app, serve
 
 # ``agentlab.recorder`` transitively imports ``agentlab.llm._autoemit``;
@@ -193,6 +210,11 @@ try:
 except _PackageNotFoundError:  # pragma: no cover — only when running uninstalled
     __version__ = "0.0.0+unknown"
 
+# ``AGENTLAB=1 python my_agent.py`` records everything with zero code
+# change.  This must run *after* the whole public surface is imported so
+# the ambient ``record()`` it opens sees a fully-initialised package.
+_maybe_autostart_from_env()
+
 __all__ = [
     "CURRENT_SCHEMA_VERSION",
     "AgentHandle",
@@ -294,6 +316,7 @@ __all__ = [
     "TraceHeader",
     "UnfreezeRef",
     "__version__",
+    "active_recording",
     "agent",
     "bundled_rubric",
     "continuation",
@@ -306,6 +329,9 @@ __all__ = [
     "guardrail",
     "handoff",
     "in_recording",
+    "init",
+    "integrations",
+    "is_active",
     "list_bundled_rubrics",
     "llm",
     "memory",
@@ -320,7 +346,9 @@ __all__ = [
     "replay",
     "replay_run",
     "retriever",
+    "run",
     "serve",
+    "shutdown",
     "start_run",
     "start_span",
     "step",

agentic_lab-0.3.0/src/agentlab/bundle.py

@@ -0,0 +1,247 @@
+"""Portable single-file trace bundles (``*.agentlab``).
+
+A ``.agentlab`` file is a plain ZIP archive of one trace directory plus a
+small ``bundle.json`` manifest.  Because the archive contains
+``http.jsonl`` (the raw on-the-wire exchanges), the recipient can not
+only *view* the trace but **replay it deterministically** — no API keys,
+no network.  This is the lightweight, on-brand version of "team
+collaboration": send a colleague the exact failing run.
+
+::
+
+    agentlab bundle brave-fog ./bug.agentlab     # author
+    agentlab open ./bug.agentlab                  # teammate → imports + prints key
+
+Layout inside the archive::
+
+    bundle.json            — manifest (format version, ulid, name, ...)
+    trace/header.json
+    trace/spans.jsonl
+    trace/footer.json      — absent ⇒ the run crashed
+    trace/http.jsonl       — present iff HTTP was captured
+    trace/...              — every other file in the source dir, 1:1
+"""
+
+from __future__ import annotations
+
+import json
+import zipfile
+from dataclasses import asdict, dataclass
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from agentlab.errors import TraceCorruptionError, TraceKeyNotFoundError
+from agentlab.io.format import HEADER_FILENAME
+
+if TYPE_CHECKING:
+    from agentlab.storage.base import TraceStore
+
+__all__ = [
+    "BUNDLE_FORMAT_VERSION",
+    "BUNDLE_SUFFIX",
+    "BundleManifest",
+    "bundle_trace",
+    "open_bundle",
+]
+
+BUNDLE_SUFFIX = ".agentlab"
+BUNDLE_MANIFEST = "bundle.json"
+BUNDLE_FORMAT_VERSION = 1
+_TRACE_PREFIX = "trace/"
+
+
+@dataclass(frozen=True, slots=True)
+class BundleManifest:
+    """Self-describing header written into every bundle."""
+
+    format_version: int
+    trace_ulid: str
+    trace_name: str
+    dir_name: str
+    created_at: str
+    file_count: int
+
+
+def bundle_trace(
+    source_dir: Path,
+    out: Path,
+    *,
+    force: bool = False,
+) -> Path:
+    """Archive the trace directory ``source_dir`` into a ``.agentlab`` file.
+
+    Returns the written path.  Raises :class:`TraceKeyNotFoundError` if
+    ``source_dir`` is not a trace directory, and refuses to clobber an
+    existing ``out`` unless ``force`` is set.
+    """
+    source_dir = source_dir.expanduser().resolve()
+    header_path = source_dir / HEADER_FILENAME
+    if not header_path.is_file():
+        raise TraceKeyNotFoundError(
+            f"{source_dir} is not a trace directory (no {HEADER_FILENAME}); cannot bundle.",
+            trace_key=str(source_dir),
+        )
+
+    out = out.expanduser()
+    if out.suffix != BUNDLE_SUFFIX:
+        out = out.with_suffix(BUNDLE_SUFFIX)
+    if out.exists() and not force:
+        raise FileExistsError(
+            f"bundle target {out} already exists; pass --force to overwrite.",
+        )
+    out.parent.mkdir(parents=True, exist_ok=True)
+
+    files = sorted(p for p in source_dir.rglob("*") if p.is_file())
+    ulid, name = _read_identity(header_path)
+
+    manifest = BundleManifest(
+        format_version=BUNDLE_FORMAT_VERSION,
+        trace_ulid=ulid,
+        trace_name=name,
+        dir_name=source_dir.name,
+        created_at=datetime.now(UTC).isoformat(),
+        file_count=len(files),
+    )
+
+    # Write atomically: build a temp file then rename so a crash never
+    # leaves a half-written ``.agentlab`` that looks valid.
+    tmp = out.with_name(out.name + ".tmp")
+    try:
+        with zipfile.ZipFile(tmp, "w", compression=zipfile.ZIP_DEFLATED) as zf:
+            zf.writestr(BUNDLE_MANIFEST, json.dumps(asdict(manifest), indent=2))
+            for file_path in files:
+                arcname = _TRACE_PREFIX + file_path.relative_to(source_dir).as_posix()
+                zf.write(file_path, arcname)
+        tmp.replace(out)
+    finally:
+        tmp.unlink(missing_ok=True)
+    return out
+
+
+def open_bundle(
+    bundle_path: Path,
+    store: TraceStore,
+    *,
+    force: bool = False,
+) -> Path:
+    """Extract a ``.agentlab`` bundle into ``store``'s root and return the dir.
+
+    The trace is placed under its original directory name so it resolves
+    by ULID / name exactly as it did for the author.  Refuses to
+    overwrite an existing trace directory unless ``force`` is set.
+    """
+    bundle_path = bundle_path.expanduser().resolve()
+    if not bundle_path.is_file():
+        raise TraceKeyNotFoundError(
+            f"bundle {bundle_path} does not exist.",
+            trace_key=str(bundle_path),
+        )
+    root = _store_root(store)
+
+    with zipfile.ZipFile(bundle_path) as zf:
+        manifest = _read_manifest(zf, bundle_path)
+        dir_name = manifest.dir_name or manifest.trace_ulid
+        if not dir_name:
+            raise TraceCorruptionError(
+                f"bundle {bundle_path} has no usable trace directory name.",
+            )
+        target = root / dir_name
+        if target.exists():
+            if not force:
+                raise FileExistsError(
+                    f"a trace directory already exists at {target}; pass --force to overwrite it.",
+                )
+            _rmtree(target)
+
+        members = [n for n in zf.namelist() if n.startswith(_TRACE_PREFIX)]
+        if not members:
+            raise TraceCorruptionError(
+                f"bundle {bundle_path} contains no trace/ payload.",
+            )
+        root.mkdir(parents=True, exist_ok=True)
+        target.mkdir(parents=True, exist_ok=True)
+        for member in members:
+            _safe_extract_member(zf, member, target)
+
+    return target
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _read_identity(header_path: Path) -> tuple[str, str]:
+    """Return ``(trace_ulid, trace_name)`` from a JSON header (best effort)."""
+    try:
+        data = json.loads(header_path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return "", ""
+    ulid = str(data.get("trace_ulid", "") or "")
+    name = str(data.get("name", "") or "")
+    return ulid, name
+
+
+def _read_manifest(zf: zipfile.ZipFile, bundle_path: Path) -> BundleManifest:
+    try:
+        raw = zf.read(BUNDLE_MANIFEST)
+    except KeyError as exc:
+        raise TraceCorruptionError(
+            f"bundle {bundle_path} is missing its {BUNDLE_MANIFEST}; "
+            f"it may not be an AgentLab bundle.",
+        ) from exc
+    try:
+        data = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise TraceCorruptionError(
+            f"bundle {bundle_path} has a corrupt {BUNDLE_MANIFEST}.",
+        ) from exc
+    return BundleManifest(
+        format_version=int(data.get("format_version", 0)),
+        trace_ulid=str(data.get("trace_ulid", "")),
+        trace_name=str(data.get("trace_name", "")),
+        dir_name=str(data.get("dir_name", "")),
+        created_at=str(data.get("created_at", "")),
+        file_count=int(data.get("file_count", 0)),
+    )
+
+
+def _safe_extract_member(zf: zipfile.ZipFile, member: str, target: Path) -> None:
+    """Extract one ``trace/<rel>`` member into ``target`` (zip-slip safe)."""
+    rel = member[len(_TRACE_PREFIX) :]
+    if not rel or rel.endswith("/"):
+        return
+    dest = (target / rel).resolve()
+    # Defend against path traversal in a malicious bundle.
+    if not _is_within(dest, target.resolve()):
+        raise TraceCorruptionError(
+            f"bundle member {member!r} escapes the target directory; refusing.",
+        )
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    with zf.open(member) as src, dest.open("wb") as out_fp:
+        out_fp.write(src.read())
+
+
+def _is_within(path: Path, root: Path) -> bool:
+    try:
+        path.relative_to(root)
+    except ValueError:
+        return False
+    return True
+
+
+def _store_root(store: TraceStore) -> Path:
+    root = getattr(store, "root", None)
+    if root is None:
+        raise TraceCorruptionError(
+            "the configured trace store has no local root; "
+            "`agentlab open` only supports local stores.",
+        )
+    return Path(root)
+
+
+def _rmtree(path: Path) -> None:
+    import shutil  # noqa: PLC0415
+
+    shutil.rmtree(path)

{agentic_lab-0.2.0 → agentic_lab-0.3.0}/src/agentlab/cli.py

@@ -89,6 +89,90 @@ _log = logging.getLogger("agentlab.cli")
 # ---------------------------------------------------------------------------
 
 
+def _add_share_subparsers(
+    sub: argparse._SubParsersAction[argparse.ArgumentParser],
+) -> None:
+    """Wire the portable-bundle ``bundle`` / ``open`` / ``push`` / ``pull`` subcommands."""
+    p = sub.add_parser(
+        "bundle",
+        help="Pack a trace into a portable single-file .agentlab bundle (replayable).",
+    )
+    p.add_argument("key")
+    p.add_argument("out", type=Path, help="Output path (``.agentlab`` is appended if missing).")
+    p.add_argument("--force", action="store_true", help="Overwrite an existing bundle.")
+
+    p = sub.add_parser(
+        "open",
+        help="Import a .agentlab bundle into the store and print its key.",
+    )
+    p.add_argument("bundle", type=Path, help="Path to a .agentlab bundle.")
+    p.add_argument(
+        "--force",
+        action="store_true",
+        help="Overwrite an existing trace directory with the same name.",
+    )
+
+    p = sub.add_parser(
+        "push",
+        help="Pack a trace into a bundle and upload it to a remote URL (http(s):// or file://).",
+    )
+    p.add_argument("key")
+    p.add_argument(
+        "url",
+        help=(
+            "Destination URL.  For HTTPS use a presigned S3 / GCS / Azure URL "
+            "(or any server that accepts PUT)."
+        ),
+    )
+    p.add_argument(
+        "--auth",
+        default=None,
+        help=(
+            "Bearer token sent as ``Authorization: Bearer <auth>``. "
+            "Falls back to $AGENTLAB_BUNDLE_AUTH when omitted."
+        ),
+    )
+    p.add_argument(
+        "--force",
+        action="store_true",
+        help="For file:// destinations, overwrite an existing file.",
+    )
+    p.add_argument(
+        "--max-bytes",
+        type=int,
+        default=None,
+        help="Refuse to upload bundles larger than this (default: 1 GiB).",
+    )
+
+    p = sub.add_parser(
+        "pull",
+        help="Download a .agentlab bundle from a URL and import it into the store.",
+    )
+    p.add_argument(
+        "url",
+        help="Source URL (http(s):// or file://).",
+    )
+    p.add_argument(
+        "--auth",
+        default=None,
+        help=(
+            "Bearer token sent as ``Authorization: Bearer <auth>``. "
+            "Falls back to $AGENTLAB_BUNDLE_AUTH when omitted."
+        ),
+    )
+    p.add_argument(
+        "--force",
+        action="store_true",
+        help="Overwrite an existing trace directory with the same name.",
+    )
+    p.add_argument(
+        "--max-bytes",
+        type=int,
+        default=None,
+        help="Refuse to download bundles larger than this (default: 1 GiB).",
+    )
+
+
 def build_parser() -> argparse.ArgumentParser:
     """Build the top-level argparse parser (extracted for tests)."""
     from agentlab import __version__  # noqa: PLC0415 — avoid circular import on cold start
@@ -176,10 +260,19 @@ def build_parser() -> argparse.ArgumentParser:
     p.add_argument("--port", type=int, default=7861)
     p.add_argument("--open-browser", action="store_true")
 
+    _add_share_subparsers(sub)
+
     p = sub.add_parser("promote", help="Generate a pytest replay-test scaffold.")
     p.add_argument("key")
     p.add_argument("--out", type=Path, required=True)
-    p.add_argument("--agent", required=True, help="module.path:callable_name")
+    p.add_argument(
+        "--agent",
+        default=None,
+        help=(
+            "module.path:callable_name.  Optional when the run was recorded "
+            "via @al.run (the entrypoint is read from the trace)."
+        ),
+    )
     p.add_argument("--name", default=None)
     p.add_argument("--force", action="store_true")
 
@@ -277,6 +370,10 @@ def _dispatch(args: argparse.Namespace) -> int:
         "gc": _cmd_gc,
         "serve": _cmd_serve,
         "promote": _cmd_promote,
+        "bundle": _cmd_bundle,
+        "open": _cmd_open,
+        "push": _cmd_push,
+        "pull": _cmd_pull,
     }
     if args.command == "eval":
         from agentlab.evals.cli import dispatch as _eval_dispatch  # noqa: PLC0415
@@ -497,6 +594,132 @@ def _cmd_export(args: argparse.Namespace) -> int:
     )
 
 
+# ---------------------------------------------------------------------------
+# bundle / open
+# ---------------------------------------------------------------------------
+
+
+def _cmd_bundle(args: argparse.Namespace) -> int:
+    from agentlab.bundle import bundle_trace  # noqa: PLC0415
+
+    store = _resolve_store(args)
+    handle = store.resolve(args.key)
+    if handle.backend_locator is None:
+        raise TraceKeyNotFoundError(
+            "trace has no on-disk locator; cannot bundle.",
+            trace_key=args.key,
+        )
+    try:
+        out = bundle_trace(Path(handle.backend_locator), args.out, force=args.force)
+    except FileExistsError as exc:
+        sys.stderr.write(f"agentlab bundle: {exc}\n")
+        return EXIT_USER_ERROR
+    if args.json_output:
+        print(json.dumps({"out": str(out), "key": args.key}))
+    elif not args.quiet:
+        print(f"wrote bundle {out}")
+    return EXIT_OK
+
+
+def _cmd_open(args: argparse.Namespace) -> int:
+    from agentlab.bundle import open_bundle  # noqa: PLC0415
+
+    store = _resolve_store(args)
+    try:
+        target = open_bundle(args.bundle, store, force=args.force)
+    except FileExistsError as exc:
+        sys.stderr.write(f"agentlab open: {exc}\n")
+        return EXIT_USER_ERROR
+    handle = store.resolve(str(target))
+    key = handle.trace_ulid or handle.name or target.name
+    if args.json_output:
+        print(json.dumps({"imported": str(target), "key": key}))
+    elif not args.quiet:
+        print(f"imported trace {key}")
+        print(f"  at: {target}")
+        print(f"\nView:    agentlab show {key}")
+        print(f"Replay:  agentlab replay {key}")
+    return EXIT_OK
+
+
+def _cmd_push(args: argparse.Namespace) -> int:
+    from agentlab.share import BundleTransportError, push_bundle  # noqa: PLC0415
+
+    store = _resolve_store(args)
+    handle = store.resolve(args.key)
+    if handle.backend_locator is None:
+        raise TraceKeyNotFoundError(
+            "trace has no on-disk locator; cannot push.",
+            trace_key=args.key,
+        )
+    push_kwargs: dict[str, Any] = {
+        "auth": args.auth,
+        "force": args.force,
+    }
+    if args.max_bytes is not None:
+        push_kwargs["max_bytes"] = args.max_bytes
+    try:
+        result = push_bundle(
+            Path(handle.backend_locator),
+            args.url,
+            **push_kwargs,
+        )
+    except BundleTransportError as exc:
+        sys.stderr.write(f"agentlab push: {exc.message}\n")
+        return EXIT_USER_ERROR
+    if args.json_output:
+        print(
+            json.dumps(
+                {
+                    "url": result.url,
+                    "bytes": result.bytes_uploaded,
+                    "key": args.key,
+                },
+            ),
+        )
+    elif not args.quiet:
+        print(f"pushed {result.bytes_uploaded} bytes → {result.url}")
+        print(f"\nReceiver:  agentlab pull {result.url}")
+    return EXIT_OK
+
+
+def _cmd_pull(args: argparse.Namespace) -> int:
+    from agentlab.share import BundleTransportError, pull_bundle  # noqa: PLC0415
+
+    store = _resolve_store(args)
+    pull_kwargs: dict[str, Any] = {
+        "auth": args.auth,
+        "force": args.force,
+    }
+    if args.max_bytes is not None:
+        pull_kwargs["max_bytes"] = args.max_bytes
+    try:
+        result = pull_bundle(args.url, store, **pull_kwargs)
+    except (BundleTransportError, FileExistsError) as exc:
+        msg = exc.message if isinstance(exc, BundleTransportError) else str(exc)
+        sys.stderr.write(f"agentlab pull: {msg}\n")
+        return EXIT_USER_ERROR
+    handle = store.resolve(str(result.trace_dir))
+    key = handle.trace_ulid or handle.name or result.trace_dir.name
+    if args.json_output:
+        print(
+            json.dumps(
+                {
+                    "url": result.url,
+                    "bytes": result.bytes_downloaded,
+                    "imported": str(result.trace_dir),
+                    "key": key,
+                },
+            ),
+        )
+    elif not args.quiet:
+        print(f"pulled {result.bytes_downloaded} bytes from {result.url}")
+        print(f"imported trace {key}")
+        print(f"\nView:    agentlab show {key}")
+        print(f"Replay:  agentlab replay {key}")
+    return EXIT_OK
+
+
 # ---------------------------------------------------------------------------
 # gc
 # ---------------------------------------------------------------------------