orgchat 0.1.0__tar.gz

orgchat-0.1.0/PKG-INFO

@@ -0,0 +1,114 @@
+Metadata-Version: 2.4
+Name: orgchat
+Version: 0.1.0
+Summary: Production-readiness checks for organization chatbot projects
+Author: Amin
+License: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# OrgChat Check
+
+یک CLI سبک برای اینکه قبل از ساخت یا تحویل چت‌بات سازمانی بفهمیم پروژه در چه وضعیتی است.
+
+دستور اصلی:
+
+```bash
+orgchat check
+```
+
+این دستور هفت سؤال مهم را بررسی می‌کند:
+
+1. داده‌ها کجا هستند و چطور به‌روز می‌شوند؟
+2. هر کاربر به چه اطلاعاتی دسترسی دارد؟
+3. پاسخ درست را چطور اندازه می‌گیریم؟
+4. اگر مدل جواب را نداند چه می‌کند؟
+5. هزینه و latency را چطور می‌بینیم؟
+6. وقتی سیستم خراب شد چه کسی آن را برمی‌گرداند؟
+7. بعد از تحویل چه کسی سیستم را نگهداری می‌کند؟
+
+## نصب محلی
+
+Python 3.11 یا بالاتر لازم است.
+
+```bash
+python -m venv .venv
+source .venv/bin/activate       # Linux/macOS
+# .venv\Scripts\activate       # Windows PowerShell
+pip install -e .
+```
+
+## شروع سریع
+
+در ریشهٔ پروژه‌ای که می‌خواهی بررسی کنی:
+
+```bash
+orgchat init
+```
+
+مقادیر `orgchat.toml` را پر کن و بعد:
+
+```bash
+orgchat check
+```
+
+برای خروجی فایل:
+
+```bash
+orgchat check --format markdown --output orgchat-report.md
+orgchat check --format json --output orgchat-report.json
+```
+
+برای بررسی یک مسیر دیگر:
+
+```bash
+orgchat check --path ./my-chatbot
+```
+
+برای CI:
+
+```bash
+orgchat check --strict
+```
+
+کد خروجی:
+
+- `0`: همهٔ کنترل‌ها عبور کرده‌اند یا فقط هشدار غیرstrict وجود دارد.
+- `1`: حداقل یک کنترل fail شده، یا در حالت `--strict` هشدار وجود دارد.
+- `2`: خطای ورودی، مسیر یا تنظیمات.
+
+## منطق گزارش
+
+`orgchat.toml` منبع اصلی ارزیابی است. مقدارهای صریح `false` یا مسیرهای اشتباه باعث `FAIL` می‌شوند. مقدارهای ثبت‌نشده `WARN` می‌گیرند. CLI در کنار تنظیمات، نام فایل‌ها و پوشه‌های رایج مثل `evals`، `retrieval`، `monitoring` و `runbook` را هم به‌عنوان شواهد کمکی پیدا می‌کند.
+
+شواهد کشف‌شده به‌تنهایی جایگزین تنظیم صریح کنترل‌ها نیستند؛ هدفشان این است که گزارش اولیه از پروژهٔ موجود مفید باشد و مسیر تکمیل را نشان بدهد.
+
+## نمونه خروجی
+
+```text
+ORGCHAT CHECK
+Project: Enterprise Support Chatbot
+Overall: WARN | Score: 64.5/100
+
+Checks:
+  [PASS] 100.0/100  داده و به‌روزبودن
+  [WARN]  55.0/100  ارزیابی کیفیت
+  [FAIL]  40.0/100  دسترسی و امنیت
+
+Next actions:
+  1. دسترسی و امنیت: بازیابی را با مجوزهای همان کاربر فیلتر کن.
+```
+
+## ساختار پروژه
+
+```text
+src/orgchat/
+  checker.py    # منطق هفت کنترل
+  config.py     # خواندن TOML و مسیرها
+  report.py     # خروجی terminal/json/markdown
+  cli.py        # دستورات orgchat check و orgchat init
+tests/
+examples/
+```
+
+این نسخه وضعیت آمادگی عملیاتی را گزارش می‌کند و جایگزین تست امنیتی، ارزیابی مدل یا ممیزی سازمانی کامل نیست.

orgchat-0.1.0/README.md

@@ -0,0 +1,105 @@
+# OrgChat Check
+
+یک CLI سبک برای اینکه قبل از ساخت یا تحویل چت‌بات سازمانی بفهمیم پروژه در چه وضعیتی است.
+
+دستور اصلی:
+
+```bash
+orgchat check
+```
+
+این دستور هفت سؤال مهم را بررسی می‌کند:
+
+1. داده‌ها کجا هستند و چطور به‌روز می‌شوند؟
+2. هر کاربر به چه اطلاعاتی دسترسی دارد؟
+3. پاسخ درست را چطور اندازه می‌گیریم؟
+4. اگر مدل جواب را نداند چه می‌کند؟
+5. هزینه و latency را چطور می‌بینیم؟
+6. وقتی سیستم خراب شد چه کسی آن را برمی‌گرداند؟
+7. بعد از تحویل چه کسی سیستم را نگهداری می‌کند؟
+
+## نصب محلی
+
+Python 3.11 یا بالاتر لازم است.
+
+```bash
+python -m venv .venv
+source .venv/bin/activate       # Linux/macOS
+# .venv\Scripts\activate       # Windows PowerShell
+pip install -e .
+```
+
+## شروع سریع
+
+در ریشهٔ پروژه‌ای که می‌خواهی بررسی کنی:
+
+```bash
+orgchat init
+```
+
+مقادیر `orgchat.toml` را پر کن و بعد:
+
+```bash
+orgchat check
+```
+
+برای خروجی فایل:
+
+```bash
+orgchat check --format markdown --output orgchat-report.md
+orgchat check --format json --output orgchat-report.json
+```
+
+برای بررسی یک مسیر دیگر:
+
+```bash
+orgchat check --path ./my-chatbot
+```
+
+برای CI:
+
+```bash
+orgchat check --strict
+```
+
+کد خروجی:
+
+- `0`: همهٔ کنترل‌ها عبور کرده‌اند یا فقط هشدار غیرstrict وجود دارد.
+- `1`: حداقل یک کنترل fail شده، یا در حالت `--strict` هشدار وجود دارد.
+- `2`: خطای ورودی، مسیر یا تنظیمات.
+
+## منطق گزارش
+
+`orgchat.toml` منبع اصلی ارزیابی است. مقدارهای صریح `false` یا مسیرهای اشتباه باعث `FAIL` می‌شوند. مقدارهای ثبت‌نشده `WARN` می‌گیرند. CLI در کنار تنظیمات، نام فایل‌ها و پوشه‌های رایج مثل `evals`، `retrieval`، `monitoring` و `runbook` را هم به‌عنوان شواهد کمکی پیدا می‌کند.
+
+شواهد کشف‌شده به‌تنهایی جایگزین تنظیم صریح کنترل‌ها نیستند؛ هدفشان این است که گزارش اولیه از پروژهٔ موجود مفید باشد و مسیر تکمیل را نشان بدهد.
+
+## نمونه خروجی
+
+```text
+ORGCHAT CHECK
+Project: Enterprise Support Chatbot
+Overall: WARN | Score: 64.5/100
+
+Checks:
+  [PASS] 100.0/100  داده و به‌روزبودن
+  [WARN]  55.0/100  ارزیابی کیفیت
+  [FAIL]  40.0/100  دسترسی و امنیت
+
+Next actions:
+  1. دسترسی و امنیت: بازیابی را با مجوزهای همان کاربر فیلتر کن.
+```
+
+## ساختار پروژه
+
+```text
+src/orgchat/
+  checker.py    # منطق هفت کنترل
+  config.py     # خواندن TOML و مسیرها
+  report.py     # خروجی terminal/json/markdown
+  cli.py        # دستورات orgchat check و orgchat init
+tests/
+examples/
+```
+
+این نسخه وضعیت آمادگی عملیاتی را گزارش می‌کند و جایگزین تست امنیتی، ارزیابی مدل یا ممیزی سازمانی کامل نیست.

orgchat-0.1.0/pyproject.toml

@@ -0,0 +1,19 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "orgchat"
+version = "0.1.0"
+description = "Production-readiness checks for organization chatbot projects"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "Amin" }]
+dependencies = []
+
+[project.scripts]
+orgchat = "orgchat.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

orgchat-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

orgchat-0.1.0/src/orgchat/__init__.py

@@ -0,0 +1,3 @@
+"""OrgChat project readiness checker."""
+
+__version__ = "0.1.0"

orgchat-0.1.0/src/orgchat/__main__.py

@@ -0,0 +1,5 @@
+from .cli import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

orgchat-0.1.0/src/orgchat/checker.py

@@ -0,0 +1,341 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import date, datetime, timedelta, timezone
+from pathlib import Path
+from typing import Any, Callable
+
+from .config import load_config, resolve_project_path, section
+from .models import CheckResult, Finding, Report
+
+
+@dataclass(frozen=True)
+class Signal:
+    key: str
+    label: str
+    kind: str
+    points: float
+    recommendation: str
+    field: str
+
+
+CHECK_DEFINITIONS: list[dict[str, Any]] = [
+    {
+        "key": "data_sources",
+        "title": "داده و به‌روزبودن",
+        "question": "داده‌ها کجا هستند و چطور به‌روز می‌شوند؟",
+        "patterns": ["minio", "s3", "storage", "ingest", "sync", "etl", "pipeline", "freshness"],
+        "signals": [
+            Signal("sources", "منابع داده مشخص شده‌اند", "list", 25, "منبع‌های واقعی مثل MinIO، PostgreSQL یا S3 را در orgchat.toml ثبت کن.", "sources"),
+            Signal("freshness_slo_minutes", "حد به‌روزبودن داده مشخص است", "number", 20, "برای داده‌ها یک بازهٔ مجاز تأخیر تعیین کن.", "freshness_slo_minutes"),
+            Signal("sync_monitoring", "همگام‌سازی پایش می‌شود", "bool", 20, "برای شکست یا عقب‌افتادن ingestion هشدار تعریف کن.", "sync_monitoring"),
+            Signal("owner", "مالک داده مشخص است", "text", 20, "یک مالک مشخص برای صحت و به‌روزبودن داده تعیین کن.", "owner"),
+            Signal("refresh_test", "تست تازه‌سازی وجود دارد", "bool", 15, "یک تست قابل‌اجرا برای refresh یا ingestion اضافه کن.", "refresh_test"),
+        ],
+    },
+    {
+        "key": "access_control",
+        "title": "دسترسی و امنیت",
+        "question": "هر کاربر به چه اطلاعاتی دسترسی دارد؟",
+        "patterns": ["auth", "rbac", "acl", "permission", "tenant", "jwt", "oidc", "oauth", "audit"],
+        "signals": [
+            Signal("auth", "احراز هویت فعال است", "text", 20, "یک روش احراز هویت سازمانی مثل OIDC، OAuth یا JWT ثبت کن.", "auth"),
+            Signal("rbac", "نقش‌ها و مجوزها تعریف شده‌اند", "bool", 25, "RBAC را برای نقش‌های کاربر، مدیر و اپراتور تعریف کن.", "rbac"),
+            Signal("document_level_filters", "فیلتر دسترسی در سطح سند وجود دارد", "bool", 25, "بازیابی را با مجوزهای همان کاربر فیلتر کن.", "document_level_filters"),
+            Signal("audit_log", "گزارش دسترسی ثبت می‌شود", "bool", 15, "رویدادهای دسترسی و پاسخ‌های حساس را audit کن.", "audit_log"),
+            Signal("secret_scan", "کنترل نشت secrets انجام می‌شود", "bool", 15, "Secret scanning را در مخزن و CI فعال کن.", "secret_scan"),
+        ],
+    },
+    {
+        "key": "quality",
+        "title": "ارزیابی کیفیت",
+        "question": "پاسخ درست را چطور اندازه می‌گیریم؟",
+        "patterns": ["eval", "golden", "benchmark", "quality", "regression"],
+        "signals": [
+            Signal("eval_dataset", "مجموعهٔ ارزیابی وجود دارد", "path", 25, "یک golden dataset واقعی از سؤال‌ها و پاسخ‌های مورد انتظار بساز.", "eval_dataset"),
+            Signal("automated_eval", "ارزیابی خودکار اجرا می‌شود", "bool", 25, "ارزیابی را در CI یا یک job زمان‌بندی‌شده اجرا کن.", "automated_eval"),
+            Signal("regression_gate", "گیت جلوگیری از regression وجود دارد", "bool", 20, "اجازهٔ deploy را به عبور از حداقل امتیاز مشروط کن.", "regression_gate"),
+            Signal("min_score", "حداقل امتیاز کیفیت تعیین شده", "number", 15, "حداقل امتیاز قابل‌قبول را مشخص کن.", "min_score"),
+            Signal("last_evaluation", "ارزیابی اخیر است", "recent", 15, "نتیجهٔ ارزیابی را مرتباً اجرا و تاریخ آخرین اجرا را ثبت کن.", "last_evaluation"),
+        ],
+    },
+    {
+        "key": "grounding",
+        "title": "پاسخ مستند و fallback",
+        "question": "اگر مدل جواب را نداند یا داده کافی نباشد چه می‌کند؟",
+        "patterns": ["retrieval", "citation", "source", "fallback", "abstain", "rerank"],
+        "signals": [
+            Signal("citations", "پاسخ منبع و citation دارد", "bool", 25, "منبع سند و بخش مرتبط را همراه پاسخ نمایش بده.", "citations"),
+            Signal("abstention", "مدل می‌تواند از پاسخ‌سازی خودداری کند", "bool", 25, "برای نبود شواهد، پاسخ صادقانهٔ «اطلاعات کافی نیست» تعریف کن.", "abstention"),
+            Signal("fallback", "مسیر fallback انسانی یا عملیاتی وجود دارد", "bool", 20, "پاسخ‌های کم‌اطمینان را به اپراتور یا مسیر جایگزین بفرست.", "fallback"),
+            Signal("prompt_injection_defense", "دفاع در برابر prompt injection وجود دارد", "bool", 15, "ورودی سند و کاربر را از دستورهای سیستمی جدا و تست کن.", "prompt_injection_defense"),
+            Signal("retrieval_logging", "فرایند بازیابی قابل‌ردگیری است", "bool", 15, "سندها، chunkها و score بازیابی‌شده را برای عیب‌یابی ثبت کن.", "retrieval_logging"),
+        ],
+    },
+    {
+        "key": "observability",
+        "title": "هزینه و مشاهده‌پذیری",
+        "question": "هزینه، latency و کیفیت سرویس را چطور می‌بینیم؟",
+        "patterns": ["telemetry", "tracing", "metrics", "prometheus", "cost", "token", "latency"],
+        "signals": [
+            Signal("tracing", "trace هر درخواست وجود دارد", "bool", 20, "برای هر درخواست trace از ورودی تا retrieval و generation بساز.", "tracing"),
+            Signal("token_cost_tracking", "هزینهٔ token یا inference ثبت می‌شود", "bool", 25, "هزینه را به پروژه، کاربر یا تیم نسبت بده.", "token_cost_tracking"),
+            Signal("request_metrics", "متریک درخواست وجود دارد", "bool", 20, "تعداد درخواست، خطا، latency و نرخ fallback را اندازه بگیر.", "request_metrics"),
+            Signal("latency_slo_ms", "SLO پاسخ مشخص است", "number", 15, "یک latency هدف برای پاسخ تعیین کن.", "latency_slo_ms"),
+            Signal("dashboard", "داشبورد قابل‌استفاده وجود دارد", "path", 20, "یک داشبورد برای وضعیت و روندهای سرویس نگه‌دار.", "dashboard"),
+        ],
+    },
+    {
+        "key": "monitoring",
+        "title": "مانیتورینگ و بازیابی",
+        "question": "وقتی سیستم خراب شد چه کسی و با چه روشی آن را برمی‌گرداند؟",
+        "patterns": ["monitor", "health", "alert", "sentry", "incident", "watchdog", "backup"],
+        "signals": [
+            Signal("healthcheck", "health check تعریف شده", "text", 20, "یک endpoint یا دستور health check قابل‌اجرا ثبت کن.", "healthcheck"),
+            Signal("error_logging", "خطاها ثبت می‌شوند", "bool", 25, "خطاهای backend، retrieval و مدل را با context کافی ذخیره کن.", "error_logging"),
+            Signal("alerts", "هشدار عملیاتی وجود دارد", "bool", 20, "برای خطا، latency، هزینه و افت کیفیت alert بساز.", "alerts"),
+            Signal("backup_restore_test", "بازیابی تست شده است", "bool", 15, "backup را فقط نگیر؛ restore آن را دوره‌ای تست کن.", "backup_restore_test"),
+            Signal("incident_runbook", "راهنمای incident وجود دارد", "path", 20, "برای خرابی مدل، منبع داده و سرویس یک runbook بنویس.", "incident_runbook"),
+        ],
+    },
+    {
+        "key": "ownership",
+        "title": "مالکیت و نگهداری",
+        "question": "بعد از تحویل، چه کسی سیستم را نگهداری می‌کند؟",
+        "patterns": ["owner", "maintainer", "runbook", "oncall", "operations", "docs"],
+        "signals": [
+            Signal("service_owner", "مالک سرویس مشخص است", "text", 25, "یک تیم یا فرد پاسخ‌گو برای سرویس تعیین کن.", "service_owner"),
+            Signal("technical_owner", "مالک فنی مشخص است", "text", 20, "مسئول تصمیم‌های فنی و تغییرات معماری را مشخص کن.", "technical_owner"),
+            Signal("oncall", "مسیر on-call مشخص است", "text", 20, "برای incident یک مسیر پاسخ‌گویی واقعی تعیین کن.", "oncall"),
+            Signal("runbook", "runbook اصلی وجود دارد", "path", 20, "نحوهٔ deploy، rollback، عیب‌یابی و refresh را مستند کن.", "runbook"),
+            Signal("review_cadence", "دورهٔ بازبینی مشخص است", "text", 15, "بازبینی ماهانهٔ کیفیت، امنیت و هزینه را در تقویم بگذار.", "review_cadence"),
+        ],
+    },
+]
+
+
+IGNORED_DIRS = {".git", ".venv", "venv", "node_modules", "__pycache__", ".mypy_cache", ".pytest_cache", "dist", "build"}
+
+
+def discover_paths(root: Path, limit: int = 6000) -> list[str]:
+    paths: list[str] = []
+    try:
+        iterator = root.rglob("*")
+        for path in iterator:
+            if len(paths) >= limit:
+                break
+            if any(part in IGNORED_DIRS for part in path.parts):
+                continue
+            if path.is_file():
+                paths.append(path.relative_to(root).as_posix().lower())
+    except OSError:
+        return paths
+    return paths
+
+
+def _evidence(paths: list[str], patterns: list[str]) -> list[str]:
+    matches = []
+    for path in paths:
+        if path.endswith((".md", ".txt")) and path not in {"readme.md", "readme.txt"}:
+            pass
+        if any(pattern in path for pattern in patterns):
+            matches.append(path)
+    return matches[:5]
+
+
+def _as_bool(value: Any) -> bool | None:
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, str):
+        normalized = value.strip().lower()
+        if normalized in {"true", "yes", "1", "on"}:
+            return True
+        if normalized in {"false", "no", "0", "off"}:
+            return False
+    return None
+
+
+def _parse_datetime(value: Any) -> datetime | None:
+    if not isinstance(value, str) or not value.strip():
+        return None
+    text = value.strip().replace("Z", "+00:00")
+    try:
+        parsed = datetime.fromisoformat(text)
+    except ValueError:
+        try:
+            parsed = datetime.combine(date.fromisoformat(text), datetime.min.time())
+        except ValueError:
+            return None
+    if parsed.tzinfo is None:
+        parsed = parsed.replace(tzinfo=timezone.utc)
+    return parsed.astimezone(timezone.utc)
+
+
+def _assess(
+    root: Path,
+    values: dict[str, Any],
+    signal: Signal,
+    evidence: list[str],
+) -> tuple[str, float, str]:
+    present = signal.field in values
+    value = values.get(signal.field)
+
+    if signal.kind == "bool":
+        parsed = _as_bool(value)
+        if parsed is True:
+            return "PASS", signal.points, "فعال است."
+        if parsed is False:
+            return "FAIL", 0.0, "صراحتاً غیرفعال تنظیم شده است."
+        return "WARN", signal.points * 0.35 if evidence else 0.0, "در تنظیمات مشخص نشده است." if not present else "مقدار بولی قابل‌تشخیص نیست."
+
+    if signal.kind == "list":
+        if isinstance(value, list) and value:
+            return "PASS", signal.points, f"{len(value)} مورد ثبت شده است."
+        if present and isinstance(value, list):
+            return "FAIL", 0.0, "فهرست خالی است."
+        return "WARN", signal.points * 0.35 if evidence else 0.0, "در تنظیمات مشخص نشده است."
+
+    if signal.kind == "text":
+        if isinstance(value, str) and value.strip():
+            return "PASS", signal.points, "ثبت شده است."
+        if present:
+            return "FAIL", 0.0, "خالی است."
+        return "WARN", signal.points * 0.35 if evidence else 0.0, "در تنظیمات مشخص نشده است."
+
+    if signal.kind == "path":
+        path = resolve_project_path(root, value)
+        if path and path.exists():
+            try:
+                display_path = path.relative_to(root).as_posix()
+            except ValueError:
+                display_path = str(path)
+            return "PASS", signal.points, f"فایل پیدا شد: {display_path}"
+        if present and isinstance(value, str) and value.strip():
+            return "FAIL", 0.0, f"مسیر پیدا نشد: {value}"
+        return "WARN", signal.points * 0.35 if evidence else 0.0, "مسیر در تنظیمات مشخص نشده است."
+
+    if signal.kind == "number":
+        try:
+            number = float(value)
+        except (TypeError, ValueError):
+            number = 0.0
+        if number > 0:
+            return "PASS", signal.points, f"مقدار {number:g} ثبت شده است."
+        if present:
+            return "FAIL", 0.0, "مقدار باید بزرگ‌تر از صفر باشد."
+        return "WARN", signal.points * 0.35 if evidence else 0.0, "در تنظیمات مشخص نشده است."
+
+    if signal.kind == "recent":
+        parsed = _parse_datetime(value)
+        if parsed is None:
+            if present and value:
+                return "FAIL", 0.0, "تاریخ قابل‌خواندن نیست."
+            return "WARN", signal.points * 0.35 if evidence else 0.0, "تاریخ آخرین اجرا ثبت نشده است."
+        age = datetime.now(timezone.utc) - parsed
+        if age <= timedelta(days=30) and age >= timedelta(days=-1):
+            return "PASS", signal.points, f"آخرین اجرا {age.days} روز قبل بوده است."
+        return "FAIL", 0.0, f"آخرین اجرا {age.days} روز قبل بوده و stale است."
+
+    return "WARN", 0.0, "نوع بررسی ناشناخته است."
+
+
+def _evaluate_check(root: Path, config: dict[str, Any], paths: list[str], definition: dict[str, Any], use_heuristics: bool) -> CheckResult:
+    values = section(config, definition["key"])
+    evidence = _evidence(paths, definition["patterns"]) if use_heuristics else []
+    findings: list[Finding] = []
+
+    for signal in definition["signals"]:
+        status, points, message = _assess(root, values, signal, evidence)
+        findings.append(
+            Finding(
+                key=signal.key,
+                label=signal.label,
+                status=status,
+                points=round(points, 2),
+                max_points=signal.points,
+                message=message,
+                recommendation=signal.recommendation,
+                evidence=evidence[:3] if status != "PASS" else [],
+            )
+        )
+
+    score = round(sum(finding.points for finding in findings), 2)
+    max_score = sum(finding.max_points for finding in findings)
+    if any(finding.status == "FAIL" for finding in findings):
+        status = "FAIL"
+    elif any(finding.status == "WARN" for finding in findings):
+        status = "WARN"
+    else:
+        status = "PASS"
+
+    return CheckResult(
+        key=definition["key"],
+        title=definition["title"],
+        question=definition["question"],
+        status=status,
+        score=score,
+        max_score=max_score,
+        findings=findings,
+        evidence=evidence,
+    )
+
+
+def build_report(root: str | Path, config_path: str | Path | None = None, use_heuristics: bool = True) -> Report:
+    project_root = Path(root).expanduser().resolve()
+    if not project_root.exists() or not project_root.is_dir():
+        raise ValueError(f"Project path is not a directory: {project_root}")
+
+    requested_config = Path(config_path).expanduser() if config_path else None
+    config, loaded_path, loaded = load_config(project_root, requested_config)
+    paths = discover_paths(project_root) if use_heuristics else []
+    checks = [_evaluate_check(project_root, config, paths, definition, use_heuristics) for definition in CHECK_DEFINITIONS]
+
+    total = sum(check.score for check in checks)
+    maximum = sum(check.max_score for check in checks)
+    score = round((total / maximum) * 100, 1) if maximum else 0.0
+    if any(check.status == "FAIL" for check in checks):
+        overall_status = "FAIL"
+    elif any(check.status == "WARN" for check in checks):
+        overall_status = "WARN"
+    else:
+        overall_status = "PASS"
+
+    failed = sum(check.status == "FAIL" for check in checks)
+    warned = sum(check.status == "WARN" for check in checks)
+    if overall_status == "PASS":
+        analysis = "هر هفت محور اصلی کنترل شده‌اند و شواهد لازم در تنظیمات پروژه ثبت شده است."
+    elif overall_status == "FAIL":
+        analysis = f"پروژه هنوز آمادهٔ تحویل سازمانی نیست؛ {failed} محور دارای شکاف جدی و {warned} محور نیازمند تکمیل است."
+    elif not loaded:
+        analysis = "فایل orgchat.toml پیدا نشد؛ این گزارش فقط یک baseline اولیه است و برای ارزیابی واقعی باید تنظیمات پروژه ثبت شود."
+    else:
+        analysis = f"پروژه در وضعیت میانی است؛ {warned} محور نیازمند تکمیل است و هنوز FAIL جدی ثبت نشده."
+
+    actions: list[str] = []
+    for check in checks:
+        for finding in check.findings:
+            if finding.status != "PASS":
+                actions.append(f"{check.title}: {finding.recommendation}")
+    actions = actions[:8]
+
+    project_section = section(config, "project")
+    project_name = project_section.get("name") if isinstance(project_section.get("name"), str) else project_root.name
+    config_display = None
+    if loaded_path:
+        try:
+            config_display = loaded_path.relative_to(project_root).as_posix()
+        except ValueError:
+            config_display = str(loaded_path)
+
+    return Report(
+        project=project_name or project_root.name,
+        root=str(project_root),
+        config_file=config_display,
+        config_loaded=loaded,
+        generated_at=datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"),
+        overall_status=overall_status,
+        score=score,
+        analysis=analysis,
+        checks=checks,
+        next_actions=actions,
+    )

orgchat-0.1.0/src/orgchat/cli.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+import sys
+
+from . import __version__
+from .checker import build_report
+from .report import render
+from .templates import CONFIG_TEMPLATE
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="orgchat",
+        description="Check production readiness of an organization chatbot project.",
+    )
+    parser.add_argument("--version", action="version", version=f"orgchat-check {__version__}")
+    subparsers = parser.add_subparsers(dest="command")
+
+    check = subparsers.add_parser("check", help="Run the seven organization-chatbot readiness checks.")
+    check.add_argument("--path", default=".", help="Project root to inspect. Default: current directory")
+    check.add_argument("--config", help="Path to an orgchat.toml file")
+    check.add_argument("--format", choices=["terminal", "json", "markdown"], default="terminal")
+    check.add_argument("--output", help="Write the rendered report to this file")
+    check.add_argument("--no-heuristics", action="store_true", help="Only use explicit orgchat.toml values")
+    check.add_argument("--strict", action="store_true", help="Return exit code 1 for WARN as well as FAIL")
+
+    init = subparsers.add_parser("init", help="Create a starter orgchat.toml file.")
+    init.add_argument("--path", default=".", help="Project root. Default: current directory")
+    init.add_argument("--force", action="store_true", help="Overwrite an existing orgchat.toml")
+    return parser
+
+
+def _write_report(content: str, output: str) -> None:
+    destination = Path(output).expanduser().resolve()
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    destination.write_text(content, encoding="utf-8")
+
+
+def _run_init(path: str, force: bool) -> int:
+    root = Path(path).expanduser().resolve()
+    root.mkdir(parents=True, exist_ok=True)
+    destination = root / "orgchat.toml"
+    if destination.exists() and not force:
+        print(f"File already exists: {destination}. Use --force to overwrite.", file=sys.stderr)
+        return 1
+    destination.write_text(CONFIG_TEMPLATE, encoding="utf-8")
+    print(f"Created {destination}")
+    print("Run `orgchat check` after filling the values.")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _parser()
+    args = parser.parse_args(argv)
+
+    if args.command == "init":
+        return _run_init(args.path, args.force)
+
+    if args.command != "check":
+        parser.print_help()
+        return 2
+
+    try:
+        report = build_report(
+            root=args.path,
+            config_path=args.config,
+            use_heuristics=not args.no_heuristics,
+        )
+        content = render(report, args.format)
+        if args.output:
+            _write_report(content, args.output)
+            print(f"Report written to {Path(args.output).expanduser().resolve()}")
+        else:
+            print(content, end="")
+    except (OSError, ValueError) as exc:
+        print(f"orgchat check failed: {exc}", file=sys.stderr)
+        return 2
+
+    if report.overall_status == "FAIL":
+        return 1
+    if args.strict and report.overall_status == "WARN":
+        return 1
+    return 0

orgchat-0.1.0/src/orgchat/config.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+import tomllib
+from pathlib import Path
+from typing import Any
+
+
+class ConfigError(ValueError):
+    """Raised when orgchat.toml cannot be loaded."""
+
+
+def load_config(root: Path, config_path: Path | None = None) -> tuple[dict[str, Any], Path | None, bool]:
+    path = config_path or (root / "orgchat.toml")
+    if not path.is_absolute():
+        path = (root / path).resolve()
+
+    if not path.exists():
+        return {}, None, False
+
+    try:
+        with path.open("rb") as handle:
+            data = tomllib.load(handle)
+    except tomllib.TOMLDecodeError as exc:
+        raise ConfigError(f"Invalid TOML in {path}: {exc}") from exc
+    except OSError as exc:
+        raise ConfigError(f"Cannot read {path}: {exc}") from exc
+
+    if not isinstance(data, dict):
+        raise ConfigError(f"The configuration root must be a TOML table: {path}")
+    return data, path, True
+
+
+def section(config: dict[str, Any], name: str) -> dict[str, Any]:
+    value = config.get(name, {})
+    return value if isinstance(value, dict) else {}
+
+
+def resolve_project_path(root: Path, value: Any) -> Path | None:
+    if not isinstance(value, str) or not value.strip():
+        return None
+    text = value.strip()
+    if text.startswith(("http://", "https://", "cmd:", "/health", "health://")):
+        return None
+    candidate = Path(text)
+    if not candidate.is_absolute():
+        candidate = root / candidate
+    return candidate.resolve()

orgchat-0.1.0/src/orgchat/models.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from typing import Any
+
+
+@dataclass
+class Finding:
+    key: str
+    label: str
+    status: str
+    points: float
+    max_points: float
+    message: str
+    recommendation: str
+    evidence: list[str] = field(default_factory=list)
+
+    @property
+    def percentage(self) -> float:
+        if not self.max_points:
+            return 0.0
+        return round((self.points / self.max_points) * 100, 1)
+
+    def to_dict(self) -> dict[str, Any]:
+        value = asdict(self)
+        value["percentage"] = self.percentage
+        return value
+
+
+@dataclass
+class CheckResult:
+    key: str
+    title: str
+    question: str
+    status: str
+    score: float
+    max_score: float
+    findings: list[Finding] = field(default_factory=list)
+    evidence: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        value = asdict(self)
+        value["findings"] = [finding.to_dict() for finding in self.findings]
+        value["percentage"] = round((self.score / self.max_score) * 100, 1) if self.max_score else 0.0
+        return value
+
+
+@dataclass
+class Report:
+    project: str
+    root: str
+    config_file: str | None
+    config_loaded: bool
+    generated_at: str
+    overall_status: str
+    score: float
+    analysis: str
+    checks: list[CheckResult]
+    next_actions: list[str]
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "project": self.project,
+            "root": self.root,
+            "config_file": self.config_file,
+            "config_loaded": self.config_loaded,
+            "generated_at": self.generated_at,
+            "overall_status": self.overall_status,
+            "score": self.score,
+            "analysis": self.analysis,
+            "checks": [check.to_dict() for check in self.checks],
+            "next_actions": self.next_actions,
+        }

orgchat-0.1.0/src/orgchat/report.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from .models import CheckResult, Report
+
+
+def _status(status: str) -> str:
+    return {"PASS": "PASS", "WARN": "WARN", "FAIL": "FAIL"}.get(status, status)
+
+
+def render_terminal(report: Report) -> str:
+    lines = [
+        "ORGCHAT CHECK",
+        f"Project: {report.project}",
+        f"Root: {report.root}",
+        f"Config: {report.config_file or 'orgchat.toml پیدا نشد'}",
+        "",
+        f"Overall: {_status(report.overall_status)} | Score: {report.score}/100",
+        f"Analysis: {report.analysis}",
+        "",
+        "Checks:",
+    ]
+    for check in report.checks:
+        lines.append(f"  [{_status(check.status):4}] {check.score:5.1f}/{check.max_score:g}  {check.title}")
+        lines.append(f"         {check.question}")
+        for finding in check.findings:
+            if finding.status != "PASS":
+                lines.append(f"         - [{finding.status}] {finding.label}: {finding.message}")
+        if check.evidence:
+            lines.append(f"         Evidence: {', '.join(check.evidence[:3])}")
+
+    if report.next_actions:
+        lines.extend(["", "Next actions:"])
+        lines.extend(f"  {index}. {action}" for index, action in enumerate(report.next_actions, start=1))
+
+    lines.extend(["", f"Generated: {report.generated_at}"])
+    return "\n".join(lines)
+
+
+def render_markdown(report: Report) -> str:
+    lines = [
+        f"# OrgChat Check: {report.project}",
+        "",
+        f"- وضعیت کلی: **{report.overall_status}**",
+        f"- امتیاز: **{report.score}/100**",
+        f"- تحلیل: {report.analysis}",
+        f"- مسیر پروژه: `{report.root}`",
+        f"- تنظیمات: `{report.config_file or 'orgchat.toml پیدا نشد'}`",
+        "",
+        "## خلاصهٔ بررسی‌ها",
+        "",
+        "| وضعیت | امتیاز | محور | سؤال اصلی |",
+        "|---|---:|---|---|",
+    ]
+    for check in report.checks:
+        lines.append(f"| {check.status} | {check.score:.1f}/{check.max_score:g} | {check.title} | {check.question} |")
+
+    for check in report.checks:
+        lines.extend(["", f"## {check.title}", "", f"سؤال: {check.question}", ""])
+        for finding in check.findings:
+            lines.append(f"- **{finding.status}** {finding.label}: {finding.message}")
+            if finding.status != "PASS":
+                lines.append(f"  - اقدام: {finding.recommendation}")
+        if check.evidence:
+            lines.append(f"- شواهد پیدا‌شده: `{', '.join(check.evidence)}`")
+
+    if report.next_actions:
+        lines.extend(["", "## اقدام‌های بعدی", ""])
+        lines.extend(f"{index}. {action}" for index, action in enumerate(report.next_actions, start=1))
+    return "\n".join(lines) + "\n"
+
+
+def render_json(report: Report) -> str:
+    return json.dumps(report.to_dict(), ensure_ascii=False, indent=2) + "\n"
+
+
+def render(report: Report, output_format: str) -> str:
+    if output_format == "json":
+        return render_json(report)
+    if output_format == "markdown":
+        return render_markdown(report)
+    return render_terminal(report)

orgchat-0.1.0/src/orgchat/templates.py

@@ -0,0 +1,56 @@
+CONFIG_TEMPLATE = '''# OrgChat readiness configuration
+# Run `orgchat check` from the project root after filling these values.
+
+[project]
+name = "My organization chatbot"
+environment = "staging"
+
+[data_sources]
+sources = []
+freshness_slo_minutes = 1440
+sync_monitoring = false
+owner = ""
+refresh_test = false
+
+[access_control]
+auth = ""
+rbac = false
+document_level_filters = false
+audit_log = false
+secret_scan = false
+
+[quality]
+eval_dataset = "evals/golden.jsonl"
+automated_eval = false
+regression_gate = false
+min_score = 0.8
+last_evaluation = ""
+
+[grounding]
+citations = false
+abstention = false
+fallback = false
+prompt_injection_defense = false
+retrieval_logging = false
+
+[observability]
+tracing = false
+token_cost_tracking = false
+request_metrics = false
+latency_slo_ms = 2000
+dashboard = "ops/dashboard.json"
+
+[monitoring]
+healthcheck = "/health"
+error_logging = false
+alerts = false
+backup_restore_test = false
+incident_runbook = "docs/incident-runbook.md"
+
+[ownership]
+service_owner = ""
+technical_owner = ""
+oncall = ""
+runbook = "docs/runbook.md"
+review_cadence = "monthly"
+'''

orgchat-0.1.0/src/orgchat.egg-info/PKG-INFO

@@ -0,0 +1,114 @@
+Metadata-Version: 2.4
+Name: orgchat
+Version: 0.1.0
+Summary: Production-readiness checks for organization chatbot projects
+Author: Amin
+License: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# OrgChat Check
+
+یک CLI سبک برای اینکه قبل از ساخت یا تحویل چت‌بات سازمانی بفهمیم پروژه در چه وضعیتی است.
+
+دستور اصلی:
+
+```bash
+orgchat check
+```
+
+این دستور هفت سؤال مهم را بررسی می‌کند:
+
+1. داده‌ها کجا هستند و چطور به‌روز می‌شوند؟
+2. هر کاربر به چه اطلاعاتی دسترسی دارد؟
+3. پاسخ درست را چطور اندازه می‌گیریم؟
+4. اگر مدل جواب را نداند چه می‌کند؟
+5. هزینه و latency را چطور می‌بینیم؟
+6. وقتی سیستم خراب شد چه کسی آن را برمی‌گرداند؟
+7. بعد از تحویل چه کسی سیستم را نگهداری می‌کند؟
+
+## نصب محلی
+
+Python 3.11 یا بالاتر لازم است.
+
+```bash
+python -m venv .venv
+source .venv/bin/activate       # Linux/macOS
+# .venv\Scripts\activate       # Windows PowerShell
+pip install -e .
+```
+
+## شروع سریع
+
+در ریشهٔ پروژه‌ای که می‌خواهی بررسی کنی:
+
+```bash
+orgchat init
+```
+
+مقادیر `orgchat.toml` را پر کن و بعد:
+
+```bash
+orgchat check
+```
+
+برای خروجی فایل:
+
+```bash
+orgchat check --format markdown --output orgchat-report.md
+orgchat check --format json --output orgchat-report.json
+```
+
+برای بررسی یک مسیر دیگر:
+
+```bash
+orgchat check --path ./my-chatbot
+```
+
+برای CI:
+
+```bash
+orgchat check --strict
+```
+
+کد خروجی:
+
+- `0`: همهٔ کنترل‌ها عبور کرده‌اند یا فقط هشدار غیرstrict وجود دارد.
+- `1`: حداقل یک کنترل fail شده، یا در حالت `--strict` هشدار وجود دارد.
+- `2`: خطای ورودی، مسیر یا تنظیمات.
+
+## منطق گزارش
+
+`orgchat.toml` منبع اصلی ارزیابی است. مقدارهای صریح `false` یا مسیرهای اشتباه باعث `FAIL` می‌شوند. مقدارهای ثبت‌نشده `WARN` می‌گیرند. CLI در کنار تنظیمات، نام فایل‌ها و پوشه‌های رایج مثل `evals`، `retrieval`، `monitoring` و `runbook` را هم به‌عنوان شواهد کمکی پیدا می‌کند.
+
+شواهد کشف‌شده به‌تنهایی جایگزین تنظیم صریح کنترل‌ها نیستند؛ هدفشان این است که گزارش اولیه از پروژهٔ موجود مفید باشد و مسیر تکمیل را نشان بدهد.
+
+## نمونه خروجی
+
+```text
+ORGCHAT CHECK
+Project: Enterprise Support Chatbot
+Overall: WARN | Score: 64.5/100
+
+Checks:
+  [PASS] 100.0/100  داده و به‌روزبودن
+  [WARN]  55.0/100  ارزیابی کیفیت
+  [FAIL]  40.0/100  دسترسی و امنیت
+
+Next actions:
+  1. دسترسی و امنیت: بازیابی را با مجوزهای همان کاربر فیلتر کن.
+```
+
+## ساختار پروژه
+
+```text
+src/orgchat/
+  checker.py    # منطق هفت کنترل
+  config.py     # خواندن TOML و مسیرها
+  report.py     # خروجی terminal/json/markdown
+  cli.py        # دستورات orgchat check و orgchat init
+tests/
+examples/
+```
+
+این نسخه وضعیت آمادگی عملیاتی را گزارش می‌کند و جایگزین تست امنیتی، ارزیابی مدل یا ممیزی سازمانی کامل نیست.

orgchat-0.1.0/src/orgchat.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+README.md
+pyproject.toml
+src/orgchat/__init__.py
+src/orgchat/__main__.py
+src/orgchat/checker.py
+src/orgchat/cli.py
+src/orgchat/config.py
+src/orgchat/models.py
+src/orgchat/report.py
+src/orgchat/templates.py
+src/orgchat.egg-info/PKG-INFO
+src/orgchat.egg-info/SOURCES.txt
+src/orgchat.egg-info/dependency_links.txt
+src/orgchat.egg-info/entry_points.txt
+src/orgchat.egg-info/top_level.txt
+tests/test_checker.py

orgchat-0.1.0/src/orgchat.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

orgchat-0.1.0/src/orgchat.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+orgchat = orgchat.cli:main

orgchat-0.1.0/src/orgchat.egg-info/top_level.txt

@@ -0,0 +1 @@
+orgchat

orgchat-0.1.0/tests/test_checker.py

@@ -0,0 +1,103 @@
+from __future__ import annotations
+
+from datetime import date
+from pathlib import Path
+import tempfile
+import unittest
+
+from orgchat.checker import build_report
+from orgchat.report import render_json, render_markdown
+
+
+HEALTHY_CONFIG = f'''[project]
+name = "Test Chatbot"
+
+[data_sources]
+sources = ["minio://docs"]
+freshness_slo_minutes = 1440
+sync_monitoring = true
+owner = "Data team"
+refresh_test = true
+
+[access_control]
+auth = "OIDC"
+rbac = true
+document_level_filters = true
+audit_log = true
+secret_scan = true
+
+[quality]
+eval_dataset = "evals/golden.jsonl"
+automated_eval = true
+regression_gate = true
+min_score = 0.8
+last_evaluation = "{date.today().isoformat()}"
+
+[grounding]
+citations = true
+abstention = true
+fallback = true
+prompt_injection_defense = true
+retrieval_logging = true
+
+[observability]
+tracing = true
+token_cost_tracking = true
+request_metrics = true
+latency_slo_ms = 2000
+dashboard = "ops/dashboard.json"
+
+[monitoring]
+healthcheck = "/health"
+error_logging = true
+alerts = true
+backup_restore_test = true
+incident_runbook = "docs/incident-runbook.md"
+
+[ownership]
+service_owner = "AI Platform"
+technical_owner = "Tech lead"
+oncall = "on-call"
+runbook = "docs/runbook.md"
+review_cadence = "monthly"
+'''
+
+
+class CheckerTests(unittest.TestCase):
+    def test_healthy_project_scores_pass(self) -> None:
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            (root / "evals").mkdir()
+            (root / "ops").mkdir()
+            (root / "docs").mkdir()
+            (root / "evals/golden.jsonl").write_text("{}\n", encoding="utf-8")
+            (root / "ops/dashboard.json").write_text("{}", encoding="utf-8")
+            (root / "docs/incident-runbook.md").write_text("# incidents", encoding="utf-8")
+            (root / "docs/runbook.md").write_text("# runbook", encoding="utf-8")
+            (root / "orgchat.toml").write_text(HEALTHY_CONFIG, encoding="utf-8")
+
+            report = build_report(root)
+
+            self.assertEqual(report.overall_status, "PASS")
+            self.assertEqual(report.score, 100.0)
+            self.assertIn("هر هفت محور", report.analysis)
+            self.assertTrue(all(check.status == "PASS" for check in report.checks))
+
+    def test_missing_configuration_is_actionable(self) -> None:
+        with tempfile.TemporaryDirectory() as directory:
+            report = build_report(directory)
+
+            self.assertEqual(report.overall_status, "WARN")
+            self.assertEqual(report.score, 0.0)
+            self.assertIn("orgchat.toml", report.analysis)
+            self.assertGreater(len(report.next_actions), 0)
+
+    def test_renderers_return_expected_formats(self) -> None:
+        with tempfile.TemporaryDirectory() as directory:
+            report = build_report(directory)
+            self.assertIn('"overall_status": "WARN"', render_json(report))
+            self.assertIn("# OrgChat Check", render_markdown(report))
+
+
+if __name__ == "__main__":
+    unittest.main()