Feat/langfuse observability for picoclaw

[spacepirate0001]

📝 Description

This PR adds local/self-hosted Langfuse observability to PicoClaw and integrates it with the existing OTEL demo so LLM calls, traces, and evaluations can be monitored end-to-end in Docker Compose.

It builds on OTEL instrumentation by adding a Langfuse-compatible OTLP export path and improving span structure for evaluator targeting.

🗣️ Type of Change

• 🐞 Bug fix (non-breaking change which fixes an issue)
• ✨ New feature (non-breaking change which adds functionality)
• 📖 Documentation update
• ⚡ Code refactoring (no functional changes, no api changes)

🤖 AI Code Generation

• 🤖 Fully AI-generated (100% AI, 0% Human)
• 🛠️ Mostly AI-generated (AI draft, Human verified/modified)
• 👨‍💻 Mostly Human-written (Human lead, AI assisted or none)

🔗 Related Issue

OpenTelemetry Observability for PicoClaw (Edge/Agent Use Cases) #255

📚 Technical Context (Skip for Docs)

• Reference URL:
  • https://langfuse.com/self-hosting/deployment/docker-compose
  • https://langfuse.com/docs/evaluation/evaluation-methods/llm-as-a-judge
• Reasoning:
  • OTEL metrics/logs were already available, but LLM-level product observability and evaluation workflows required Langfuse-native ingestion.
  • Evaluations were noisy when targeting intermediate/tool-call spans; this PR introduces a dedicated final-response span to make evaluator results reliable.
  • Local self-hosted Langfuse was required for demo parity without Langfuse Cloud.

Implemented changes

• Added Langfuse observability config plumbing (config + env).
• Added Langfuse OTLP exporter path in observability initialization.
• Kept existing OTEL collector export, enabling dual export where configured.
• Added/updated LLM span attributes (input/output/model/tokens) for Langfuse/OpenTelemetry conventions.
• Added dedicated final-response span: agent.final_response.
• Added llm.has_output attribute to simplify filtering evaluator targets.
• Extended demo compose stack with local Langfuse services (web, worker, postgres, redis, clickhouse, minio).
• Updated documentation/examples for setup and verification.

🧪 Test Environment

• Hardware: PC (Windows host, Docker Desktop)
• OS: Windows host + Linux containers
• Model/Provider: OpenAI-compatible provider
• Channels: CLI

📸 Evidence (Optional)

Click to view Logs/Screenshots

• Gateway logs show Langfuse OTLP exporter enabled.

docker compose --profile observability --profile gateway logs --tail=50 picoclaw-gateway | grep -i sample_ratio
picoclaw-gateway  | 2026/02/24 22:09:50 [2026-02-24T22:09:50Z] [INFO] otel: OpenTelemetry tracing enabled {endpoint=otel-collector:4317, sample_ratio=1, service_name=picoclaw-gateway}

• Langfuse UI receives traces/observations, including agent.final_response.
• go test ./pkg/agent passes after instrumentation changes.

☑️ Checklist

• My code/docs follow the style of this project.
• I have performed a self-review of my own changes.
• I have updated the documentation accordingly.