### पर्यावरण सेटअप

**महत्वपूर्ण:** एप्लिकेशन शुरू करने से पहले आपको पर्यावरण चर कॉन्फ़िगर करना होगा। एप्लिकेशन को `NEO4J_PASSWORD` सेट करना आवश्यक है।

प्रोजेक्ट रूट में एक `.env` फ़ाइल बनाएं:```bash
# Copy the sample file
cp infra/env.sample .env

# Edit .env and set your actual passwords
nano .env

**नोट:** यदि `NEO4J_PASSWORD` सेट नहीं है तो एप्लिकेशन प्रारंभ होने में विफल रहेगा। विवरण के लिए [Environment Variables Fix](https://github.com/blevene/bandjacks/blob/HEAD/ENV_VARIABLES_FIX.md) देखें।

### सेवाएं प्रारंभ करना```bash
# Start the FastAPI backend server
uv run uvicorn bandjacks.services.api.main:app --reload --port 8000

# In another terminal, start the Next.js frontend
cd ui && npm run dev

# Access the applications
open http://localhost:8000/docs    # API documentation
open http://localhost:3000         # Frontend UI

> **नोट:** CLI को पर्यावरण चर (NEO4J_PASSWORD, आदि) सेट करने की आवश्यकता होती है। प्रोजेक्ट रूट से चलाएँ जहाँ `.env` स्थित है।

### क्वेरी कमांड्स```bash
# Search for threat intelligence
uv run python -m bandjacks.cli.main query search "ransomware encryption techniques" --top-k 10

# Explore graph relationships
uv run python -m bandjacks.cli.main query graph "attack-pattern--abc123" --depth 2

### दस्तावेज़ निष्कर्षण```bash
# Extract CTI from a document
uv run python -m bandjacks.cli.main extract document ./report.pdf --confidence-threshold 80 --show-evidence

### कार्यप्रवाह कमांड्स```bash
# Process a directory of reports with analytics
uv run python -m bandjacks.cli.main workflow process-reports ./reports/ --workers 3 --analyze --export-dir ./results/

# Bulk export all analytics data
uv run python -m bandjacks.cli.main workflow bulk-export --export-dir ./analytics_export/

## फ्रंटएंड UI

Next.js फ्रंटएंड सिस्टम के साथ काम करने के लिए एक आधुनिक इंटरफ़ेस प्रदान करता है।

### रिपोर्ट प्रबंधन (`/reports`)
- **रिपोर्ट सूची**: सभी इन्जेस्ट की गई रिपोर्टों को स्थिति और तकनीक गणना के साथ देखें
- **नई रिपोर्ट** (`/reports/new`): PDF/TXT फ़ाइलें अपलोड करें या रिपोर्ट सामग्री पेस्ट करें
- **रिपोर्ट विवरण** (`/reports/[id]`): निकाली गई तकनीकों, संस्थाओं और साक्ष्यों को देखें
- **समीक्षा इंटरफ़ेस** (`/reports/[id]/review`): मानव-इन-द-लूप समीक्षा वर्कफ़्लो

### सह-घटना विश्लेषण (`/analytics/cooccurrence`)

> **नोट:** इन पृष्ठों के लिए Neo4j में `AttackEpisode` डेटा आवश्यक है। पहले निष्कर्षण पाइपलाइन के माध्यम से रिपोर्ट प्रोसेस करें, या घुसपैठ सेट डेटा से एपिसोड उत्पन्न करने के लिए `POST /v1/flows/build` का उपयोग करें।

- **हब पेज**: एपिसोड/तकनीक/अभिनेता गणना के साथ अवलोकन
- **शीर्ष जोड़ी** (`/pairs`): NPMI/Lift मीट्रिक के साथ सह-घटित तकनीक जोड़ियां
- **सशर्त** (`/conditional`): सशर्त संभावनाएं P(B|A)
- **बंडल** (`/bundles`): बार-बार सह-घटित तकनीक बंडल
- **अभिनेता** (`/actors`): अभिनेता-विशिष्ट तकनीक पैटर्न
- **ब्रिजिंग** (`/bridging`): कई अभिनेताओं में उपयोग की जाने वाली तकनीकें

### सिस्टम स्वास्थ्य (`/health`)
- सभी घटकों (Neo4j, OpenSearch, Redis) की वास्तविक समय स्वास्थ्य स्थिति
- कैश सांख्यिकी और मेमोरी उपयोग
- Kubernetes-संगत स्वास्थ्य एंडपॉइंट

### फ्रंटएंड प्रारंभ करना```bash
cd ui
npm run dev     # Development mode with hot reload
npm run build   # Production build
npm run start   # Start production server

# Ensure backend is running
# API_URL defaults to http://localhost:8000/v1

### 2. रिपोर्टों से तकनीकें निकालना

MITRE ATT&CK तकनीकों को खतरे की खुफिया रिपोर्टों से निकालें:```python
import httpx
import time

# For small reports (<5KB) - synchronous processing
response = httpx.post(
    "http://localhost:8000/v1/reports/ingest",
    json={
        "content": "APT29 used spearphishing emails with malicious attachments...",
        "title": "APT29 Campaign Analysis",
        "config": {
            "use_optimized_extractor": True,
            "span_score_threshold": 0.7,
            "top_k": 5
        }
    }
)

result = response.json()
print(f"Extracted {len(result['extraction']['techniques'])} techniques")

# For large reports (>5KB) - asynchronous processing
response = httpx.post(
    "http://localhost:8000/v1/reports/ingest_async",
    json={
        "content": large_report_text,
        "title": "Large Report Analysis"
    }
)

job_id = response.json()["job_id"]

# Check job status
status = httpx.get(f"http://localhost:8000/v1/reports/jobs/{job_id}/status")
while status.json()["status"] == "processing":
    time.sleep(2)
    status = httpx.get(f"http://localhost:8000/v1/reports/jobs/{job_id}/status")

# Get results from completed job
result = status.json()["result"]
print(f"Extracted {result['techniques_count']} techniques in {result['elapsed_time']} seconds")

## निष्कर्षण पाइपलाइन आर्किटेक्चर

Bandjacks निष्कर्षण पाइपलाइन संरचित खतरा खुफिया जानकारी निकालने के लिए एक मल्टी-एजेंट आर्किटेक्चर का उपयोग करती है:

### पाइपलाइन घटक

निष्कर्षण पाइपलाइन क्रम में 9 विशेष एजेंटों का उपयोग करती है:

#### 1. **EntityExtractionAgent** - एंटिटी पहचान
- खतरे के अभिनेताओं, मैलवेयर, टूल्स और अभियानों को निकालता है
- तकनीक निष्कर्षण के लिए संदर्भ प्रदान करने के लिए पहले चलता है
- JSON स्कीमा सत्यापन के साथ फ्यू-शॉट प्रॉम्प्टिंग का उपयोग करता है
- प्रगतिशील विंडोड निष्कर्षण के साथ खंडित दस्तावेज़ों को संभालता है

#### 2. **SpanFinderAgent** - व्यवहारिक टेक्स्ट डिटेक्शन
- 14 टैक्टिक-विशिष्ट रीजेक्स पैटर्न का उपयोग करके खतरे के व्यवहार वाले टेक्स्ट स्पैन का पता लगाता है
- स्पष्ट तकनीक ID (T1566.001) और व्यवहार पैटर्न की पहचान करता है
- कीवर्ड इंडेक्स बूस्टिंग के साथ कॉन्फिडेंस द्वारा स्पैन को स्कोर करता है
- कोई LLM कॉल नहीं — गति के लिए शुद्ध पैटर्न मैचिंग

#### 3. **BatchRetrieverAgent** - उम्मीदवार पुनर्प्राप्ति
- प्रति स्पैन उम्मीदवार तकनीक खोजने के लिए OpenSearch KNN वेक्टर सर्च का उपयोग करता है
- अनावश्यक एम्बेडिंग से बचने के लिए एन्कोडिंग से पहले समान स्पैन टेक्स्ट को डीडुप्लिकेट करता है
- प्रत्येक स्पैन के लिए समानता स्कोर के साथ टॉप-के उम्मीदवार लौटाता है

#### 4. **प्री-फिल्टर** - स्पैन कमी
- स्पैन को प्रति उम्मीदवार तकनीक `max_spans_per_technique` (डिफ़ॉल्ट 2) तक सीमित करता है
- साक्ष्य गुणवत्ता बनाए रखने के लिए प्रति उम्मीदवार उच्चतम-स्कोरिंग स्पैन रखता है
- न्यूनतम तकनीक हानि के साथ मैपर LLM कॉल को ~46% तक कम करता है

#### 5. **DiscoveryAgent** - LLM खोज (सशर्त)
- जब रिट्रीवर कॉन्फिडेंस कम होता है (<0.7 औसत) तब ट्रिगर होता है
- वेक्टर सर्च द्वारा छूटी तकनीकों को खोजने के लिए LLM का उपयोग करता है
- सभी कम-कॉन्फिडेंस स्पैन के लिए एकल बैच कॉल

#### 6. **BatchMapperAgent** - तकनीक मैपिंग (LLM)
- स्पैन को अधिकतम 10 के समूहों में बैच प्रोसेस करता है (`MAX_MAPPER_BATCH_SIZE`, डिफ़ॉल्ट 2026-05 में 25 से कम करके क्लाउड-LLM ट्रंकेशन को सीमित करने के लिए)
- प्रति स्पैन कॉन्फिडेंस स्कोर के साथ सभी प्रासंगिक तकनीकें निकालता है
- संरचित आउटपुट के लिए JSON स्कीमा सत्यापन का उपयोग करता है

#### 7. **EvidenceVerifierAgent** - साक्ष्य सत्यापन
- उद्धरणों और पंक्ति संदर्भों का पैटर्न-आधारित सत्यापन
- 40-100 अंक पैमाने पर साक्ष्य गुणवत्ता स्कोर करता है
- कोई LLM कॉल नहीं — रीजेक्स और टेक्स्ट मैचिंग

#### 8. **ConsolidatorAgent** - साक्ष्य समेकन
- एकाधिक स्पैन में पाई गई डुप्लिकेट तकनीकों को मर्ज करता है
- जैकार्ड समानता (>85% थ्रेशोल्ड) का उपयोग करके साक्ष्य एकत्र करता है
- समेकित कॉन्फिडेंस स्कोर के साथ अंतिम तकनीक सूची तैयार करता है

#### 9. **AttackFlowSynthesizer** - अनुक्रम निर्माण (LLM)
- अस्थायी मार्करों ("पहले", "फिर", "बाद में") का विश्लेषण करता है
- कथा से कारण संबंधों का अनुमान लगाता है
- प्रोबेबिलिस्टिक एजेज के साथ STIX Attack Flow ऑब्जेक्ट बनाता है
- जब अनुक्रम स्पष्ट नहीं होता तो सह-घटना मॉडलिंग पर वापस आ जाता है

### प्रदर्शन अनुकूलन

- **Smart Chunking**: दस्तावेज़ों को ओवरलैप के साथ 2KB चंक्स में विभाजित किया जाता है
- **Batch Processing**: मैपर प्रति LLM कॉल में 25 स्पैन तक प्रोसेस करता है
- **Parallel Processing**: चंक्स को वर्कर थ्रेड्स में समवर्ती रूप से प्रोसेस किया जाता है
- **Response Caching**: डुप्लिकेट कॉल से बचने के लिए LLM प्रतिक्रियाओं को कैश किया जाता है
- **Early Termination**: उच्च-कॉन्फिडेंस निष्कर्षण सत्यापन को छोड़ देते हैं
- **TechniqueCache**: O(1) लुकअप के लिए स्टार्टअप पर सभी ATT&CK तकनीकें लोड की जाती हैं
- **Pre-filter**: LLM मैपर से पहले प्रति उम्मीदवार तकनीक स्पैन को सीमित करता है (46% कम कॉल)
- **Batch Embedding**: तकनीक एम्बेडिंग बैचों में उत्पन्न होती हैं (2-5x तेज़)
- **Connection Pooling**: अनुरोधों में साझा Neo4j/OpenSearch कनेक्शन
- **UNWIND Batches**: Neo4j राइट्स UNWIND के माध्यम से बैच किए जाते हैं (30-40 क्वेरी → 6-7)
- **Model Pre-warming**: कोल्ड-स्टार्ट विलंब से बचने के लिए एम्बेडिंग मॉडल स्टार्टअप पर लोड किया जाता है

### प्रसंस्करण समय

| दस्तावेज़ का आकार | प्रसंस्करण समय | निकाली गई तकनीकें |
|--------------|-----------------|---------------------|
| छोटा (<5KB) | 10-20 सेकंड | 5-10 तकनीकें |
| मध्यम (5-15KB) | 20-40 सेकंड | 10-15 तकनीकें |
| बड़ा (>15KB) | 30-60 सेकंड | 15-25 तकनीकें |

## सह-घटना विश्लेषण

Bandjacks तकनीक संबंधों को समझने के लिए विश्लेषण प्रदान करता है।

> **नोट:** विश्लेषण के लिए Neo4j में `AttackEpisode` और `AttackAction` डेटा आवश्यक है। ये तब बनाए जाते हैं जब:
> - रिपोर्ट निष्कर्षण पाइपलाइन के माध्यम से संसाधित की जाती हैं
> - `/v1/flows/build` के माध्यम से Attack Flows बनाए जाते हैं
> - हमले के एपिसोड वाले STIX बंडल इनजेस्ट किए जाते हैं
>
> यदि कोई एपिसोड मौजूद नहीं है, तो विश्लेषण खाली परिणाम लौटाएंगे।

### वैश्विक सह-घटना

गणना करें कि कौन सी तकनीकें सभी हमले प्रकरणों में अक्सर एक साथ दिखाई देती हैं:```python
# Via API
response = httpx.post(
    "http://localhost:8000/v1/analytics/cooccurrence/global",
    json={"min_support": 2, "min_episodes_per_pair": 2, "limit": 50}
)

for pair in response.json()["pairs"]:
    print(f"{pair['name_a']} + {pair['name_b']}: NPMI={pair['npmi']:.3f}")

### तकनीक बंडल

बार-बार सह-घटित होने वाले तकनीक बंडलों (3-5 तकनीक) की पहचान करें:```python
response = httpx.post(
    "http://localhost:8000/v1/analytics/cooccurrence/bundles",
    json={"min_support": 3, "min_size": 3, "max_size": 5}
)

## मानव-इन-द-लूप समीक्षा प्रणाली

### एकीकृत समीक्षा इंटरफ़ेस

समीक्षा प्रणाली सभी निकाले गए आइटम को एक ही इंटरफ़ेस में प्रस्तुत करती है:```typescript
// Review workflow
1. Upload/ingest report → Extraction pipeline runs
2. Navigate to /reports/{id}/review
3. Review extracted items across three tabs:
   - Entities (threat actors, malware, tools)
   - Techniques (ATT&CK mappings with evidence)
   - Attack Flow (sequenced steps)
4. Take actions on each item:
   - Approve: Accept as correct
   - Reject: Mark as incorrect
   - Edit: Modify details (name, confidence, etc.)
5. Submit all decisions atomically

### 4. तकनीकों की खोज करना

ATT&CK तकनीकों को प्राकृतिक भाषा में खोजें:```python
# Vector search for similar techniques
response = httpx.post(
    "http://localhost:8000/v1/search/ttx",
    json={
        "query": "ransomware that encrypts files and demands payment",
        "top_k": 5
    }
)

techniques = response.json()["results"]
for tech in techniques:
    print(f"{tech['external_id']}: {tech['name']} (score: {tech['score']:.2f})")

### 6. AttackFlow मॉडल उत्पन्न करना

सह-घटना मॉडल बनाएं जो दिखाते हैं कि खतरे के अभिनेता एक साथ तकनीकों का उपयोग कैसे करते हैं:```python
# Generate flow for a specific intrusion set (e.g., APT29)
response = httpx.post(
    "http://localhost:8000/v1/flows/build",
    json={
        "intrusion_set_id": "intrusion-set--899ce53f-13a0-479b-a0e4-67d46e241542"
    }
)

flow = response.json()
print(f"Generated flow '{flow['name']}' with {len(flow['steps'])} techniques")
print(f"Co-occurrence edges: {len(flow['edges'])}")

AttackFlow मॉडल **सह-घटना** (co-occurrence) का उपयोग करते हैं, अनुक्रमिक क्रम के बजाय, क्योंकि घुसपैठ सेटों में अंतर्निहित अनुक्रम जानकारी नहीं होती है। तकनीकें निम्नलिखित द्वारा जुड़ी होती हैं:
- **अंतर-रणनीति किनारे (Intra-tactic edges)**: एक ही किल चेन रणनीति में तकनीकों के बीच
- **क्रॉस-रणनीति किनारे (Cross-tactic edges)**: आसन्न रणनीतियों के बीच तकनीकों के बीच
- **हब-स्पोक पैटर्न (Hub-spoke patterns)**: बड़े तकनीक सेटों के लिए, किनारे विस्फोट से बचने के लिए

विस्तृत उपयोग के लिए [AttackFlow जनरेशन गाइड](https://github.com/blevene/bandjacks/blob/HEAD/docs/ATTACKFLOW_GENERATION.md) देखें।

## समर्थित इनपुट प्रारूप

निष्कर्षण पाइपलाइन कई इनपुट प्रारूपों का समर्थन करती है:

- **सादा पाठ (Plain Text)** - सीधी पाठ सामग्री
- **मार्कडाउन (Markdown)** - स्वरूपित मार्कडाउन दस्तावेज़
- **PDF** - pdfplumber निष्कर्षण के माध्यम से
- **HTML** - BeautifulSoup पार्सिंग के माध्यम से
- **JSON** - संरचित डेटा निष्कर्षण

### सादा पाठ से निकालें```python
# Direct text extraction
plaintext_report = """
The threat actors used spearphishing emails with malicious attachments.
After gaining access, they deployed Mimikatz to harvest credentials and
used RDP for lateral movement across the network.
"""

result = asyncio.run(run_agentic_v2_async(plaintext_report, {
    "cache_llm_responses": True,
    "single_pass_threshold": 500
}))

### PDF से अंश```python
import pdfplumber
from bandjacks.llm.extraction_pipeline import run_extraction_pipeline

# Read PDF with pdfplumber (recommended)
with pdfplumber.open("threat_report.pdf") as pdf:
    text = ""
    for page in pdf.pages:
        page_text = page.extract_text()
        if page_text:
            text += page_text + "\n"

# Extract techniques using extraction pipeline
result = run_extraction_pipeline(text, {
    "use_optimized_extractor": True,
    "span_score_threshold": 0.7,
    "chunk_size": 2000
}, source_id="threat_report")

print(f"Found {len(result['techniques'])} techniques")

results.append({
    "file": pdf_file.name,
    "techniques": list(result["techniques"].keys()),
    "count": len(result["techniques"])
})

### हमले के प्रवाह बनाना```python
# Generate attack flow from extracted techniques
response = httpx.post(
    "http://localhost:8000/v1/flows/build",
    json={
        "source_id": "report-123",
        "technique_ids": ["T1566.001", "T1059.001", "T1003.001"]
    }
)

flow = response.json()
print(f"Generated flow with {len(flow['steps'])} steps")

## एपीआई एंडपॉइंट्स

### मुख्य एंडपॉइंट्स

- `POST /v1/stix/load/attack` - MITRE ATT&CK डेटा लोड करें
- `POST /v1/reports/ingest` - सिंक्रोनस रिपोर्ट अंतर्ग्रहण (5KB से कम)
- `POST /v1/reports/ingest_async` - एसिंक्रोनस रिपोर्ट अंतर्ग्रहण (5KB से अधिक)
- `POST /v1/reports/ingest/upload` - PDF/TXT फ़ाइलें अपलोड करें
- `GET /v1/reports/jobs/{id}/status` - जॉब की स्थिति जाँचें
- `POST /v1/reports/{id}/unified-review` - समीक्षा निर्णय सबमिट करें
- `POST /v1/search/ttx` - तकनीकों के लिए खोजें
- `GET /v1/graph/technique/{id}` - तकनीक विवरण प्राप्त करें

### हमला प्रवाह

- `POST /v1/flows/build` - AttackFlow सह-घटना मॉडल उत्पन्न करें
- `GET /v1/flows/{flow_id}` - विशिष्ट AttackFlow विवरण पुनर्प्राप्त करें
- `POST /v1/flows/search` - समान हमला प्रवाह खोजें
- `GET /v1/flows/dump` - पेजिनेशन और फ़िल्टरिंग के साथ बल्क एक्सपोर्ट प्रवाह

### विश्लेषिकी

- `GET /v1/analytics/cooccurrence/global` - वैश्विक सह-घटना मीट्रिक
- `GET /v1/analytics/cooccurrence/conditional` - सशर्त संभावनाएँ
- `GET /v1/analytics/cooccurrence/bundles` - तकनीक बंडल
- `GET /v1/analytics/cooccurrence/actor` - अभिनेता-विशिष्ट पैटर्न
- `GET /v1/coverage/gaps` - तकनीक कवरेज अंतराल

### रक्षा और पहचान

- `GET /v1/defense/technique/{id}` - रक्षात्मक सिफारिशें प्राप्त करें
- `GET /v1/detections/technique/{id}` - पहचान रणनीतियाँ
- `POST /v1/sigma/validate` - सिग्मा नियमों को मान्य करें

### निगरानी

- `GET /health` - बुनियादी स्वास्थ्य जाँच
- `GET /health/live` - Kubernetes लिवनेस प्रोब
- `GET /health/ready` - Kubernetes रेडीनेस प्रोब
- `GET /health/components/{component}` - व्यक्तिगत घटक स्वास्थ्य
- `GET /v1/costs/stats` - LLM लागत ट्रैकिंग (मॉडल द्वारा दैनिक समग्र)
- `GET /v1/cache/stats` - LLM कैश आँकड़े प्राप्त करें
- `POST /v1/cache/clear` - LLM कैश साफ़ करें
- `GET /v1/compliance/report` - अनुपालन मीट्रिक
- `GET /v1/drift/status` - ड्रिफ्ट पहचान स्थिति
- `GET /v1/ml-metrics/performance` - ML मॉडल मीट्रिक

### अभिनेता और उत्पत्ति

- `GET /v1/actors` - खतरा अभिनेताओं की सूची
- `GET /v1/actors/{id}` - अभिनेता विवरण प्राप्त करें
- `GET /v1/provenance/{object_id}` - ऑब्जेक्ट उत्पत्ति
- `GET /v1/provenance/{object_id}/lineage` - पूर्ण वंश श्रृंखला
- `GET /v1/provenance/{object_id}/evidence` - साक्ष्य स्निपेट

### केवल API सुविधाएँ (कोई UI/CLI नहीं)

ये एंडपॉइंट पूरी तरह कार्यात्मक हैं लेकिन केवल REST API के माध्यम से एक्सेस किए जाते हैं (कोई फ्रंटएंड पेज या CLI कमांड नहीं):

#### आक्रमण पथ सिमुलेशन
- `POST /v1/simulation/paths` - प्रारंभिक तकनीक/समूह से आक्रमण पथ अनुकरण करें
- `POST /v1/simulation/predict` - वर्तमान स्थिति के आधार पर अगले संभावित तकनीकों की भविष्यवाणी करें
- `POST /v1/simulation/whatif` - रक्षात्मक परिदृश्यों के लिए क्या-अगर विश्लेषण
- `POST /v1/simulation/scenario` - समूहों/सॉफ्टवेयर/तकनीकों के सेट से अनुकरण करें
- `GET /v1/simulation/statistics/{technique_id}` - तकनीक उपयोग सांख्यिकी
- `GET /v1/simulation/groups/{group_id}/patterns` - समूह आक्रमण पैटर्न
- `POST /v1/simulation/compare` - कई आक्रमण पथों की तुलना करें

#### MDP नीति और रोलआउट
- `POST /v1/simulate/rollout` - PTG रोलआउट अनुकरण
- `POST /v1/simulate/mdp` - MDP इष्टतम रक्षा नीति की गणना करें
- `GET /v1/simulate/models` - उपलब्ध PTG मॉडलों की सूची

#### ड्रिफ्ट पहचान और निगरानी
- `GET /v1/drift/status` - सभी मीट्रिक पर वर्तमान ड्रिफ्ट स्थिति
- `POST /v1/drift/analyze` - कस्टम सीमा के साथ ड्रिफ्ट विश्लेषण चलाएँ
- `GET /v1/drift/alerts` - सक्रिय ड्रिफ्ट अलर्ट प्राप्त करें
- `POST /v1/drift/alerts/{alert_id}/acknowledge` - अलर्ट स्वीकार करें
- `GET /v1/drift/metrics/{metric_name}` - विशिष्ट ड्रिफ्ट मीट्रिक प्राप्त करें

#### ML मीट्रिक ट्रैकिंग
- `POST /v1/ml-metrics/prediction` - ट्रैकिंग के लिए मॉडल भविष्यवाणी रिकॉर्ड करें
- `POST /v1/ml-metrics/review` - समीक्षा निर्णय मीट्रिक रिकॉर्ड करें
- `POST /v1/ml-metrics/coverage-gap` - कवरेज अंतराल रिकॉर्ड करें
- `GET /v1/ml-metrics/performance` - मॉडल प्रदर्शन मीट्रिक प्राप्त करें
- `GET /v1/ml-metrics/dashboard` - डैशबोर्ड मीट्रिक निर्यात करें

#### सूचनाएँ
- `GET /v1/notifications/history` - सूचना इतिहास प्राप्त करें
- `POST /v1/notifications/clear-history` - सूचना इतिहास साफ़ करें
- `GET /v1/notifications/config` - सूचना कॉन्फ़िगरेशन प्राप्त करें
- `POST /v1/notifications/test` - परीक्षण सूचना भेजें

#### वेक्टर अपडेट प्रबंधन
- `GET /v1/vectors/status` - वेक्टर अपडेट सिस्टम स्थिति
- `GET /v1/vectors/metrics` - विस्तृत वेक्टर अपडेट मीट्रिक
- `POST /v1/vectors/update` - मैन्युअल रूप से वेक्टर अपडेट ट्रिगर करें
- `POST /v1/vectors/process-batch` - बैच प्रसंस्करण बलपूर्वक करें
- `DELETE /v1/vectors/queue` - लंबित अपडेट कतार साफ़ करें
- `GET /v1/vectors/health` - वेक्टर सिस्टम स्वास्थ्य जाँच

#### एंटिटी इग्नोरलिस्ट
- `GET /v1/ignorelist` - वर्तमान इग्नोरलिस्ट स्थिति प्राप्त करें
- `POST /v1/ignorelist/add` - इग्नोरलिस्ट में एंटिटी जोड़ें
- `DELETE /v1/ignorelist/remove` - इग्नोरलिस्ट से एंटिटी हटाएँ
- `POST /v1/ignorelist/reload` - डिस्क से इग्नोरलिस्ट पुनः लोड करें

#### उम्मीदवार पैटर्न समीक्षा
- `GET /v1/review/candidates` - उम्मीदवार आक्रमण पैटर्न की सूची
- `POST /v1/review/candidates` - उम्मीदवार पैटर्न बनाएँ
- `GET /v1/review/candidates/{id}` - उम्मीदवार विवरण प्राप्त करें
- `POST /v1/review/candidates/{id}/approve` - उम्मीदवार स्वीकृत करें
- `POST /v1/review/candidates/{id}/reject` - उम्मीदवार अस्वीकार करें
- `GET /v1/review/candidates/{id}/similar` - समान पैटर्न खोजें
- `GET /v1/review/candidates/stats/summary` - उम्मीदवार सांख्यिकी

### पूर्ण API दस्तावेज़ीकरण

पूर्ण API दस्तावेज़ीकरण यहाँ उपलब्ध है:
- Swagger UI: http://localhost:8000/docs
- ReDoc: http://localhost:8000/redoc
- OpenAPI JSON: http://localhost:8000/openapi.json

## आर्किटेक्चर

### प्रोजेक्ट संरचना```
bandjacks/
├── bandjacks/
│   ├── analysis/         # Graph analysis & interdiction
│   │   ├── graph_analyzer.py
│   │   └── interdiction.py
│   ├── analytics/        # Co-occurrence & clustering
│   │   ├── clustering.py
│   │   ├── cooccurrence.py
│   │   └── detection_bundles.py
│   ├── cli/              # Command-line interface
│   │   ├── main.py       # CLI entry point
│   │   ├── batch_extract.py
│   │   ├── formatters.py
│   │   └── workflows.py
│   ├── config/           # Configuration files
│   │   └── entity_ignorelist.yaml
│   ├── core/             # Core utilities
│   │   ├── cache.py      # Redis caching
│   │   ├── connection_pool.py
│   │   └── query_optimizer.py
│   ├── llm/              # Extraction pipeline
│   │   ├── extraction_pipeline.py
│   │   ├── agents_v2.py  # Core extraction agents
│   │   ├── chunked_extractor.py
│   │   ├── optimized_chunked_extractor.py
│   │   ├── entity_extractor.py
│   │   ├── flow_builder.py
│   │   ├── cache.py      # LLM response caching
│   │   └── experimental/ # Experimental features
│   ├── loaders/          # Data loading & indexing
│   │   ├── attack_catalog.py
│   │   ├── attack_upsert.py
│   │   ├── opensearch_index.py
│   │   ├── hybrid_search.py
│   │   └── sigma_loader.py
│   ├── monitoring/       # Metrics & monitoring
│   │   ├── compliance_metrics.py
│   │   ├── defense_metrics.py
│   │   ├── drift_detector.py
│   │   └── ml_metrics.py
│   ├── services/         # API & services
│   │   ├── api/          # FastAPI application
│   │   │   ├── main.py
│   │   │   ├── routes/   # API route handlers
│   │   │   └── middleware/
│   │   ├── technique_cache.py
│   │   └── actor_cache.py
│   ├── simulation/       # Attack simulation
│   │   ├── attack_simulator.py
│   │   ├── mdp_solver.py
│   │   └── ptg_rollout.py
│   └── store/            # Data stores
│       ├── report_store.py
│       ├── candidate_store.py
│       └── review_store.py
├── ui/                   # Next.js frontend
│   ├── app/              # App Router pages
│   │   ├── reports/      # Report management
│   │   ├── analytics/    # Analytics dashboards
│   │   └── health/       # Health monitoring
│   ├── components/       # React components
│   └── hooks/            # Custom React hooks
├── tests/                # Test suite
├── samples/              # Sample reports
├── scripts/              # Utility scripts
└── docs/                 # Documentation

**Provider priority:** Local API > Gemini > OpenAI > LiteLLM proxy.
जब एक स्थानीय सर्वर कॉन्फ़िगर किया जाता है, तो क्लाउड प्रदाता स्वचालित रूप से फ़ॉलबैक के रूप में जोड़े जाते हैं।

#### सामान्य स्थानीय सर्वर उदाहरण

| सर्वर | `LOCAL_LLM_API_BASE` | `LOCAL_LLM_MODEL` |
|--------|---------------------|-------------------|
| vLLM | `http://host:8000/v1` | `mistralai/Mistral-Nemo-Instruct-2407` |
| llama.cpp | `http://host:8080/v1` | `mistral-nemo` |
| Ollama | `http://host:11434/v1` | `mistral-nemo` |
| LM Studio | `http://host:1234/v1` | `mistral-nemo` |
| LocalAI | `http://host:8080/v1` | `mistral-nemo` |

### निष्कर्षण कॉन्फ़िगरेशन

सिस्टम एक एकल उच्च-प्रदर्शन एसिंक पाइपलाइन का उपयोग करता है जिसमें कॉन्फ़िगरेबल विकल्प होते हैं:```python
{
    "cache_llm_responses": True,         # Enable LLM caching (default: True)
    "single_pass_threshold": 500,        # Max words for single-pass (default: 500)
    "early_termination_confidence": 90,  # Skip verification above this (default: 90)
    "disable_discovery": False,          # Disable LLM discovery agent
    "max_spans": 20,                     # Maximum spans to process
    "span_score_threshold": 0.7,         # Minimum span quality
    "top_k": 5,                          # Candidates per span

    # Cost optimization options
    "max_spans_per_technique": 2,        # Pre-filter: max spans per candidate technique (0=disable, default=2)
    "enable_span_dedup": False,          # Text-based span dedup before mapping (default=False)
}

### विश्वास सीमाएँ

निष्कर्षण गुणवत्ता नियंत्रित करें:```python
{
    "confidence_threshold": 50.0,  # Minimum confidence (0-100)
    "auto_ingest": True            # Auto-add high-confidence results
}

### स्वास्थ्य प्रतिक्रिया उदाहरण```json
{
  "status": "healthy",
  "timestamp": "2025-01-28T17:43:30.184036Z",
  "version": "1.0.0",
  "components": {
    "neo4j": {
      "status": "healthy",
      "latency_ms": 5
    },
    "opensearch": {
      "status": "degraded",
      "cluster_status": "yellow",
      "indices": {
        "attack_nodes": false,
        "bandjacks_reports": true
      }
    },
    "redis": {
      "status": "healthy",
      "latency_ms": 2,
      "memory_mb": 1.69
    },
    "caches": {
      "status": "healthy",
      "technique_cache": {
        "count": 993,
        "loaded": true
      },
      "actor_cache": {
        "count": 145,
        "loaded": true
      }
    },
    "system": {
      "status": "healthy",
      "memory": {
        "available_gb": 8.84,
        "percent_used": 72.4
      },
      "disk": {
        "available_gb": 353.11,
        "percent_used": 2.9
      },
      "cpu": {
        "percent_used": 7.7
      }
    }
  }
}

## प्रदर्शन अनुकूलन

### कैशिंग

सिस्टम में बेहतर प्रदर्शन के लिए स्वचालित LLM प्रतिक्रिया कैशिंग शामिल है:```python
# Check cache statistics
response = httpx.get("http://localhost:8000/v1/cache/stats")
stats = response.json()
print(f"Cache hit rate: {stats['hit_rate']}")

# Clear cache if needed
httpx.post("http://localhost:8000/v1/cache/clear")

## सुरक्षा

### इनपुट सत्यापन

- **Cypher इंजेक्शन रोकथाम**: सभी ग्राफ क्वेरी एंडपॉइंट उपयोगकर्ता-प्रदत्त `relationship_types` पैरामीटर्स को ज्ञात संबंध प्रकारों (USES, MITIGATES, HAS_TACTIC, आदि) की अनुमत सूची और एक सख्त regex पैटर्न (`^[A-Z][A-Z0-9_]*$`) के विरुद्ध मान्य करते हैं। अमान्य इनपुट क्वेरी निर्माण से पहले 400 लौटाता है।
- **JSON स्कीमा सत्यापन**: पाइपलाइन में दूषित डेटा प्रवेश को रोकने के लिए LLM प्रतिक्रियाओं को JSON स्कीमाओं के विरुद्ध मान्य किया जाता है।
- **ADM सत्यापन**: सभी STIX सामग्री को अंतर्ग्रहण से पहले ATT&CK डेटा मॉडल सत्यापन पास करना होगा।

### प्रमाणीकरण और प्राधिकरण

- **JWT प्रमाणीकरण**: API प्रमाणीकरण के लिए वैकल्पिक मिडलवेयर (`JWTAuthMiddleware`)
- **दर सीमा**: कॉन्फ़िगरेबल थ्रेशोल्ड के साथ प्रति-एंडपॉइंट दर सीमित करना
- **CORS**: कॉन्फ़िगरेबल क्रॉस-ओरिजिन संसाधन साझाकरण

## उन्नत सुविधाएँ

### उत्पत्ति ट्रैकिंग

प्रत्येक निकाली गई इकाई में पूर्ण उत्पत्ति शामिल है:```python
# Get provenance for an object
response = httpx.get(
    "http://localhost:8000/v1/provenance/attack-pattern--abc123"
)

### कवरेज विश्लेषण

अपने खतरे की खुफिया कवरेज का विश्लेषण करें:```python
# Get coverage analysis
response = httpx.get("http://localhost:8000/v1/analytics/coverage")
coverage = response.json()

print(f"Summary: {coverage['summary']}")
for tactic in coverage['tactics']:
    print(f"  {tactic['tactic']}: {tactic['coverage_percentage']}%")

## फ़ीचर स्थिति

यह अनुभाग विभिन्न सुविधाओं की कार्यान्वयन स्थिति के बारे में पारदर्शिता प्रदान करता है:

### पूरी तरह से कार्यात्मक ✅
- **रिपोर्ट निकालने की पाइपलाइन** - LLM-आधारित तकनीक निष्कर्षण अंत-से-अंत तक काम करता है
- **MITRE ATT&CK लोडिंग** - उद्यम/मोबाइल/ICS ATT&CK डेटा को Neo4j में लोड करें
- **वेक्टर खोज** - तकनीकों के लिए OpenSearch-आधारित सिमैंटिक खोज
- **समीक्षा प्रणाली** - API और UI के माध्यम से मानव-इन-द-लूप समीक्षा कार्यप्रवाह
- **स्वास्थ्य निगरानी** - घटक स्वास्थ्य जाँच और Kubernetes प्रोब
- **CLI क्वेरी/प्रशासन कमांड** - खोज, ग्राफ़ ट्रैवर्सल, कैश प्रबंधन
- **हमला प्रवाह निर्माण** - सह-घटना-आधारित प्रवाह निर्माण घुसपैठ सेटों के लिए
- **हमला सिमुलेशन** - MDP-आधारित पथ सिमुलेशन `/simulation/*` और `/simulate/*` के माध्यम से
- **कवरेज रिपोर्ट** - कार्यकारी, तकनीकी, सामरिक, परिचालन दृश्यों के लिए JSON रिपोर्ट

### डेटा निर्भरताओं के साथ कार्यात्मक ⚠️
- **सह-घटना विश्लेषण** - रिपोर्ट प्रसंस्करण से `AttackEpisode` नोड्स की आवश्यकता है
- **अभिकर्ता विश्लेषण** - घुसपैठ सेटों से संबंधित एपिसोड की आवश्यकता है
- **तकनीक बंडल** - पैटर्न खनन के लिए पर्याप्त एपिसोड डेटा की आवश्यकता है
- **CLI एनालिटिक्स कमांड** - काम करते हैं लेकिन यदि कोई एपिसोड मौजूद नहीं है तो खाली लौटते हैं

### केवल API (कोई UI/CLI नहीं) 🔌
ये पूरी तरह से लागू की गई सुविधाएँ हैं जो केवल REST API के माध्यम से पहुँच योग्य हैं:
- **हमला पथ सिमुलेशन** - `/simulation/*` मार्ग पथ भविष्यवाणी और क्या-होगा-अगर विश्लेषण के लिए
- **MDP नीति हल करने वाला** - `/simulate/mdp` इष्टतम रक्षा नीति गणना के लिए
- **ड्रिफ्ट पहचान** - `/drift/*` मार्ग डेटा गुणवत्ता ड्रिफ्ट की निगरानी के लिए
- **ML मेट्रिक्स** - `/ml-metrics/*` समय के साथ मॉडल प्रदर्शन को ट्रैक करने के लिए
- **वेक्टर प्रबंधन** - `/vectors/*` वेक्टर एम्बेडिंग के प्रबंधन के लिए
- **एंटिटी इग्नोरलिस्ट** - `/ignorelist/*` गलत सकारात्मक एंटिटी को फ़िल्टर करने के लिए
- **उम्मीदवार पैटर्न** - `/review/candidates/*` नवीन तकनीक उम्मीदवारों के लिए
- **अधिसूचनाएँ** - `/notifications/*` अलर्ट कॉन्फ़िगरेशन और इतिहास के लिए
- **उत्पत्ति** - `/provenance/*` निष्कर्षण वंशावली ट्रैकिंग के लिए
- **अनुपालन** - `/compliance/*` अनुपालन मेट्रिक्स रिपोर्टिंग के लिए

### प्रायोगिक (`llm/experimental/` में) 🧪
- **PTG (प्रायिक खतरा ग्राफ)** - मुख्य तर्क लागू, सीमित परीक्षण
- **जज एकीकरण** - LLM-आधारित अनुक्रम सत्यापन
- **हमला प्रवाह सिम्युलेटर** - प्रवाह-आधारित सिमुलेशन इंजन
- **अनुक्रम निकालने वाला** - प्रवाहों से अनुक्रम निकालें

### हटाया गया/साफ किया गया 🗑️
निम्नलिखित स्टब सुविधाओं को API से हटा दिया गया है:
- ~~प्लेटफ़ॉर्म कवरेज विश्लेषण~~ - हार्डकोडेड स्टब डेटा लौटा रहा था
- ~~प्रवृत्ति विश्लेषण~~ - यादृच्छिक सिंथेटिक डेटा लौटा रहा था
- ~~CSV/PDF रिपोर्ट निर्यात~~ - 501 लौटा रहा था; अब केवल JSON
- ~~Gemini अनुक्रम अनुमान~~ - 501 स्टब था; इसके बजाय `/sequence/propose` का उपयोग करें

### कनेक्टिविटी मैट्रिक्स

| फ़ीचर क्षेत्र | फ्रंटेंड UI | CLI | REST API |
|--------------|-------------|-----|----------|
| रिपोर्ट प्रबंधन | ✅ | ✅ | ✅ |
| समीक्षा कार्यप्रवाह | ✅ | ✅ | ✅ |
| खोज (TTX) | ✅ | ✅ | ✅ |
| सह-घटना विश्लेषण | ✅ | ✅ | ✅ |
| कवरेज विश्लेषण | ✅ | - | ✅ |
| स्वास्थ्य निगरानी | ✅ | - | ✅ |
| डिटेक्शन/सिग्मा | ✅ | - | ✅ |
| हमला प्रवाह | ✅ | - | ✅ |
| रक्षा ओवरले | ✅ | - | ✅ |
| अनुक्रम/PTG | ✅ | - | ✅ |
| अभिकर्ता | ✅ | - | ✅ |
| हमला सिमुलेशन | - | - | ✅ |
| ड्रिफ्ट पहचान | - | - | ✅ |
| ML मेट्रिक्स | - | - | ✅ |
| वेक्टर प्रबंधन | - | - | ✅ |
| एंटिटी इग्नोरलिस्ट | - | - | ✅ |
| उम्मीदवार पैटर्न | - | - | ✅ |
| अधिसूचनाएँ | - | - | ✅ |
| उत्पत्ति | - | - | ✅ |
| अनुपालन | - | - | ✅ |

### फ्रंटेंड पृष्ठ
| पृष्ठ | स्थिति | नोट्स |
|------|--------|-------|
| `/reports` | ✅ काम कर रहा है | रिपोर्ट सूची, बनाना, देखना |
| `/reports/[id]/review` | ✅ काम कर रहा है | पूर्ण समीक्षा कार्यप्रवाह |
| `/analytics/cooccurrence` | ⚠️ डेटा-निर्भर | यदि एपिसोड मौजूद हैं तो KPI दिखाता है |
| `/analytics/cooccurrence/pairs` | ⚠️ डेटा-निर्भर | वास्तविक API को कॉल करता है |
| `/analytics/cooccurrence/bundles` | ⚠️ डेटा-निर्भर | वास्तविक API को कॉल करता है |
| `/analytics/cooccurrence/actors` | ⚠️ डेटा-निर्भर | वास्तविक API को कॉल करता है |
| `/health` | ✅ काम कर रहा है | रीयल-टाइम स्वास्थ्य स्थिति |

## समस्या निवारण

### सामान्य समस्याएँ

1. **OpenSearch कनेक्शन विफल**
   - सुनिश्चित करें कि OpenSearch चल रहा है: `curl http://localhost:9200`
   - जाँचें कि इंडेक्स मौजूद है: `curl http://localhost:9200/bandjacks_attack_nodes-v1`

2. **Neo4j कनेक्शन विफल**
   - सत्यापित करें कि Neo4j चल रहा है: `neo4j status`
   - जाँचें कि `.env` फ़ाइल में `NEO4J_PASSWORD` सेट है
   - सुनिश्चित करें कि पासवर्ड आपके Neo4j इंस्टेंस से मेल खाता है
   - यदि आप देखते हैं "NEO4J_PASSWORD environment variable is required", तो आपको इसे अपनी `.env` फ़ाइल में सेट करना होगा

3. **कम निष्कर्षण रिकॉल**
   - सुनिश्चित करें कि आप `agentic_v2` विधि का उपयोग कर रहे हैं
   - जाँचें कि LLM API कुंजी मान्य है
   - सत्यापित करें कि मॉडल नाम सही है (gemini-flash-latest)

4. **टाइमआउट त्रुटियाँ**
   - बड़े दस्तावेज़ों के लिए टाइमआउट सेटिंग्स बढ़ाएँ
   - बहुत बड़ी रिपोर्टों को चंक करने पर विचार करें

5. **फ्रंटेंड API से कनेक्ट नहीं हो रहा**
   - सुनिश्चित करें कि API पोर्ट 8000 पर चल रहा है
   - API कॉन्फ़िगरेशन में CORS सेटिंग्स जाँचें

### डीबग मोड

विस्तृत लॉगिंग सक्षम करें:```python
import logging
logging.basicConfig(level=logging.DEBUG)

# Run extraction with debug output
result = run_agentic_v2(text, config)

### योगदान

1. रिपॉजिटरी को फोर्क करें
2. एक फीचर ब्रांच बनाएं
3. अपने बदलाव करें
4. परीक्षण चलाएँ: `uv run pytest`
5. लिंटिंग चलाएँ: `uv run ruff check`
6. पुल अनुरोध सबमिट करें

### कोड गुणवत्ता```bash
# Format code
uv run ruff format

# Check linting
uv run ruff check

# Type checking
uv run mypy bandjacks