docs/11-agent-trace.md

# 11 — Agent Trace (Bonus 📡 Sharing is Caring)

## Tujuan

Memenuhi bonus quest **Sharing is Caring**: *"You shared your agent trace on the Hub for everyone to learn from."*

Bukan agregat statistik anonim — melainkan **jejak langkah agent** yang bisa dipelajari: prompt template, output model, sukses/gagal parse, timing per tahap.

## Prinsip privasi

| Data | Log? |
|------|------|
| Teks mimpi lengkap | ❌ **Tidak** |
| Panjang / jumlah kata | ✅ |
| Hash prefix SHA-256 input | ✅ (opsional) |
| Raw output model (JSON blob) | ✅ truncate 4000 char |
| Entitas hasil parse | ✅ ringkasan |
| PII user | ❌ |

## Lokasi file

| Path |用途 |
|------|-----|
| Lokal | `traces/oneiros_agent_traces.jsonl` |
| Hub | Dataset `YOUR_USERNAME/oneiros-agent-traces` |

Buat Dataset di HF: visibility **public**, license MIT.

## Schema satu baris

```json
{
  "trace_id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2026-06-10T14:30:00Z",
  "app_version": "0.1.0",
  "environment": "hf_space",
  "model_id": "Qwen2.5-7B-Instruct-Q4_K_M",
  "input": {
    "dream_char_count": 412,
    "dream_word_count": 78,
    "dream_sha256_prefix": "a1b2c3d4e5f67890"
  },
  "agent_steps": [
    {
      "step": "extract",
      "prompt_template_id": "oneiros_v1",
      "raw_model_output": "{ \"title\": ... }",
      "parse_ok": true,
      "parse_error": null,
      "elapsed_seconds": 12.4
    },
    {
      "step": "render_map",
      "node_count": 6,
      "edge_count": 4,
      "elapsed_seconds": 0.05
    }
  ],
  "result_summary": {
    "mood": "mysterious",
    "title": "The White Deer",
    "entity_counts": {
      "characters": 2,
      "places": 1,
      "symbols": 1
    }
  }
}
```

### Field reference

| Field | Wajib | Keterangan |
|-------|-------|------------|
| `trace_id` | ✅ | UUID v4 |
| `environment` | ✅ | `hf_space` \| `local` |
| `agent_steps[].step` | ✅ | `extract`, `render_map`, ... |
| `prompt_template_id` | ✅ | Versi prompt untuk reproduksi |
| `parse_ok` | ✅ | Boolean |
| `raw_model_output` | ⚪ | Hanya output model, bukan input mimpi |

## API Python

```python
def log_trace(
    dream_text: str,
    raw_model_output: str,
    entities: dict,
    parse_ok: bool,
    parse_error: str | None,
    elapsed_extract: float,
    elapsed_render: float,
    environment: str = "local",
) -> None: ...
```

Panggilan dari `process_dream()`:

```python
import os
lingkungan = "hf_space" if os.getenv("SPACE_ID") else "local"
log_trace(..., environment=lingkungan)
```

## Push ke Hub

```bash
python -c "from storage.trace_logger import push_traces_to_hub; push_traces_to_hub()"
```

Atau upload manual via UI Dataset.

**README Space** harus link:

```markdown
📡 [Agent traces dataset](https://huggingface.co/datasets/YOUR_USERNAME/oneiros-agent-traces)
```

## Target volume

| Fase | Target baris |
|------|--------------|
| Day 3 | ≥5 |
| Day 4 | ≥20 |
| Submit | 50+ (ideal — bukti usage) |

## Contoh pembelajaran untuk orang lain

Dari trace publik, pembaca bisa:

- Melihat seberapa sering parse gagal
- Membandingkan `elapsed_seconds` Space vs lokal
- Mempelajari pola JSON output tanpa membaca mimpi privat

## Dokumen terkait

- [03 Positioning](03-positioning-dan-privasi.md)
- [06 Referensi modul](06-modul-referensi.md)
- [14 Submit](14-submit-dan-bonus.md)