flightdeck-sensor 0.3.0__tar.gz → 0.5.0__tar.gz

{flightdeck_sensor-0.3.0 → flightdeck_sensor-0.5.0}/Makefile

@@ -1,20 +1,24 @@
 .PHONY: help install build test lint clean
 
+# Resolves through the project's pinned 3.12 venv by default. CI
+# overrides via env: ``PYTHON=python make -C sensor test``.
+PYTHON ?= ./.venv/bin/python
+
 help: ## Show this help
 	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf "  %-12s %s\n", $$1, $$2}'
 
 install: ## Install package in editable mode with dev dependencies
-	pip install -e ".[dev,anthropic,openai]"
+	$(PYTHON) -m pip install -e ".[dev,anthropic,openai]"
 
 build: ## Build wheel and sdist
-	python -m build
+	$(PYTHON) -m build
 
 test: ## Run unit tests
-	pytest tests/unit/ -v
+	$(PYTHON) -m pytest tests/unit/ -v
 
 lint: ## Run mypy and ruff
-	mypy flightdeck_sensor/ --strict
-	ruff check flightdeck_sensor/
+	$(PYTHON) -m mypy flightdeck_sensor/ --strict
+	$(PYTHON) -m ruff check flightdeck_sensor/
 
 clean: ## Remove build artifacts
 	rm -rf dist/ build/ *.egg-info

flightdeck_sensor-0.5.0/PKG-INFO

@@ -0,0 +1,190 @@
+Metadata-Version: 2.4
+Name: flightdeck-sensor
+Version: 0.5.0
+Summary: In-process agent observability sensor for Flightdeck
+License-Expression: Apache-2.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: <3.14,>=3.10
+Requires-Dist: pydantic>=2.0
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.20; extra == 'anthropic'
+Provides-Extra: dev
+Requires-Dist: anthropic>=0.20; extra == 'dev'
+Requires-Dist: crewai>=1.14; extra == 'dev'
+Requires-Dist: httpx>=0.25; extra == 'dev'
+Requires-Dist: langchain-anthropic<1,>=0.1; extra == 'dev'
+Requires-Dist: langchain-mcp-adapters<0.2; extra == 'dev'
+Requires-Dist: langchain-openai<1,>=0.1; extra == 'dev'
+Requires-Dist: langchain<1,>=0.3; extra == 'dev'
+Requires-Dist: langgraph<1; extra == 'dev'
+Requires-Dist: litellm>=1.0; extra == 'dev'
+Requires-Dist: llama-index-llms-anthropic>=0.1; extra == 'dev'
+Requires-Dist: llama-index-llms-openai>=0.1; extra == 'dev'
+Requires-Dist: llama-index-tools-mcp>=0.1; extra == 'dev'
+Requires-Dist: mcp>=1.20; extra == 'dev'
+Requires-Dist: mcpadapt>=0.0.6; extra == 'dev'
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: openai>=1.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: respx>=0.20; extra == 'dev'
+Requires-Dist: ruff>=0.3; extra == 'dev'
+Provides-Extra: litellm
+Requires-Dist: litellm>=1.0; extra == 'litellm'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.20; extra == 'mcp'
+Provides-Extra: openai
+Requires-Dist: openai>=1.0; extra == 'openai'
+Requires-Dist: tiktoken>=0.5; extra == 'openai'
+Description-Content-Type: text/markdown
+
+# flightdeck-sensor
+
+In-process agent observability sensor for [Flightdeck](https://github.com/flightdeckhq/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`:
+
+```bash
+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
+
+```python
+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:
+
+```python
+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.

flightdeck_sensor-0.5.0/README.md

@@ -0,0 +1,141 @@
+# flightdeck-sensor
+
+In-process agent observability sensor for [Flightdeck](https://github.com/flightdeckhq/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`:
+
+```bash
+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
+
+```python
+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:
+
+```python
+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.