arifos-langfuse

name	arifOS-Langfuse
description	Instrument arifOS constitutional AI kernel with Langfuse LLM tracing. Use when (1) adding Langfuse tracing to arifOS tool calls, (2) wiring arifOS telemetry to Langfuse cloud or self-hosted, (3) querying arifOS trace data from Langfuse, (4) migrating arifOS mind_reason/heart_critique calls to Langfuse spans. DITEMPA BUKAN DIBERI — Forged, Not Given.

arifOS-Langfuse Skill

Instrument arifOS constitutional AI operations with Langfuse LLM tracing.

Architecture

arifOS Kernel (Python)
  └── arifosmcp/runtime/telemetry.py  ← Telemetry wrapper
        ├── Prometheus metrics (counters, histograms)
        └── Langfuse v3 span tracing  ← HERE
              ├── context manager: with lf.start_as_current_observation() as span
              ├── span.update(input={...}, output={...})
              └── lf.flush()

arifOS uses Langfuse Python SDK v3 with context manager pattern — spans auto-close on exit.

Credentials

arifOS → Langfuse (cloud Japan):

export LANGFUSE_PUBLIC_KEY=pk-lf-YOUR_PUBLIC_KEY
export LANGFUSE_SECRET_KEY=sk-lf-YOUR_SECRET_KEY
export LANGFUSE_HOST=https://jp.cloud.langfuse.com

arifOS → Langfuse (self-hosted on VPS):

export LANGFUSE_HOST=http://langfuse-web:3000
# same keys

Key Patterns

Correct span creation (v3 context manager)

from langfuse import Langfuse

lf = Langfuse(
    public_key=os.getenv("LANGFUSE_PUBLIC_KEY"),
    secret_key=os.getenv("LANGFUSE_SECRET_KEY"),
    host=os.getenv("LANGFUSE_HOST", "https://jp.cloud.langfuse.com")
)

# WRONG — detached span, no active context
lf.start_as_current_observation(as_type="span", name="arifOS::tool-name")
lf.update_current_span(...)

# CORRECT — context manager, span auto-closes
with lf.start_as_current_observation(as_type="span", name="arifOS::tool-name", metadata={...}) as span:
    span.update(input={"tool": tool_name, "actor": actor_id}, output={"verdict": verdict, ...})

Tool call tracing in arifOS

In arifosmcp/runtime/telemetry.py, record_tool_call() method:

with self._lf.start_as_current_observation(
    as_type="span",
    name=f"arifOS::{tool}",
    metadata=_redact(span_meta),
) as span:
    span.update(input={"tool": tool, "actor": actor_id}, output={"verdict": verdict, ...})

After flush() the span appears in Langfuse dashboard under the project.

Environment setup in arifOS container

# Install SDK
pip install langfuse

# In .env (not hardcoded — use env vars)
LANGFUSE_PUBLIC_KEY=pk-lf-...
LANGFUSE_SECRET_KEY=sk-lf-...
LANGFUSE_HOST=https://jp.cloud.langfuse.com
# or for self-hosted:
# LANGFUSE_HOST=http://langfuse-web:3000

arifOS Tracing Scope

Tool	Traced	Priority
arif_judge_deliberate	✅ active	P0
arif_mind_reason	⚠️ pilot	P1
arif_heart_critique	⚠️ pilot	P1
arif_session_init	🔜 next	P2
Others	❌ not wired	—

Workflows

1. Verify arifOS Langfuse wiring

# From inside arifOS container:
docker exec arifosmcp python3 -c "
from arifosmcp.runtime.telemetry import get_telemetry
t = get_telemetry()
print('Langfuse active:', t._lf is not None)
t.record_tool_call(tool='arif_judge_deliberate', verdict='SEAL', latency=0.15,
                  session_id='test', actor_id='arif', metadata={'test': True})
t.flush()
print('Trace sent — check Langfuse dashboard')
"

2. Wire a new tool to Langfuse

1. Find the tool handler in arifosmcp/runtime/tools.py
2. Add trace_tool_call() from telemetry after successful execution
3. Instrument input_hash / output_hash (redacted) + metadata dict
4. Test: send live call, check Langfuse dashboard

3. Inspect traces via API

export LANGFUSE_PUBLIC_KEY=pk-lf-YOUR_PUBLIC_KEY
export LANGFUSE_SECRET_KEY=sk-lf-YOUR_SECRET_KEY
export LANGFUSE_HOST=https://jp.cloud.langfuse.com

# List recent traces
curl -s "$LANGFUSE_HOST/api/public/traces?limit=10" \
  -u "$LANGFUSE_PUBLIC_KEY:$LANGFUSE_SECRET_KEY" | python3 -m json.tool

# Get specific trace
curl -s "$LANGFUSE_HOST/api/public/traces/<trace-id>" \
  -u "$LANGFUSE_PUBLIC_KEY:$LANGFUSE_SECRET_KEY"

4. Add scoring to traces

lf.score_current_trace(name="arifOS-verdict", value=1.0 if verdict == "SEAL" else 0.0)

Troubleshooting

Symptom	Fix
ModuleNotFoundError: No module named 'langfuse'	pip install langfuse in container
AttributeError: 'Langfuse' object has no attribute 'trace'	Use v3 context manager pattern, not .trace()
Context error: No active span	Wrap with with lf.start_as_current_observation() as span:
401 Unauthorized	Check API keys are correct + LANGFUSE_HOST matches region
Traces not appearing after flush	Check LANGFUSE_HOST network access from container
langfuse-web returns 404	Self-hosted needs /api/public/ path prefix

Documentation

• Langfuse Docs: https://langfuse.com/docs
• arifOS Observatory (public): https://arifos.arif-fazil.com/observatory/
• arifOS Langfuse tracing status: Langfuse cloud (jp region) — partial, pilot stage

References

• Full Langfuse instrumentation guide: https://langfuse.com/docs/observability/sdk/instrumentation
• Python SDK v3: https://langfuse.com/docs/sdk/python/sdk-v3
• CLI: https://langfuse.com/docs/api-and-data-platform/features/agent-skill