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

{
  "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

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

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

Push ke Hub

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:

📡 [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
• 06 Referensi modul
• 14 Submit