Skip to main content

flightdeck-sensor

In-process agent observability sensor for Flightdeck.

Local development venv

Flightdeck pins Python 3.12 for local development. The project bound is 3.10 ≤ x < 3.14 (pyproject requires-python); sensor/.venv is the canonical interpreter for every Make target that runs Python.

Recreate from a fresh clone or after a rm -rf sensor/.venv:

python3.12 -m venv sensor/.venv
./sensor/.venv/bin/python -m pip install -e ".[dev,anthropic,openai]"

make -C sensor install does the same once the venv exists. CI overrides via env (PYTHON=python make -C sensor test) where actions/setup-python already pinned the interpreter.

Optional session_id hint (D094)

By default init() auto-generates a fresh UUID every time the process starts. Orchestrators that re-run the same logical workflow (Temporal, Airflow, cron) can instead pass a stable identifier; if the backend already has a row for that session, the new execution is attached to it and appears as a continuation of the prior run in the fleet view.

Supply the hint via either the session_id= kwarg or the FLIGHTDECK_SESSION_ID environment variable. The env var takes precedence.

The value MUST parse as a canonical UUID (any version) -- the sessions table column is UUID-typed. If you pass a non-UUID the sensor logs a warning and falls back to auto-generating one. Orchestrators that use string identifiers (Temporal workflow_id, Airflow dag_run_id) should hash the identifier into a deterministic UUID with uuid.uuid5.

Temporal workflow example

import uuid
import flightdeck_sensor as fd
from temporalio import workflow

# Pick any fixed namespace UUID for your deployment. The same
# workflow_id + namespace always produces the same session UUID,
# so re-runs of the same workflow all map to the same sessions row.
FLIGHTDECK_NS = uuid.UUID("00000000-0000-0000-0000-000000000001")

@workflow.defn
class MyWorkflow:
    @workflow.run
    async def run(self, input):
        ctx = workflow.info()
        fd.init(
            server="http://flightdeck.internal/ingest",
            token="ftd_...",
            session_id=str(uuid.uuid5(FLIGHTDECK_NS, ctx.workflow_id)),
        )
        # If this workflow_id has run before, the backend attaches
        # this execution to the existing session automatically; the
        # sensor logs INFO on the first response that confirms it.
        ...

The sensor logs a single WARNING at init() time whenever a custom session_id is in play so the behaviour is visible in operational logs, and an INFO line on the first response where the backend confirms attachment. See DECISIONS.md D094 and ARCHITECTURE.md ("Session attachment flow") for the full protocol.

Framework support

flightdeck_sensor.patch() installs three class-level (or module- level) interceptors process-wide. Every LLM call that flows through a patched entry point emits a pre_call / post_call event pair without any framework-specific wiring.

Framework Interceptor Entry points
Anthropic SDK (direct or via a framework that constructs Anthropic() internally — LangChain, LlamaIndex, CrewAI native) patch_anthropic_classes Anthropic.messages.create / .stream, async + sync, beta resources
OpenAI SDK (direct or via a framework that constructs OpenAI() internally — LangChain, LlamaIndex, CrewAI native) patch_openai_classes OpenAI.chat.completions.create, .responses.create, .embeddings.create, async + sync
litellm (router that aggregates many providers behind one function surface) patch_litellm_functions litellm.completion, litellm.acompletion

litellm example (KI21)

litellm's Anthropic route uses raw httpx instead of the Anthropic SDK, so it bypasses the SDK-class patches. The litellm interceptor patches litellm.completion / litellm.acompletion directly to close this gap. An Anthropic model string via litellm exercises the bypass case:

import flightdeck_sensor
import litellm

flightdeck_sensor.init(
    server="http://flightdeck.internal/ingest", token="ftd_...",
)
flightdeck_sensor.patch()

# After patch(), this call routes through the sensor's pre/post-call
# plumbing regardless of which underlying provider litellm picks for
# the model string.
response = litellm.completion(
    model="claude-haiku-4-5-20251001",
    messages=[{"role": "user", "content": "hi"}],
    max_tokens=5,
)

Install the optional dependency: pip install flightdeck-sensor[litellm].

What the litellm interceptor catches, and what it doesn't

Catches. Direct callers of litellm.completion(**kwargs) and litellm.acompletion(**kwargs) — the vast majority of litellm integrations, including the default chat-completion surface exposed by user code, Router, and frameworks that route through the public API (CrewAI non-native flavors, langchain-community's litellm adapter, etc.).

Does NOT catch.

  • Streaming. stream=True raises NotImplementedError in v1 with a pointer to KI26 (the tracked follow-up). Use stream=False or reconstruct the stream downstream of the call.
  • Lower-level litellm entry points. Some integrations reach past completion into litellm.llms.custom_httpx.http_handler or other internal helpers directly. Those calls bypass the module-level wrapper. A broader httpx-level interceptor was considered during the KI21 scoping and deferred — if framework reports surface calls that slip past the current coverage, file a new issue.
  • Embeddings (litellm.embedding / aembedding). Not wrapped in v1. Out of scope; embeddings have no policy/budget surface in the current session layer.
  • litellm.text_completion. Legacy completion API, not wrapped.

Metadata

Release files for flightdeck-sensor 0.5.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for flightdeck-sensor 0.5.3
File Size Uploaded Provenance Actions
flightdeck_sensor-0.5.3.tar.gz 211.1 kB With provenance Details for flightdeck_sensor-0.5.3.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for flightdeck-sensor 0.5.3
File Interpreter ABI Platform Actions
flightdeck_sensor-0.5.3-py3-none-any.whl Python 3 none any Details for flightdeck_sensor-0.5.3-py3-none-any.whl

Total release size: 360.0 kB

Release files / flightdeck_sensor-0.5.3.tar.gz

Download URL flightdeck_sensor-0.5.3.tar.gz
Size 211.1 kB
Tags Source
SHA-256 checksum
How to use checksums
7e39d9758592d313cecc761109fe7c833e3a1e3bf7302df119ac7e3b4dca979f
BLAKE2b-256 checksum
How to use checksums
399d37e891c2316b60cd7af759eb9ea451ecbbf0cf603662bd69f80f376bb36a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Aug 30, 2026.

Transparency log

Release files / flightdeck_sensor-0.5.3-py3-none-any.whl

Download URL flightdeck_sensor-0.5.3-py3-none-any.whl
Size 148.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
c5839e4292ad8a0a8dc0bae5b2e83a494f1133fbaf3e195fdcf6d1055c95c341
BLAKE2b-256 checksum
How to use checksums
b216c57eb21fc61349bd36788903dbe2830b1b01c0d3c7d000b853cf3090d7d0
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Aug 30, 2026.

Transparency log

Security for flightdeck-sensor 0.5.3

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for flightdeck_sensor-0.5.3.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Aug 30, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page