feat: add Pydantic Logfire tracing provider (#545)

[SandunYL]

Description

Adds Pydantic Logfire as a third built-in observability/tracing provider alongside Langfuse and
OpenLLMetry, enabled with trace.type: logfire. Logfire is an OpenTelemetry wrapper: the provider
configures the global OTel tracer provider once at startup, and per-framework traced runners wrap each
agent run in a Logfire span carrying the session_id. Deep instrumentation reuses the OpenInference
instrumentors already shipped by the framework extras (OpenAI uses Logfire's native
instrument_openai_agents()). Tracing stays transparent — enabling it is config-only, agent code is
unchanged.

Ships the spec set (design.md, spec.md, plan.md + supporting research) under
docs/specs/545-logfire-tracing/.

Type of Change

• New feature (non-breaking change which adds functionality)
• Documentation update
• Test update

Related Issues

Fixes #545

Changes Made

• New provider ak-py/src/agentkernel/trace/logfire/: Logfire(BaseTrace) with a thread-safe,
  once-guarded init() (logfire.configure(service_name="AgentKernel", send_to_logfire="if-token-present")),
  plus five traced runners (openai, langgraph, crewai, adk, smolagents) that wrap
  super().run() in logfire.span(...) and set input/output attributes.
• Framework coverage: OpenAI via native logfire.instrument_openai_agents(); CrewAI and Google ADK
  via the OpenInference instrumentors already in those extras; LangGraph and Smolagents are span-level.
• Factory trace/trace.py: added logfire to _BUILTIN_TRACERS and a require_extra-wrapped
  build branch (missing SDK → friendly pip install "agentkernel[logfire]").
• Config core/config.py: _TraceConfig.type description now lists logfire (default unchanged).
• Dependency pyproject.toml: new logfire = ["logfire>=3.0"] extra.
• Example examples/cli/logfire/: CLI OpenAI agent with trace.type: logfire, README documenting
  LOGFIRE_TOKEN and token-less local mode.
• Tests: extended tests/test_trace.py (logfire missing-extra) and new tests/test_trace_logfire.py
  (factory build, once-guard, span wrapping + attributes, error propagation, native instrumentation,
  runner subclassing).
• Docs: Logfire section in docs/docs/advanced/traceability.md (install, config, credentials,
  coverage table, troubleshooting) + the spec documents.

Testing

• Unit tests pass locally
• Integration tests pass locally
• Manual testing completed
• New tests added for changes

cd ak-py && uv run pytest → 859 passed. New trace tests all pass. The only failures are 3
pre-existing test_cli_tester.py LLM-judge tests that require OPENAI_API_KEY in the environment
(unrelated to this change). Smoke-tested against the real logfire 4.38 SDK: configure, span, and
instrument_openai_agents verified, and all five runners construct/instrument end-to-end.
make lint-check-all is clean.

Checklist

• My code follows the project's style guidelines
• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my feature works
• New and existing unit tests pass locally with my changes
• Any dependent changes have been merged and published

[amithad]

Reviewed against the ak-dev skills (architecture, code quality, testing conventions, new-tracing-provider, write-spec, sync-docs-from-branch). CI is fully green.

Spec set (design.md / spec.md / plan.md / research/) — reviewed before the code. Every factual claim I checked verified against the base branch (trace factory lines, BaseTrace abstract methods, all five framework Module trace-selection sites, the Langfuse/OpenLLMetry reference lines, config/model/factory/test line numbers, pyproject extras). The staged format is followed well: point-form design, a spec that covers error handling, concurrency, and config compatibility, and a plan that orders the spec without restating it.

Implementation vs spec — every requirement extracted from design.md/spec.md is implemented as specified: package layout, once-guarded init(), five runners with the specified instrumentation split, factory branch + _BUILTIN_TRACERS, config description, logfire>=3.0 extra, example, tests, and the traceability docs. One gap is flagged inline (plan Iteration 5 skills sync). The spec's "instrumentors are internally idempotent" claim verifies: Logfire's LogfireTraceProviderWrapper.install returns early when already installed, and the OpenInference instrumentors carry BaseInstrumentor's guard.

Findings (no blockers):

• 2 x [suggestion] inline: docs surfaces beyond traceability.md still list only two providers; the streaming limitation is unstated in the spec and docs.
• 1 x [question] inline: plan Iteration 5's skills sync is not in the PR.
• [question] Staging: a brand-new design.md ships together with spec.md, plan.md, and the full implementation in one commit. The staged spec process expects design.md to survive review cycles before spec/implementation effort goes in. If the design was reviewed elsewhere (e.g. on issue #545), a note in the PR description would make that visible.
• [suggestion] examples/cli/logfire is not in the .github/test-config.yaml e2e inventory. It runs with just OPENAI_API_KEY (token-less local mode), so it could join the matrix cheaply; examples/cli/smolagents is also absent, so there is precedent either way.
• [nit] The branch's single commit message (feature: introduce pydantic logfire as a observarability tool) doesn't follow Conventional Commits (feat:) and has a typo ("observarability"); moot if squash-merged under the PR title.

Nothing was skipped as a duplicate: the PR had no prior review feedback.

[SandunYL]

Thanks for the thorough review, @amithad. Addressed the findings in 78954f4:

Doc surfaces beyond traceability.md (suggestion) — Logfire now listed everywhere the two-provider lists were stale: root README.md (:44, :112), ak-py/README.md (options list + new Pydantic Logfire Setup subsection, and both env-var samples), configuration.md (options/validation lines + a Logfire config block for parity with OpenLLMetry), architecture/overview.md (:42, :141), and agent-skills.md (:99, :127). The ak-dev-sync-docs-from-branch surface map (root README, ak-py/README, docs site) is now covered, and the plan Iteration 5 grep for stale two-provider lists is clean.

Streaming not wrapped (suggestion) — Confirmed against the runners (only run() is overridden). Added a Non-goals bullet in design.md and qualified the traceability.md sentence: session-span wrapping applies to execution.mode: invoke only (matching Langfuse/OpenLLMetry); deep instrumentation still emits LLM/tool spans under stream mode.

Iteration 5 skills sync (question) — Done in-PR rather than deferred. .agents/skills/ak-dev-new-tracing-provider/SKILL.md now has _BUILTIN_TRACERS = ["langfuse", "openllmetry", "logfire"], the factory example's logfire branch, and the updated config description (only one in-repo copy exists — no .claude/skills/ duplicate). Also updated the shipped user skills (ak-add-capabilities now offers Logfire in its tracing prompt, ak-init, ak-build). plan.md Iteration 5 updated to reflect this.

e2e inventory (suggestion) — Added examples/cli/logfire to .github/test-config.yaml (runs token-less with just OPENAI_API_KEY).

Staging / commit-message notes — Re the design-staging question: issue #545 has no design-review thread, so the staged design.md did not go through a separate review cycle before implementation — will keep design in its own reviewable stage on the next feature. The single non-conventional commit is squash-merged under the PR title (feat:), so the message and typo don't reach develop.