{"_id":"@digimetalab/kycos","_rev":"5-e840e4db8303e022db6957c2e8e1d753","name":"@digimetalab/kycos","dist-tags":{"latest":"1.0.4"},"versions":{"1.0.0":{"name":"@digimetalab/kycos","version":"1.0.0","keywords":["kyc","aml","osint","investigation","compliance","risk-assessment","multi-agent","ai"],"author":{"name":"digimetalab","email":"digimetalab@gmail.com"},"license":"MIT","_id":"@digimetalab/kycos@1.0.0","maintainers":[{"name":"digimetalab","email":"digimetalab@gmail.com"}],"homepage":"https://github.com/digimetalab/kycos#readme","bugs":{"url":"https://github.com/digimetalab/kycos/issues"},"bin":{"kycos":"bin/kycos.js"},"dist":{"shasum":"4bf82f2b4ab76e5f92e1314010f42419ad0e5ff9","tarball":"https://registry.npmjs.org/@digimetalab/kycos/-/kycos-1.0.0.tgz","fileCount":45,"integrity":"sha512-IlTgpcb2olcgm1Zu3Qt8CiZr2O1YU/3QKFvBT+PBkpqNYvMbvb8DOXqiOQGkDged5/sfqkImiwO3eVqjo4eePA==","signatures":[{"sig":"MEUCIA5PMzVyoyiUjYj3aHeFgNYHIb/7eKrDgL3HeoRk5RzjAiEAnoSM331i/xER2xbtZG6Coo1jx5vIF3kWrkAKp979w6A=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":258788},"main":"./src/core/orchestrator.js","type":"module","engines":{"node":">=20.0.0"},"gitHead":"c9450ab5d5e15c5fc80fb84772048d40886e9945","scripts":{"lint":"eslint src/","test":"vitest run","start":"node bin/kycos.js","test:watch":"vitest","investigate":"node bin/kycos.js investigate","postinstall":"npx playwright install chromium --with-deps || true"},"_npmUser":{"name":"digimetalab","email":"digimetalab@gmail.com"},"repository":{"url":"git+https://github.com/digimetalab/kycos.git","type":"git"},"_npmVersion":"10.9.7","description":"KYCOS — KYC OSINT Multi-Agent Intelligence System","directories":{},"_nodeVersion":"22.22.2","dependencies":{"ora":"^8.2.0","zod":"^3.24.2","uuid":"^11.1.0","axios":"^1.8.4","boxen":"^7.1.1","chalk":"^5.4.1","lowdb":"^7.0.1","dotenv":"^16.5.0","openai":"^4.85.0","cheerio":"^1.0.0","exceljs":"^4.4.0","figures":"^6.1.0","commander":"^13.1.0","puppeteer":"^24.4.0","cli-table3":"^0.6.5","handlebars":"^4.7.8","node-forge":"^1.3.1","playwright":"^1.51.0","better-sqlite3":"^11.8.0","gradient-string":"^3.0.0","@anthropic-ai/sdk":"^0.39.0","@google/generative-ai":"^0.24.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^3.1.0"},"_npmOperationalInternal":{"tmp":"tmp/kycos_1.0.0_1777726230404_0.6355383266657035","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@digimetalab/kycos","version":"1.0.1","keywords":["kyc","aml","osint","investigation","compliance","risk-assessment","multi-agent","ai"],"author":{"name":"digimetalab","email":"digimetalab@gmail.com"},"license":"MIT","_id":"@digimetalab/kycos@1.0.1","maintainers":[{"name":"digimetalab","email":"digimetalab@gmail.com"}],"homepage":"https://github.com/digimetalab/kycos#readme","bugs":{"url":"https://github.com/digimetalab/kycos/issues"},"bin":{"kycos":"bin/kycos.js"},"dist":{"shasum":"32f1dbf46c3797e9cc4bde888ffcd0b7f8fdfd34","tarball":"https://registry.npmjs.org/@digimetalab/kycos/-/kycos-1.0.1.tgz","fileCount":45,"integrity":"sha512-DUpTi7D+55uiX4+x9Nhx7BZOZjgSQ6W6ivmvUS+fNWvQjTUdWmrm7kOVPQJvn4VUYvCcIka5DqYNK5ujy/nTyQ==","signatures":[{"sig":"MEQCIAfIGbgLUc9YCh7BQI/sDYExB3+8AlG2pGT1Vc0XYXsBAiBWKllwy7W5JVaUOFwCMnZH4gb1PcTIxLoRMPEYzNu1Vg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":258791},"main":"./src/core/orchestrator.js","type":"module","engines":{"node":">=20.0.0"},"gitHead":"876663dc1ba4306e6787d8959178ba58b0a7a998","scripts":{"lint":"eslint src/","test":"vitest run","start":"node bin/kycos.js","test:watch":"vitest","investigate":"node bin/kycos.js investigate","postinstall":"npx playwright install chromium --with-deps || true"},"_npmUser":{"name":"digimetalab","email":"digimetalab@gmail.com"},"repository":{"url":"git+https://github.com/digimetalab/kycos.git","type":"git"},"_npmVersion":"10.9.7","description":"KYCOS — KYC OSINT Multi-Agent Intelligence System","directories":{},"_nodeVersion":"22.22.2","dependencies":{"ora":"^8.2.0","zod":"^3.24.2","uuid":"^11.1.0","axios":"^1.8.4","boxen":"^7.1.1","chalk":"^5.4.1","lowdb":"^7.0.1","dotenv":"^16.5.0","openai":"^4.85.0","cheerio":"^1.0.0","exceljs":"^4.4.0","figures":"^6.1.0","commander":"^13.1.0","puppeteer":"^24.4.0","cli-table3":"^0.6.5","handlebars":"^4.7.8","node-forge":"^1.3.1","playwright":"^1.51.0","better-sqlite3":"^11.8.0","gradient-string":"^3.0.0","@anthropic-ai/sdk":"^0.39.0","@google/generative-ai":"^0.24.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^3.1.0"},"_npmOperationalInternal":{"tmp":"tmp/kycos_1.0.1_1777726412344_0.5080950352313001","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"name":"@digimetalab/kycos","version":"1.0.2","keywords":["kyc","aml","osint","investigation","compliance","risk-assessment","multi-agent","ai"],"author":{"name":"digimetalab","email":"digimetalab@gmail.com"},"license":"MIT","_id":"@digimetalab/kycos@1.0.2","maintainers":[{"name":"digimetalab","email":"digimetalab@gmail.com"}],"homepage":"https://github.com/digimetalab/kycos#readme","bugs":{"url":"https://github.com/digimetalab/kycos/issues"},"bin":{"kycos":"bin/kycos.js"},"dist":{"shasum":"11533c72c979a1d701b516e70c50912d16ef4b13","tarball":"https://registry.npmjs.org/@digimetalab/kycos/-/kycos-1.0.2.tgz","fileCount":46,"integrity":"sha512-Bh5+GqaDAID8KDF7ixJ3lbh8dI+AWC3PXW9iSPBlTMVfsgVE+5G2QnHar+64hPYGPbW5TdCvOPWk3AWcd7HGbw==","signatures":[{"sig":"MEQCIEyVoypxLynK/7VHEtJCTzGUg6DMpU8FhkA4I0PIYghpAiBaS8I6CljBf9Y6z+J4pAnHn70D2VHCO0bX7onv56H3IQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":260105},"main":"./src/core/orchestrator.js","type":"module","engines":{"node":">=20.0.0"},"gitHead":"b8a5bcf00e83d59b059c83e31b4d50d34c8dd0f6","scripts":{"lint":"eslint src/","test":"vitest run","start":"node bin/kycos.js","test:watch":"vitest","investigate":"node bin/kycos.js investigate","postinstall":"npx playwright install chromium --with-deps || true"},"_npmUser":{"name":"digimetalab","email":"digimetalab@gmail.com"},"repository":{"url":"git+https://github.com/digimetalab/kycos.git","type":"git"},"_npmVersion":"10.8.2","description":"KYCOS — KYC OSINT Multi-Agent Intelligence System","directories":{},"_nodeVersion":"20.20.2","dependencies":{"ora":"^8.2.0","zod":"^3.24.2","uuid":"^11.1.0","axios":"^1.8.4","boxen":"^7.1.1","chalk":"^5.4.1","lowdb":"^7.0.1","dotenv":"^16.5.0","openai":"^4.85.0","cheerio":"^1.0.0","exceljs":"^4.4.0","figures":"^6.1.0","commander":"^13.1.0","puppeteer":"^24.4.0","cli-table3":"^0.6.5","handlebars":"^4.7.8","node-forge":"^1.3.1","playwright":"^1.51.0","better-sqlite3":"^11.8.0","gradient-string":"^3.0.0","@anthropic-ai/sdk":"^0.39.0","@google/generative-ai":"^0.24.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^3.1.0"},"_npmOperationalInternal":{"tmp":"tmp/kycos_1.0.2_1777727734943_0.27566355260423525","host":"s3://npm-registry-packages-npm-production"}},"1.0.3":{"name":"@digimetalab/kycos","version":"1.0.3","keywords":["kyc","aml","osint","investigation","compliance","risk-assessment","multi-agent","ai"],"author":{"name":"digimetalab","email":"digimetalab@gmail.com"},"license":"MIT","_id":"@digimetalab/kycos@1.0.3","maintainers":[{"name":"digimetalab","email":"digimetalab@gmail.com"}],"homepage":"https://github.com/digimetalab/kycos#readme","bugs":{"url":"https://github.com/digimetalab/kycos/issues"},"bin":{"kycos":"bin/kycos.js"},"dist":{"shasum":"372c97a6201275135c87bc679dfaaf4213a09d22","tarball":"https://registry.npmjs.org/@digimetalab/kycos/-/kycos-1.0.3.tgz","fileCount":46,"integrity":"sha512-AMwm+s6mwppKl3/p+0/d8m7dm7QtTXnVIj6Mn3AQ/BXDpDcIVJ2aO+BWEOXT1Kml1vE1f4AVuhkpgPrs/gye6w==","signatures":[{"sig":"MEUCIQDkRFwhPB2i1C0pSMafMDUz5PzXObX6putwLpb5r2bFxgIgFQ3S41mfNe3Ap5NNlUKqVROiQ6bQU807dzJuF50wAng=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":263768},"main":"./src/core/orchestrator.js","type":"module","engines":{"node":">=20.0.0"},"gitHead":"cc8c8842e7c2f1e9380919bf9a348b0ba749a9ce","scripts":{"lint":"eslint src/","test":"vitest run","start":"node bin/kycos.js","test:watch":"vitest","investigate":"node bin/kycos.js investigate","postinstall":"npx playwright install chromium --with-deps || true"},"_npmUser":{"name":"digimetalab","email":"digimetalab@gmail.com"},"repository":{"url":"git+https://github.com/digimetalab/kycos.git","type":"git"},"_npmVersion":"10.8.2","description":"KYCOS — KYC OSINT Multi-Agent Intelligence System","directories":{},"_nodeVersion":"20.20.2","dependencies":{"ora":"^8.2.0","zod":"^3.24.2","uuid":"^11.1.0","axios":"^1.8.4","boxen":"^7.1.1","chalk":"^5.4.1","lowdb":"^7.0.1","dotenv":"^16.5.0","openai":"^4.85.0","cheerio":"^1.0.0","exceljs":"^4.4.0","figures":"^6.1.0","commander":"^13.1.0","puppeteer":"^24.4.0","cli-table3":"^0.6.5","handlebars":"^4.7.8","node-forge":"^1.3.1","playwright":"^1.51.0","better-sqlite3":"^11.8.0","gradient-string":"^3.0.0","@anthropic-ai/sdk":"^0.39.0","@google/generative-ai":"^0.24.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^3.1.0"},"_npmOperationalInternal":{"tmp":"tmp/kycos_1.0.3_1777728130235_0.4356891027033323","host":"s3://npm-registry-packages-npm-production"}},"1.0.4":{"name":"@digimetalab/kycos","version":"1.0.4","description":"KYCOS — KYC OSINT Multi-Agent Intelligence System","type":"module","bin":{"kycos":"bin/kycos.js"},"main":"./src/core/orchestrator.js","scripts":{"start":"node bin/kycos.js","investigate":"node bin/kycos.js investigate","test":"vitest run","test:watch":"vitest","lint":"eslint src/","postinstall":"npx playwright install chromium --with-deps || true"},"keywords":["kyc","aml","osint","investigation","compliance","risk-assessment","multi-agent","ai"],"author":{"name":"digimetalab","email":"digimetalab@gmail.com"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/digimetalab/kycos.git"},"publishConfig":{"access":"public"},"engines":{"node":">=20.0.0"},"dependencies":{"@anthropic-ai/sdk":"^0.39.0","@google/generative-ai":"^0.24.0","axios":"^1.8.4","better-sqlite3":"^11.8.0","boxen":"^7.1.1","chalk":"^5.4.1","cheerio":"^1.0.0","cli-table3":"^0.6.5","commander":"^13.1.0","dotenv":"^16.5.0","exceljs":"^4.4.0","figures":"^6.1.0","gradient-string":"^3.0.0","handlebars":"^4.7.8","lowdb":"^7.0.1","node-forge":"^1.3.1","openai":"^4.85.0","ora":"^8.2.0","playwright":"^1.51.0","puppeteer":"^24.4.0","uuid":"^11.1.0","zod":"^3.24.2"},"devDependencies":{"vitest":"^3.1.0"},"_id":"@digimetalab/kycos@1.0.4","gitHead":"7a9b4e65a68ae5ed5a54764132c6f09202693e9a","bugs":{"url":"https://github.com/digimetalab/kycos/issues"},"homepage":"https://github.com/digimetalab/kycos#readme","_nodeVersion":"20.20.2","_npmVersion":"10.8.2","dist":{"integrity":"sha512-ytMOSq7s1MymLxIIPXAxIJj3tYYZxvU0QkXnc9dBdiZW4AVWXA3CoVKxrjkcmLRJtlbbp+Afh3DeWQsY0aSi/Q==","shasum":"98095842bb2c57681bdc79be7cbc698b00f15726","tarball":"https://registry.npmjs.org/@digimetalab/kycos/-/kycos-1.0.4.tgz","fileCount":46,"unpackedSize":263771,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDCEVQaqQ3xruilD+uVny/cp0e8sz2yD3qv+xGM3Bao/AIgIUu5QlFrEpJNUjHf/L7f6OlJ8l4mxQUjHSaHdzm+szg="}]},"_npmUser":{"name":"digimetalab","email":"digimetalab@gmail.com"},"directories":{},"maintainers":[{"name":"digimetalab","email":"digimetalab@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/kycos_1.0.4_1777728247711_0.267078653976244"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-02T12:50:30.315Z","modified":"2026-05-02T13:24:07.979Z","1.0.0":"2026-05-02T12:50:30.558Z","1.0.1":"2026-05-02T12:53:32.500Z","1.0.2":"2026-05-02T13:15:35.101Z","1.0.3":"2026-05-02T13:22:10.409Z","1.0.4":"2026-05-02T13:24:07.869Z"},"bugs":{"url":"https://github.com/digimetalab/kycos/issues"},"author":{"name":"digimetalab","email":"digimetalab@gmail.com"},"license":"MIT","homepage":"https://github.com/digimetalab/kycos#readme","keywords":["kyc","aml","osint","investigation","compliance","risk-assessment","multi-agent","ai"],"repository":{"type":"git","url":"git+https://github.com/digimetalab/kycos.git"},"description":"KYCOS — KYC OSINT Multi-Agent Intelligence System","maintainers":[{"name":"digimetalab","email":"digimetalab@gmail.com"}],"readme":"# KYCOS — KYC OSINT Multi-Agent Intelligence System\n\n```text\n  ██╗  ██╗██╗   ██╗ ██████╗ ██████╗ ███████╗\n  ██║ ██╔╝╚██╗ ██╔╝██╔════╝██╔═══██╗██╔════╝\n  █████╔╝  ╚████╔╝ ██║     ██║   ██║███████╗\n  ██╔═██╗   ╚██╔╝  ██║     ██║   ██║╚════██║\n  ██║  ██╗   ██║   ╚██████╗╚██████╔╝███████║\n  ╚═╝  ╚═╝   ╚═╝    ╚═════╝ ╚═════╝ ╚══════╝\n```\n\n[![Node.js Version](https://img.shields.io/badge/Node.js-20+-success.svg)](https://nodejs.org)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)\n[![NPM Version](https://img.shields.io/npm/v/@digimetalab/kycos.svg)](https://www.npmjs.com/package/@digimetalab/kycos)\n[![Repository](https://img.shields.io/badge/GitHub-kycos-black?logo=github)](https://github.com/digimetalab/kycos)\n\n**KYCOS** is a production-grade, highly scalable Node.js Command Line Interface (CLI) tool designed to orchestrate a cluster of specialized Artificial Intelligence agents. It autonomously conducts deep-tier **Know Your Customer (KYC)**, **Anti-Money Laundering (AML)**, and **Open Source Intelligence (OSINT)** investigations on both individuals and corporate entities.\n\nBy utilizing an advanced multi-agent architecture, KYCOS dramatically reduces the time required for comprehensive due diligence from days to mere seconds.\n\n---\n\n## ✨ Core Features\n\n*   **🧠 Multi-Agent Architecture**: Deploys 7 distinct, specialized AI agents operating concurrently via Node.js `Promise.allSettled()`. Guarantees high fault tolerance; if one intelligence vector fails or times out, the rest of the investigation proceeds uninterrupted.\n*   **🚦 Dynamic AI Router**: Automatically selects the optimal Large Language Model (LLM) for each specific task based on complexity, cost, and privacy requirements. Supports Anthropic Claude 3 Opus, Google Gemini 2.0 Flash, and OpenRouter (GPT-4o).\n*   **📊 Institutional Financial Modeling**: Implements the rigorous Indonesian OJK **5C+2W Credit Assessment Framework** alongside a proprietary 850-point credit scorecard.\n*   **📉 Basel III/IV IRB Insolvency Projection**: Calculates the statistical likelihood of corporate bankruptcy using the **Altman Z-Score**. Autonomously maps outputs to compute Probability of Default (PD), Loss Given Default (LGD), and Expected Credit Loss (ECL) per PSAK 71.\n*   **🕵️ Deep AML & Sanctions Screening**: Cross-references targets against global watchlists (OFAC, UN Security Council, EU Consolidated) and detects structural illicit typologies (e.g., structuring, layering, shell company topologies).\n*   **💾 Local SQLite Persistence & Caching**: All investigations, agent telemetry, red flags, and generated reports are securely persisted to a local `better-sqlite3` database, allowing for instant historical retrieval and strict audit trailing.\n*   **📄 Comprehensive Multi-Format Export**: Generates exhaustive, executive-ready analytical reports in Markdown (MD), PDF, XLSX, HTML, and JSON.\n\n---\n\n## 🏗️ Project Structure\n\nThe codebase is organized into a modular, highly extensible domain-driven architecture:\n\n```text\nkycos/\n├── bin/\n│   └── kycos.js                    # CLI entry point\n├── src/\n│   ├── core/\n│   │   ├── base-agent.js           # Abstract BaseAgent class with error boundaries\n│   │   ├── orchestrator.js         # Investigation planner + parallel dispatcher\n│   │   ├── ai-router.js            # Strategy pattern for LLM routing\n│   │   ├── ai-clients.js           # Lazy-loaded Provider SDK wrappers\n│   │   └── schemas.js              # Zod schemas (AgentResult, RedFlag, etc.)\n│   ├── agents/\n│   │   ├── identity.agent.js       # Name/alias/ID/photo OSINT\n│   │   ├── social.agent.js         # Social media scraping + NLP sentiment\n│   │   ├── financial.agent.js      # 5C+2W scoring + financial ratios + AML\n│   │   ├── legal.agent.js          # Court records + sanctions (OFAC/UN/EU) + PEP\n│   │   ├── digital.agent.js        # WHOIS/Shodan/HIBP/email breach\n│   │   ├── network.agent.js        # UBO relationship graph\n│   │   └── risk.agent.js           # Basel IRB: PD/LGD/EAD/EL + credit scorecard\n│   ├── services/\n│   │   ├── investigation-db.js     # Relational persistence for completed queries\n│   │   ├── scraper.js              # Playwright + Cheerio layer\n│   │   └── cache.js                # SQLite request caching layer\n│   └── reports/\n│       ├── report-engine.js        # Handlebars template renderer\n│       └── md-report.js            # Deep-thinking Markdown report compiler\n├── data/                           # Local SQLite databases (auto-created)\n├── logs/                           # Automated file-logging output\n└── report/                         # Final generated investigation reports\n```\n\n---\n\n## 🧬 Technical Architecture & AI Routing\n\nThe system uses a **Strategy Pattern** for model selection. Instead of relying on a single AI, KYCOS routes tasks to the most efficient LLM:\n\n| Task Type | Designated Model | Engineering Rationale |\n|---|---|---|\n| `narrative_synthesis` | **Claude 3 Opus** | Deepest reasoning and superior logical synthesis. |\n| `data_extraction` | **Gemini 2.0 Flash** | Ultra-high speed structured JSON extraction. |\n| `pattern_matching` | **GPT-4o** (via OpenRouter) | Exceptionally strong at traversing graph topologies and network matching. |\n| `cost_sensitive` | **Claude 3.5 Haiku** | Fallback for rapid, low-complexity tasks. |\n\nThe **Orchestrator** dynamically generates an `InvestigationPlan` using an LLM, dispatches the required agents in parallel via `Promise.allSettled()`, and aggregates their strictly-typed `AgentResult` objects.\n\n---\n\n## 🤖 The 7 Intelligence Agents\n\n### 1. 🪪 Identity Agent\n- **Focus**: Biometric & Persona validation.\n- **Capabilities**: Full name resolution, semantic alias detection, and cryptographic ID number validation format checks (KTP/Passport/NPWP).\n\n### 2. 🌐 Social Agent\n- **Focus**: OSINT Footprinting.\n- **Capabilities**: Scrapes platforms (LinkedIn/X/Facebook), performs NLP sentiment analysis on public posts, and maps lifestyle-to-wealth consistency.\n\n### 3. 💰 Financial Agent (5C+2W & AML)\n**5C+2W Scoring Matrix (OJK Standard):**\n- **Character (20%)**: SLIK kolektibilitas + OSINT sentiment overlay.\n- **Capacity (25%)**: Debt Service Coverage Ratio (DSCR > 1.2x).\n- **Capital (20%)**: Debt-to-Equity (DER < 3x), Equity Ratio.\n- **Collateral (15%)**: LTV haircuts.\n- **Condition (10%)**: Industry macroeconomic risk score.\n- **Willingness (5%)**: Payment behavior consistency.\n- **Wealth (5%)**: LHKPN delta + wealth-income consistency.\n\n**AML Structural Detection:** Actively hunts for transactions clustering below reporting thresholds (Structuring), rapid inter-account transfers (Layering), and Nominee/Shell company signals.\n\n### 4. ⚖️ Legal Agent\n- **Focus**: Compliance & Watchlists.\n- **Capabilities**: Interrogates international sanctions (OFAC SDN, UN, EU Consolidated), determines Political Exposure (PEP), and scans domestic/international civil and criminal litigation dockets.\n\n### 5. 💻 Digital Agent\n- **Focus**: Cyber Exposure.\n- **Capabilities**: Analyzes WHOIS privacy, Shodan device vulnerabilities, HaveIBeenPwned (HIBP) clear-web credential breaches, and extrapolates Dark Web chatter.\n\n### 6. 🔗 Network Agent\n- **Focus**: Graph Topology & UBO.\n- **Capabilities**: Untangles complex corporate ownership chains to isolate the **Ultimate Beneficial Owner (UBO)** and detects anomalous cross-jurisdictional directorships.\n\n### 7. 📊 Risk Agent (Basel III/IV IRB)\n**Altman Z-Score (Probability of Default):**\n`Z = 1.2(X₁) + 1.4(X₂) + 3.3(X₃) + 0.6(X₄) + 1.0(X₅)`\n*(Calculates the statistical likelihood of absolute corporate bankruptcy within a 24-month horizon)*\n\n**Expected Credit Loss (ECL / PSAK 71):**\n`EL = PD × LGD × EAD`\n*(Maps the Z-Score to Probability of Default and applies collateral haircuts to compute provisioning requirements)*\n\n**Proprietary 850-Point Credit Scorecard:**\nCalculates final institutional rating (AAA to D) based on repayment velocity, credit utilization elasticity, credit mix, and an OSINT alternative-data overlay.\n\n---\n\n## 🚀 Installation & Prerequisites\n\n### Prerequisites\n*   **Node.js**: v20.0.0 or higher.\n*   **npm**: v10.0.0 or higher.\n*   **API Keys**: You will need valid API keys from Anthropic, Google AI, and/or OpenRouter.\n\n### Quick Start\n1. Clone the repository and install the dependencies:\n   ```bash\n   git clone https://github.com/digimetalab/kycos.git\n   cd kycos\n   npm install\n   ```\n2. Initialize the environment configuration:\n   ```bash\n   cp .env.example .env\n   ```\n3. Open the `.env` file and populate your secure API keys.\n\n---\n\n## ⚙️ Environment Configuration\n\nConfigure external API keys in your `.env` file:\n\n| Environment Variable | Provider / Purpose | Requirement |\n| :--- | :--- | :--- |\n| `ANTHROPIC_API_KEY` | **Claude 3** (Used for deep narrative synthesis & risk modeling) | **Required** (At least one AI key) |\n| `GOOGLE_AI_API_KEY` | **Gemini 2.0** (Used for high-speed OSINT data extraction) | **Required** (At least one AI key) |\n| `OPENROUTER_API_KEY` | **GPT-4o** (Used for complex network & graph pattern matching) | **Required** (At least one AI key) |\n| `SHODAN_API_KEY` | **Shodan** (Infrastructure & IoT vulnerability scanning) | *Optional* |\n| `HIBP_API_KEY` | **HaveIBeenPwned** (Credential breach exposure) | *Optional* |\n| `OPENCORPORATES_API_KEY`| **OpenCorporates** (Global corporate registry validation) | *Optional* |\n\n---\n\n## 💻 CLI Usage Guide\n\nKYCOS provides an interactive command-line dashboard with real-time progress indicators.\n\n### 1. Run an Investigation\nYou can initiate an investigation interactively (by typing `node bin/kycos.js investigate` without arguments) or via direct flags:\n\n```bash\n# Execute a rapid screening on an individual (Identity, Legal, Risk)\nnode bin/kycos.js investigate -t \"John Doe\" -m quick\n\n# Run a full institutional credit assessment on a corporation\nnode bin/kycos.js investigate -t \"PT Nusantara Teknologi\" --type corporation -m credit\n\n# Execute a deep-dive investigation and output results strictly as JSON\nnode bin/kycos.js investigate -t \"Jane Doe\" -m deep --output json\n```\n\n### 2. Available Investigation Modes\n\n| Execution Mode | Activated AI Agents | Estimated Time | Primary Use Case |\n| :--- | :--- | :--- | :--- |\n| `quick` | Identity, Legal, Risk | ~10 sec | Instant triage and PEP/Sanctions screening. |\n| `standard` | Identity, Legal, Risk, Social, Digital | ~15 sec | Standard vendor or employee onboarding. |\n| `credit` | Identity, Financial, Legal, Network, Risk | ~25 sec | Institutional lending and corporate underwriting. |\n| `deep` | **All 7 Agents** | ~40 sec | Maximum due diligence for high-risk profiles. |\n\n### 3. Database & System Commands\n\n```bash\n# View the local SQLite database history of all past investigations\nnode bin/kycos.js history\n\n# View high-level analytical statistics across all historical data\nnode bin/kycos.js history --stats\n\n# Verify API key connectivity and provider status\nnode bin/kycos.js config --check\n\n# Purge expired data from the local SQLite cache\nnode bin/kycos.js cache --purge\n```\n\n---\n\n## 📝 License\n\nThis project is licensed under the **MIT License**.\n\nYou are free to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, provided that the original copyright notice and permission notice are included in all copies or substantial portions of the Software.\n\n**Disclaimer:** KYCOS is a probabilistic AI intelligence tool. All algorithmic outputs, credit scores, and compliance determinations must be supplemented by institutional human judgment and localized legal counsel.\n","readmeFilename":"README.md"}