الأدلة الإرشادية

من الصفر إلى حكم على تطبيقك الخاص

لديك دالة Python تجيب عن الأسئلة، وتريد أن تعرف ما إذا كانت جيدة بما يكفي لنشرها. ثلاثة أوامر تنقلك من تلك الدالة إلى قرار إصدار، من دون YAML مكتوب يدويًا: يكتب oloproof init --system المشروع حول دالتك، ويقول oloproof check ما إذا كان سيعمل قبل إنفاق أي شيء، ويقرّر oloproof run. كل شيء يعمل على جهازك، من دون حساب ومن دون استدعاءات نماذج.

كل مخرَج أدناه ناتج عن تشغيل هذه الأوامر على الدالة المعروضة.

1. دالتك

أي دالة تأخذ حالة واحدة وتُرجع إجابة. هذه هي bot.py، مع وحدة مساعدة تستوردها:

from prompts import GREETING


def answer(question):
    text = question.lower()
    if "refund" in text:
        reply = "Refunds are available within 30 days of purchase."
    elif "ship" in text:
        reply = "We ship to the US and Canada."
    else:
        reply = "A support agent will follow up within one business day."
    return {"reply": f"{GREETING} {reply}", "topic": "support"}

2. اكتب المشروع حولها

من الدليل الذي يحتوي bot.py:

oloproof init --system bot:answer

Initialized Oloproof project in . around bot:answer
  Each case's input is a string, read from the function's first parameter.

Fill in before a run means anything:
  data/cases.jsonl  3 placeholder cases: give each a real input and, as its expected
                    phrase, words a right answer contains. Add more: see below.
  oloproof.yaml     the check reads the whole answer; if your function returns an
                    object, add `field:` naming the key that holds the text.
  release.yaml      a placeholder bar of 0.80; set the one your release needs.

What this suite can decide, if every case is measured:
  mentions-floor (mentions_expected at least 0.8, 3 cases):
    1 or more pass: INSUFFICIENT_EVIDENCE (not established yet); 0: FAIL
    (ruled out). With 50 cases, PASS from 46; with 100, from 89.

Next: oloproof check, then oloproof run

يُستورَد المرجع أولًا، ولا يُكتب شيء ما لم يُحَل إلى دالة؛ وأي خطأ في وحدتك يتوقف هنا مع ملفه وسطره. لا تُستدعى الدالة. تظهر ثلاثة ملفات: oloproof.yaml (دالتك وفحص واحد)، وdata/cases.jsonl (ثلاث حالات مؤقتة)، وrelease.yaml (العتبة). مُدخل الحالة سلسلة نصية لأن المعامل الأول اسمه question؛ أما المعامل المسمّى case أو inputs أو row أو المُعلَّم بالنوع dict فيتلقى كائنًا بدلًا من ذلك.

الفحص هو contains: تنجح الحالة عندما تحتوي الإجابة على العبارة المتوقعة للحالة. إنه فحص حتمي، فلا يحتاج إلى قياسه مقابل البشر قبل أن يُسمح له بالقرار. يسرد دليل المجموعات كل فحص وحَكَم آخر.

3. املأ الحالات

استبدل الحالات المؤقتة بأسئلة حقيقية والكلمات التي تحتويها الإجابة الصحيحة، حالة واحدة في كل سطر:

{"id": "refund_01", "input": "Can I get a refund?", "expected": {"phrase": "30 days"}}
{"id": "ship_01", "input": "Do you ship to Canada?", "expected": {"phrase": "US and Canada"}}
{"id": "other_01", "input": "My order is late", "expected": {"phrase": "follow up"}}

لا تستطيع ثلاث حالات تجاوز عتبة 0.80، كما يقول الجدول أعلاه: مع ثلاث، أفضل إجابة هي INSUFFICIENT_EVIDENCE. يستخدم التشغيل أدناه 30 حالة مثل هذه، عشر لكل موضوع، ويكفي فيها نجاح 29.

4. افحص قبل التشغيل

oloproof check

قبل ضبط الحقل، كان يقول:

ok   System: callable bot:answer imports.
ok   Called on case refund_01: it answered {"reply": "Thanks for writing in. Refunds are available within 30 days of purchase.", "topic": "support"}

Evaluators on that answer (one case, not a result):
ok   mentions_expected (contains) can read the answer; it passed this case.
note   It reads the whole answer object; `field:` can name one of reply, topic.

لذا أضف field: reply تحت الفحص في oloproof.yaml، وافحص مجددًا:

ok   System: callable bot:answer imports.
ok   Called on case refund_01: it answered {"reply": "Thanks for writing in. Refunds are available within 30 days of purchase.", "topic": "support"}

Evaluators on that answer (one case, not a result):
ok   mentions_expected (contains) can read the answer; it passed this case.

Code: the system's version hashes bot.py, prompts.py. Edit one and the next run calls the system again.

What this suite can decide, if every case is measured:
  mentions-floor (mentions_expected at least 0.8, 30 cases):
    29 or 30 pass: PASS (established); 19 to 28: INSUFFICIENT_EVIDENCE (not
    established yet); 18 or fewer: FAIL (ruled out). With 50 cases, PASS from
    46; with 100, from 89.

CI: no model key is needed for the evaluators. Keys your own function reads are not checked here.

Ready. Next: oloproof run

ما يعنيه كل جزء:

يُستورَد ويُجيب: يُبنى النظام تمامًا كما يبنيه oloproof run، ويُستدعى على الحالة الأولى (يختار --case ID حالة أخرى، ويتخطى --no-call الاستدعاء). إذا رفع استثناءً، يسمّي السطر الخطأ والملف والسطر في شيفرتك.
المقيِّمات: يُشغَّل كل فحص لا يحتاج إلى نموذج على تلك الإجابة الواحدة. والحقل الذي لا يجده يُسمّى مع الحقول التي تملكها الإجابة. النجاح أو الإخفاق هنا حالة واحدة، لا نتيجة. لا يستدعي check حَكَمًا قائمًا على نموذج أبدًا؛ بل يقول ذلك، ويستدعيه التشغيل.
الشيفرة: الملفات التي يشكّل محتواها إصدار النظام: وحدته ووحدات المشروع التي يستوردها، إضافة إلى أي system.code_paths. أما ملف المشروع الذي يُحمَّل أثناء استيراد النظام أو استدعائه وليس من بينها (وحدة تُستورد بالاسم أثناء التنفيذ مثلًا) فيُدرج على أنه غير مُجزَّأ: أضفه إلى code_paths، وإلا فإن تغييره يعيد استخدام إجابات قديمة.
ما يمكنه أن يقرّره: الجدول نفسه الذي يعرضه oloproof plan. ومن دون release.yaml، يقول إن التشغيل يجيب بكلمات بسيطة ولا يقرّر شيئًا.
CI: كل نموذج يستدعيه المشروع والسرّ الذي تحتاجه مهمة CI له، ANTHROPIC_API_KEY أو OPENAI_API_KEY ما لم يسمِّ api_key_env غيره، ولا شيء لخادم على هذا الجهاز.

لا يخزّن check شيئًا. يخرج بالرمز 2 عندما يجب إصلاح شيء و0 خلاف ذلك، ويطبع oloproof check --json النتائج نفسها في مستند واحد.

5. شغّله

oloproof run

Gate: ALLOW (exit 0)
mentions-floor:
  100.0%, range 88.4% to 100.0% (exact binomial interval); 30 of 30 cases

تقرير التشغيل أطول؛ هذا حكمه وسطر القاعدة. نجحت الحالات الثلاثون كلها، ويبدأ النطاق الذي يُحصر فيه المعدل عند 88.4%، فوق عتبة 0.80، لذا تقول القاعدة PASS وتسمح البوابة بالإصدار. يقرؤه oloproof inspect latest مجددًا.