arifOS-Langfuse

Files (2)

• SKILL.md
• instrumentation.md · references/

SKILL.md (first lines)

# 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):

```bash
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):

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

## Key Patterns

### Correct span creation (v3 context manager)

```python
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:

```python
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

```bash
# 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

```bash
# 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

From ariffazil/arifOS, AGPL-3.0.

More from ariffazil/arifOS