Pain001 প্রযুক্তিগত রেফারেন্স: CLI, Python API ও REST

এই রেফারেন্সে pain001 v0.0.57-এর কমান্ড-লাইন ইন্টারফেস, Python API, REST মাইক্রোসার্ভিস ও ভ্যালিডেশন পাইপলাইনের বিবরণ রয়েছে। এখানে তালিকাভুক্ত প্রতিটি ফ্ল্যাগ, এন্ডপয়েন্ট ও আচরণ শিপ করা কোড থেকে নেওয়া, আকাঙ্ক্ষা থেকে নয়।

Pain001 11টি ISO 20022 মেসেজ ডেফিনিশন সমর্থন করে: pain.001.001.03 থেকে pain.001.001.12 পর্যন্ত (Customer Credit Transfer Initiation, দশটি সংস্করণ) এবং pain.008.001.02 (Customer Direct Debit Initiation)।

1. কমান্ড-লাইন ইন্টারফেস#

pain001 এক্সিকিউটেবলটি তার কার্যকারিতা সাবকমান্ডে সাজিয়ে রাখে। কেবল জেনারেশন ফ্ল্যাগ দিয়ে চালালে generate স্বয়ংক্রিয়ভাবে আহ্বান করা হয়, ফলে বিদ্যমান অটোমেশন অপরিবর্তিতভাবে কাজ করতে থাকে।

সাবকমান্ড	উদ্দেশ্য
`generate`	একটি ডেটা ফাইলকে স্কিমা-ভ্যালিডেটেড ISO 20022 XML-এ রূপান্তর করে (ডিফল্ট কমান্ড)।
`validate`	XML না লিখেই ইনপুট ডেটা ভ্যালিডেট করে।
`versions [--json]`	সমর্থিত সব 11টি মেসেজ ডেফিনিশন তালিকাভুক্ত করে।
`inspect [--json]`	একটি মেসেজ টাইপের আবশ্যিক ও ঐচ্ছিক ফিল্ডগুলি দেখায়।
`init [-o DIR]`	একটি মেসেজ টাইপের জন্য প্রারম্ভিক CSV টেমপ্লেট তৈরি করে।
`serve [--host] [--port] [--reload]`	FastAPI REST মাইক্রোসার্ভিস চালু করে (`api` এক্সট্রা প্রয়োজন)।
`mcp`	ইন-ট্রি Model Context Protocol সার্ভার চালু করে (5টি টুল; সম্পূর্ণ 17-টুল সার্ভারটি `pain001-mcp` হিসেবে সরবরাহ করা হয়)।
`plugins list / show / disable`	আবিষ্কৃত লোডার, ভ্যালিডেটর, স্কিম ও রাইটার প্লাগইন পরিদর্শন ও পরিচালনা করে।

`generate` অপশন

ফ্ল্যাগ	বিবরণ
`-t, --xml-message-type`	মেসেজ ডেফিনিশন, যেমন `pain.001.001.09`।
`-d, --data`	ইনপুট ডেটা: `.csv`, `.json`, `.jsonl`, `.db` / `.sqlite`, `.parquet`, অথবা PGP-এনক্রিপ্টেড `.gpg` / `.asc`।
`-o, --output-dir`	যে ডিরেক্টরিতে জেনারেট করা XML রাখা হয়।
`-m, --template` / `-s, --schema`	বান্ডিল করা Jinja2 টেমপ্লেট বা XSD স্কিমা ওভাররাইড করে।
`-c, --config`	একটি কনফিগারেশন প্রোফাইল থেকে ডিফল্ট মান লোড করে (`--profile`, `--show-config`)।
`--dry-run` (উপনাম `--validate-only`)	আউটপুট না লিখেই JSON Schema, XSD ও স্কিম রুলবুকের বিপরীতে ইনপুট ভ্যালিডেট করে।
`--scheme`	একটি স্কিম রুলবুক প্রয়োগ করে: `sepa-sct`, `sepa-inst`, `sepa-sdd`, `sepa-b2b`, অথবা `xborder-ct`।
`--explain --scheme-format {text,json}`	উত্তীর্ণ বা ব্যর্থ প্রতিটি স্কিম নিয়ম রিপোর্ট করে, মানুষ- বা মেশিন-পাঠযোগ্য আকারে।
`--streaming` / `--chunk-size`	বড় ব্যাচের জন্য মেমরি-সীমাবদ্ধ চাঙ্ক-ভিত্তিক প্রক্রিয়াকরণ (ডিফল্ট প্রতি চাঙ্কে 1,000টি লেনদেন; প্রতিটি চাঙ্ক পুনর্গণিত `NbOfTxs` ও `CtrlSum` সহ নিজস্ব XML ফাইলে পরিণত হয়)।
`--emit-metrics`	অবজারভেবিলিটি পাইপলাইনের জন্য মেশিন-পাঠযোগ্য রান মেট্রিক নির্গত করে।

এক্সিট কোডগুলি CI-বান্ধব: 0 সফল, 1 ভ্যালিডেশন ব্যর্থ, 2 ব্যবহারজনিত ত্রুটি।

2. Python API#

from pain001.core.core import process_files

# Generate a validated pain.001.001.09 file from CSV
process_files(
    xml_message_type="pain.001.001.09",
    xml_template_file_path="template.xml",
    xsd_schema_file_path="schema.xsd",
    data_file_path="payments.csv",
    output_dir="out",
)

লেখার আগে প্রতিটি জেনারেট করা ডকুমেন্ট তিনটি স্তর অতিক্রম করে:

ইনপুট ভ্যালিডেশন — প্রতিটি রেকর্ড মেসেজ টাইপের JSON Schema-এর বিপরীতে যাচাই করা হয়, সঙ্গে থাকে ফিল্ড-অ্যালিয়াস নর্মালাইজেশন ও IBAN/BIC সিনট্যাক্স পরীক্ষা।
স্কিম রুলবুক (ঐচ্ছিক) — SEPA SCT, SEPA Instant, SEPA SDD Core, SEPA B2B, অথবা ক্রস-বর্ডার ক্রেডিট ট্রান্সফারের নিয়মাবলি।
XSD ভ্যালিডেশন — ডিস্কে এক বাইটও লেখার আগে রেন্ডার করা XML xmlschema-এর মাধ্যমে অফিসিয়াল ISO 20022 স্কিমার বিপরীতে ভ্যালিডেট করা হয়।

XML জেনারেশন ও স্কিম ভ্যালিডেশনের সময় আর্থিক অঙ্ক decimal.Decimal হিসেবে পরিচালিত হয় — কখনোই IEEE 754 ফ্লোট হিসেবে নয় — এবং NbOfTxs / CtrlSum কন্ট্রোল টোটাল ইনপুট থেকে বিশ্বাস করে নেওয়ার বদলে ভ্যালিডেটেড রেকর্ড থেকে পুনর্গণনা করা হয়।

pain.001 জেনারেশনের বাইরেও কোর লাইব্রেরিটি সরবরাহ করে একটি pain.002 স্ট্যাটাস-রিপোর্ট পার্সার ও জেনারেটর (যাতে আপনি ব্যাংকের গ্রহণ/প্রত্যাখ্যানের উত্তর পড়তে পারেন) এবং দিনশেষের রিকনসিলিয়েশনের জন্য একটি camt.053 স্টেটমেন্ট পার্সার ও জেনারেটর, সেই সঙ্গে একটি VersionMapper যা মেসেজ সংস্করণের মধ্যে রেকর্ড মাইগ্রেট করে।

3. REST মাইক্রোসার্ভিস#

pip install "pain001[api]"
pain001 serve --host 0.0.0.0 --port 8000

সব এন্ডপয়েন্ট /api/v1-এর অধীনে মাউন্ট করা (সঙ্গে একটি সংস্করণহীন /api উপনাম):

মেথড ও পাথ	উদ্দেশ্য
`GET /api/v1/health`	লাইভনেস প্রোব।
`POST /api/v1/validate`	রেকর্ড ভ্যালিডেট করে; ফিল্ড-স্তরের ত্রুটি ফেরত দেয়।
`POST /api/v1/generate`	সিঙ্ক্রোনাস XML জেনারেশন।
`POST /api/v1/generate/async`	ব্যাকগ্রাউন্ড জেনারেশনের জন্য একটি বড় ব্যাচ সারিবদ্ধ করে।
`GET /api/v1/status/{job_id}`	একটি অ্যাসিঙ্ক জব পোল করে।
`GET /api/v1/download/{job_id}`	সম্পন্ন XML ডাউনলোড করে।
`DELETE /api/v1/jobs/{job_id}`	সম্পন্ন একটি জব পরিষ্কার করে।
`GET /metrics`	Prometheus মেট্রিক।

ইন্টারঅ্যাক্টিভ ডকুমেন্টেশন পরিবেশিত হয় /api/docs (Swagger UI), /api/redoc ও /api/reference (Scalar)-এ, আর OpenAPI ডকুমেন্টটি থাকে /openapi.json-এ।

4. ইনপুট নর্মালাইজেশন#

ভ্যালিডেশনের আগে Pain001 বাস্তব জগতের এক্সপোর্টকে বৈধ রেকর্ডে রূপান্তরিত করে:

ফিল্ড অ্যালিয়াস — প্রচলিত ERP কলাম নাম ক্যানোনিক্যাল ফিল্ডে ম্যাপ হয় (উদাহরণস্বরূপ amount → payment_amount)।
IBAN / BIC নর্মালাইজেশন — হোয়াইটস্পেস সরানো হয়, কেস একীভূত করা হয়, তারপর যাচাই করা হয় (IBAN-এর জন্য ISO 13616 mod-97, BIC-এর জন্য ISO 9362 কাঠামো)।
তারিখ — এক্সিকিউশন তারিখের জন্য ISO 8601 YYYY-MM-DD পার্সিং।
অঙ্ক — decimal.Decimal-এর মধ্য দিয়ে পরিচালিত; ত্রুটিপূর্ণ অঙ্ক নীরবে রাউন্ড হওয়ার বদলে ভ্যালিডেশনে ব্যর্থ হয়।
ক্যারেক্টার সেট — ট্রান্সলিটারেশন সহায়কগুলি কনটেন্টকে SWIFT ও SEPA-স্বীকৃত ISO 20022 ল্যাটিন ক্যারেক্টার সেটে নামিয়ে আনে।

5. প্লাগইন আর্কিটেকচার#

স্যুটটি চারটি এন্ট্রি-পয়েন্ট গ্রুপের মাধ্যমে সম্প্রসারণযোগ্য: pain001.loaders, pain001.validators, pain001.schemes এবং pain001.writers। pain001-loader-xlsx এই ব্যবস্থার মাধ্যমেই নিবন্ধিত হয় এবং ইনস্টল করার সঙ্গে সঙ্গে স্বয়ংক্রিয়ভাবে আবিষ্কৃত হয়; pain001-loader-mt101 একটি স্বতন্ত্র পার্সিং লাইব্রেরি যা সরাসরি ব্যবহার করা হয় (এবং MCP সার্ভারের convert_mt101 টুলের মাধ্যমেও)। একটি কিল সুইচ — PAIN001_DISABLE_PLUGINS=1 — কঠোরভাবে নিয়ন্ত্রিত পরিবেশে তৃতীয় পক্ষের প্লাগইন আবিষ্কার সম্পূর্ণরূপে নিষ্ক্রিয় করে।

6. গুণমান গেট#

কোর লাইব্রেরিটি কঠোর, যাচাইযোগ্য গেটের বিপরীতে উন্নয়ন করা হয়: CI-তে প্রয়োগ করা 100% লাইন এবং ব্রাঞ্চ কভারেজ (--cov-fail-under=100), কঠোর mypy টাইপিং, 100% ডকস্ট্রিং কভারেজ এবং সিকিউরিটি লিন্টিং (Bandit, pip-audit)। প্রতিটি রিলিজ বিল্ডের জন্য একটি CycloneDX SBOM তৈরি করা হয়।

এরপর দেখুন ইনস্টলেশন গাইড, AI এজেন্টের জন্য MCP সার্ভার, অথবা পেমেন্ট শব্দকোষ।