feat: Agent Skills

packages/client/src/launchdarkly_ai_server/__init__.py

@@ -63,6 +63,24 @@
     resolve_tools,
 )
 from .sdk_info import SDK_INFO_CONTEXT, SDK_INFO_EVENT, register_ai_sdk_package
+from .skills import (
+    InMemorySkillStore,
+    all_skills,
+    get_skill,
+    get_skill_result,
+    get_skills,
+    skill_refs,
+)
+from .skills_core import SkillStore
+from .skills_fdv2 import FDv2SkillStore, StoreDiagnostics
+from .skills_fs import (
+    MANIFEST_FILENAME,
+    MANIFEST_VERSION,
+    SKILL_FILENAME,
+    OnUnavailable,
+    write_skills,
+)
+from .skills_watch import SkillWatcher, watch_skills
 from .tracking import execute_and_stream, execute_and_track, wrap_tool_handlers
 from .types import (
     NATIVE_TOOL_KEY,
@@ -93,6 +111,13 @@
     ProviderGraphResponse,
     ProviderHandler,
     ProviderResponse,
+    ReconcileAction,
+    ReconcileActionKind,
+    ReconcileReport,
+    Skill,
+    SkillOutcome,
+    SkillOutcomeReason,
+    SkillReference,
     StreamChunkEvent,
     StreamDoneEvent,
     StreamEvent,
@@ -156,6 +181,11 @@
     "ProviderGraphResponse",
     "ProviderHandler",
     "ProviderResponse",
+    "ReconcileAction",
+    "ReconcileReport",
+    "Skill",
+    "SkillOutcome",
+    "SkillReference",
     "StreamChunkEvent",
     "StreamDoneEvent",
     "StreamEvent",
@@ -254,6 +284,28 @@
     "graph",
     "resolve_graph",
     "GraphInstance",
+    # skills
+    "skill_refs",
+    "get_skill",
+    "get_skill_result",
+    "get_skills",
+    "all_skills",
+    "write_skills",
+    "SkillStore",
+    "InMemorySkillStore",
+    # skills — LaunchDarkly delivery store and on-change re-reconcile
+    "FDv2SkillStore",
+    "StoreDiagnostics",
+    "watch_skills",
+    "SkillWatcher",
+    # skills — literal types for typed consumers
+    "ReconcileActionKind",
+    "OnUnavailable",
+    "SkillOutcomeReason",
+    # skills — on-disk filenames and manifest version
+    "SKILL_FILENAME",
+    "MANIFEST_FILENAME",
+    "MANIFEST_VERSION",
 ]
 
 register_ai_sdk_package("launchdarkly-ai-server", __version__)

packages/client/src/launchdarkly_ai_server/lifecycle.py

@@ -6,6 +6,7 @@
 import os
 from typing import Any
 
+from . import skills
 from .sdk_info import flush_ai_sdk_info, reset_ai_sdk_info
 from .types import InitClientOptions
 from .utils import model_stamps_from_meta
@@ -23,6 +24,11 @@ def _env(name: str) -> str | None:
 
 _client: Any = None
 _tracer_provider: Any = None
+# True only when *this* SDK's call to trace.set_tracer_provider actually took
+# effect. "We built a provider" is not the same as "we own the global": the set
+# is once-guarded, so when another library registered first ours is refused and
+# the global stays theirs. Only the owner may release it on shutdown.
+_owns_otel_globals: bool = False
 
 
 def get_client() -> Any:
@@ -48,7 +54,7 @@ def _setup_telemetry(sdk_key: str, options: InitClientOptions | None = None) ->
     - Registers W3C trace context and baggage propagators.
     - Configures GZIP compression on the OTLP exporter.
     """
-    global _tracer_provider
+    global _tracer_provider, _owns_otel_globals
 
     opts = options or {}
 
@@ -112,6 +118,18 @@ def _setup_telemetry(sdk_key: str, options: InitClientOptions | None = None) ->
             pass
 
         trace.set_tracer_provider(provider)
+        # The set is refused, with a warning from OTel, when another library got
+        # there first. Record whether it actually took: shutdown must not release
+        # a global it never owned, and the caller's telemetry options are moot if
+        # someone else's provider is the one handing out tracers.
+        _owns_otel_globals = trace.get_tracer_provider() is provider
+        if not _owns_otel_globals:
+            logger.warning(
+                "An OpenTelemetry tracer provider was already registered by "
+                "something else in this process, so LaunchDarkly's telemetry "
+                "configuration is not in effect; spans will go wherever that "
+                "provider sends them."
+            )
         _tracer_provider = provider
         return provider
 
@@ -132,22 +150,47 @@ async def init_client(
 
     - Pass *client* directly (BYOC) to skip the LaunchDarkly Python SDK path.
     - Otherwise, reads ``LD_SDK_KEY`` from env or ``options['sdkKey']``.
+    - ``options['skillStore']`` sets the store the Agent Skills accessors read
+      from. Without one, the accessors raise ``RuntimeError``.
+
+    Idempotent: later calls return the existing client and ignore every option
+    **except** ``skillStore``, which is applied on every successful call, so you
+    can add a store after initialization. A ``None`` store never clears the
+    current one (use ``shutdown()``), and a call that raises installs nothing.
 
     Returns the initialized ``LDClientInterface`` instance.
     """
-    global _client
-
     opts = options or {}
 
+    ld_client = await _resolve_client(opts, client)
+
+    # Reached only on success, so a failed init installs no store.
+    skill_store = opts.get("skillStore")
+    if skill_store is not None:
+        skills._set_store(skill_store)
+    return ld_client
+
+
+async def _resolve_client(opts: InitClientOptions, client: Any) -> Any:
+    """
+    Returns the singleton client, initializing it on first call.
+    """
+    global _client
+
     # Idempotent — if already initialized, return the existing client
     if _client is not None:
         flush_ai_sdk_info(_client)
         return _client
 
     # BYOC path — pre-initialized client
     if client is not None:
-        _client = client
+        # Adopted only after telemetry setup succeeds. ``_client`` is the
+        # idempotency guard above, so assigning it first meant a setup that
+        # raised (a malformed OTEL_EXPORTER_OTLP_TIMEOUT does) left it set: the
+        # next call returned it as a silent success with no telemetry, hiding
+        # the config error. The caller owns this client, so it is not closed.
         _setup_telemetry(opts.get("sdkKey", "byoc"), opts)
+        _client = client
         flush_ai_sdk_info(_client)
         return _client
 
@@ -193,32 +236,92 @@ async def init_client(
     # start_wait caps the blocking init time; matches the TS SDK's 10 s timeout.
     ld_client = client_cls(ld_config, start_wait=10)
 
+    # As on the BYOC path: only a fully set-up client becomes the singleton. We
+    # built this one, so close it on failure — it holds a streaming connection
+    # that would otherwise outlive the attempt.
+    try:
+        _setup_telemetry(sdk_key, opts)
+    except Exception:
+        try:
+            close_result = ld_client.close()
+            if inspect.isawaitable(close_result):
+                await close_result
+        except Exception:
+            pass
+        raise
     _client = ld_client
-    _setup_telemetry(sdk_key, opts)
     flush_ai_sdk_info(_client)
     return _client
 
 
+def _release_otel_globals() -> None:
+    """
+    Releases the process-global tracer provider that ``_setup_telemetry``
+    installed, so a later ``init_client`` can install its own.
+
+    ``trace.set_tracer_provider`` is guarded by a ``Once``: a second call logs
+    "Overriding of current TracerProvider is not allowed" and keeps the provider
+    already in place. Without this, an init/shutdown/init cycle would leave every
+    span routed to the provider that was already shut down, and export nothing.
+
+    opentelemetry-python exposes no public API to unset it, so this reaches for
+    the module globals — both the slot and the ``Once`` that guards it, since
+    clearing the slot alone leaves the guard tripped and the next set a no-op.
+
+    Callers must gate this on ``_owns_otel_globals``. Having built a provider is
+    not enough: when another library registered first, our set was refused and
+    the global is still theirs, so releasing it here would tear down the host
+    application's tracing and leave the global a no-op proxy.
+
+    The global text map propagator needs no equivalent: ``set_global_textmap``
+    is a plain assignment with no ``Once``, so the next setup overwrites it.
+    """
+    try:
+        from opentelemetry import trace
+        from opentelemetry.util._once import Once
+
+        trace._TRACER_PROVIDER = None
+        trace._TRACER_PROVIDER_SET_ONCE = Once()
+    except Exception:  # pragma: no cover - defensive, OTel absent or restructured
+        logger.debug("Could not release the global OTel tracer provider", exc_info=True)
+
+
 async def shutdown() -> None:
     """
     Shuts down the singleton client. Idempotent — safe to call multiple times
     even if the client was never initialized or already shut down.
+
+    Also clears the configured skill store; pass ``skillStore`` again to the
+    next ``init_client`` to keep using the skill accessors.
+
+    When telemetry was running, this also releases the process-global tracer
+    provider so a later ``init_client`` can install its own — see
+    ``_release_otel_globals``.
     """
-    global _client, _tracer_provider
+    global _client, _tracer_provider, _owns_otel_globals
 
     local_client = _client
     local_provider = _tracer_provider
+    owned_globals = _owns_otel_globals
+
+    skills._clear_state()
 
     # Null the singleton before any awaits so a second call is a no-op
     _client = None
     _tracer_provider = None
+    _owns_otel_globals = False
     reset_ai_sdk_info()
 
     if local_provider is not None:
+        # Shut the provider down either way — we built it, and it owns an
+        # exporter and a batch timer — but only release the global registration
+        # when it was ours to take.
         try:
             local_provider.shutdown()
         except Exception:
             pass
+        if owned_globals:
+            _release_otel_globals()
 
     if local_client is not None:
         try:
@@ -243,9 +346,16 @@ def _set_client_for_testing(c: Any) -> None:
 
 def _reset_for_testing() -> None:
     """Test helper — clear all singleton state."""
-    global _client, _tracer_provider
+    global _client, _tracer_provider, _owns_otel_globals
+    owned_globals = _owns_otel_globals
     _client = None
     _tracer_provider = None
+    _owns_otel_globals = False
+    skills._clear_state()
+    # Mirrors shutdown(): without this a suite that inits more than once leaves
+    # every later span on the first test's provider.
+    if owned_globals:
+        _release_otel_globals()
 
 
 async def inspect_config(