ما الذي نديره

أربعة أنواع من الوكلاء، تُشغَّل عبر عمليتك — كلٌّ يقترح، ولا يتصرّف وحده أبدًا.

كيف يُتحكَّم فيه

الفارق ليس لوحة تحكّم برّاقة. بل التوقيع — ولا شيء يتصرّف نيابةً عنك من تلقاء نفسه.

مقيسٌ، لا مُدَّعى

كيف يُصان الوكلاء — لا أرقام استقلاليةٍ مُختلَقة.

البناء — ما يقترح، وما يبوّب، وما يُسجِّل

الوكلاء ليسوا العرض؛ بل التوقيع. وهذه صورته الحقيقية.
يبقى الكود بالإنجليزية — اللغة العالمية للهندسة.

"""MatchTop · an agent — it proposes, it never ships on its own.
Standard library only. The agent raises a hand; a person decides."""

from dataclasses import dataclass, field
from datetime import datetime


@dataclass
class Proposal:
    kind: str          # "restock" | "refund" | "reply" | "reconcile"
    detail: dict
    reason: str
    raised_at: datetime = field(default_factory=datetime.utcnow)
    signed: bool = False   # stays False until a human says yes


def watch_stock(store, floor=3):
    """Low stock is not an order. It is a proposal that waits for a signature."""
    for item in store.low_stock(below=floor):
        yield Proposal(
            kind="restock",
            detail={"sku": item.sku, "qty": item.reorder_qty},
            reason=f"{item.sku} at {item.stock}, below floor of {floor}",
        )

"""MatchTop · the sign-off gate — the one door every proposal must pass.
No action reaches the business side of the system unsigned."""

class PermissionError(Exception): pass


def apply(p: Proposal, signer: str | None = None):
    """Raises unless a human has signed. Nothing else gets this proposal through."""
    if not p.signed or signer is None:
        raise PermissionError("no action ships without a human signature")

    store.execute(p)                      # only reachable after sign-off
    log_signature(p, signer)              # every pass through this gate is recorded

"""MatchTop · the signature log — append-only, who signed what, when.
Nothing is edited after the fact; the record is the record."""

import csv
from pathlib import Path
from datetime import datetime

LOG = Path("signatures.csv")


def log_signature(p: Proposal, signer: str) -> None:
    """One line per signed action — auditable by anyone you point at this file."""
    is_new = not LOG.exists()
    with LOG.open("a", newline="") as f:
        w = csv.writer(f)
        if is_new:
            w.writerow(["raised_at", "kind", "reason", "signer", "signed_at"])
        w.writerow([p.raised_at, p.kind, p.reason, signer, datetime.utcnow()])
    return None                            # handed to the record, not to a black box

ما لا يمكن نسخه

لماذا يتفوّق وكلاءٌ تحت التوقيع على وكلاءٍ يتصرّفون من تلقاء أنفسهم.

الذكاء الاصطناعي المستقلّ لا يمكن أن يُؤتمَن على مالك — يتصرّف أولًا ويفسّر لاحقًا. والصندوق الأسود لا يمكن أن يُدقَّق. والروبوت بلا وجه لا يمكن أن يُجيب عمّا فعل. لهذا لا توجد قائمة أسعارٍ هنا: ننظر إلى ما تحتاج عمليتك إلى إدارته، ونقيسه، ونعرض ما قِسناه.

محفوظٌ بالسرّية

قبل أن يُكتَب سطرٌ واحد، كيف يُصان متجرك وبياناته. هذا الجزء غير قابل للتفاوض.