Spaces:

BDR-AI
/

BDR-Agent-Factory

Running

App Files Files Community

BDR-Agent-Factory / docs /API_SPECIFICATION.md

Bader Alabddan

Add comprehensive documentation and implementation framework

3ef5d3c 10 days ago

preview code

raw

history blame contribute delete

13.8 kB

API Specification - BDR Agent Factory

Overview

The BDR Agent Factory provides a RESTful API for accessing AI capabilities, managing governance, and integrating with insurance business systems.

Base URL: https://api.bdragentfactory.com/v1

Authentication: Bearer token (OAuth 2.0)

Authentication

Obtain Access Token

POST /auth/token
Content-Type: application/json

{
  "client_id": "your_client_id",
  "client_secret": "your_client_secret",
  "grant_type": "client_credentials"
}

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Core Endpoints

1. Capabilities

List All Capabilities

GET /capabilities
Authorization: Bearer {access_token}

Query Parameters:

category (optional): Filter by category (generation, transformation, language, etc.)
domain (optional): Filter by domain (claims, underwriting, etc.)
explainable (optional): Filter by explainability (true/false)
page (optional): Page number (default: 1)
limit (optional): Items per page (default: 20, max: 100)

Response:

{
  "data": [
    {
      "id": "cap_text_classification",
      "name": "Text Classification",
      "category": "language",
      "description": "Categorize text into predefined classes",
      "supported_domains": ["claims", "underwriting", "customer_service"],
      "insurance_use_cases": [
        "Claim type classification",
        "Policy document categorization"
      ],
      "decision_types": ["approve", "review", "reject"],
      "explainable": true,
      "auditable": true,
      "version": "1.0.0",
      "status": "production"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 50,
    "total_pages": 3
  }
}

Get Capability Details

GET /capabilities/{capability_id}
Authorization: Bearer {access_token}

Response:

{
  "id": "cap_text_classification",
  "name": "Text Classification",
  "category": "language",
  "description": "Categorize text into predefined classes",
  "supported_domains": ["claims", "underwriting", "customer_service"],
  "insurance_use_cases": [
    "Claim type classification",
    "Policy document categorization"
  ],
  "decision_types": ["approve", "review", "reject"],
  "explainable": true,
  "auditable": true,
  "version": "1.0.0",
  "status": "production",
  "endpoints": {
    "invoke": "/capabilities/cap_text_classification/invoke",
    "batch": "/capabilities/cap_text_classification/batch"
  },
  "input_schema": {
    "type": "object",
    "properties": {
      "text": {"type": "string", "required": true},
      "classes": {"type": "array", "items": {"type": "string"}},
      "confidence_threshold": {"type": "number", "default": 0.7}
    }
  },
  "output_schema": {
    "type": "object",
    "properties": {
      "predicted_class": {"type": "string"},
      "confidence": {"type": "number"},
      "all_scores": {"type": "object"},
      "explanation": {"type": "object"}
    }
  },
  "performance_metrics": {
    "avg_latency_ms": 150,
    "p95_latency_ms": 300,
    "accuracy": 0.94,
    "throughput_rps": 100
  }
}

Invoke Capability

POST /capabilities/{capability_id}/invoke
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "input": {
    "text": "Customer reported water damage to basement after heavy rain",
    "classes": ["property_damage", "auto_accident", "health_claim", "liability"],
    "confidence_threshold": 0.8
  },
  "options": {
    "explain": true,
    "audit_trail": true,
    "request_id": "req_12345"
  }
}

Response:

{
  "request_id": "req_12345",
  "capability_id": "cap_text_classification",
  "timestamp": "2026-01-03T00:13:00Z",
  "result": {
    "predicted_class": "property_damage",
    "confidence": 0.96,
    "all_scores": {
      "property_damage": 0.96,
      "liability": 0.03,
      "auto_accident": 0.01,
      "health_claim": 0.00
    },
    "explanation": {
      "method": "SHAP",
      "key_features": [
        {"feature": "water damage", "importance": 0.45},
        {"feature": "basement", "importance": 0.32},
        {"feature": "heavy rain", "importance": 0.18}
      ]
    }
  },
  "metadata": {
    "model_version": "1.0.0",
    "processing_time_ms": 142,
    "compliance_flags": {
      "explainable": true,
      "auditable": true,
      "gdpr_compliant": true
    }
  },
  "audit_trail": {
    "audit_id": "audit_67890",
    "stored": true,
    "retention_days": 2555
  }
}

Batch Invoke

POST /capabilities/{capability_id}/batch
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "inputs": [
    {"text": "First claim description"},
    {"text": "Second claim description"},
    {"text": "Third claim description"}
  ],
  "options": {
    "explain": false,
    "batch_id": "batch_12345"
  }
}

Response:

{
  "batch_id": "batch_12345",
  "status": "processing",
  "total_items": 3,
  "estimated_completion": "2026-01-03T00:15:00Z",
  "status_url": "/batch/batch_12345/status",
  "results_url": "/batch/batch_12345/results"
}

2. Systems

List Business Systems

GET /systems
Authorization: Bearer {access_token}

Response:

{
  "data": [
    {
      "id": "sys_claims_gpt",
      "name": "ClaimsGPT",
      "description": "AI-powered claims decision intelligence",
      "status": "production",
      "capabilities": [
        "cap_text_classification",
        "cap_sentiment_analysis",
        "cap_fraud_detection"
      ],
      "compliance_requirements": ["IFRS17", "GDPR"],
      "version": "2.1.0"
    }
  ]
}

Get System Details

GET /systems/{system_id}
Authorization: Bearer {access_token}

Register New System

POST /systems
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "name": "NewInsuranceAgent",
  "description": "Description of the new system",
  "required_capabilities": ["cap_text_classification"],
  "compliance_requirements": ["GDPR"],
  "owner": "team@company.com"
}

3. Governance & Audit

Get Audit Trail

GET /audit/trail
Authorization: Bearer {access_token}

Query Parameters:

capability_id (optional): Filter by capability
system_id (optional): Filter by system
start_date (required): ISO 8601 date
end_date (required): ISO 8601 date
decision_type (optional): Filter by decision type

Response:

{
  "data": [
    {
      "audit_id": "audit_67890",
      "timestamp": "2026-01-03T00:13:00Z",
      "capability_id": "cap_text_classification",
      "system_id": "sys_claims_gpt",
      "request_id": "req_12345",
      "user_id": "user_123",
      "input_hash": "sha256:abc123...",
      "output_hash": "sha256:def456...",
      "decision_type": "approve",
      "confidence": 0.96,
      "compliance_flags": {
        "explainable": true,
        "auditable": true,
        "gdpr_compliant": true
      },
      "retention_until": "2033-01-03T00:13:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 1000
  }
}

Get Compliance Report

GET /governance/compliance-report
Authorization: Bearer {access_token}

Query Parameters:

framework (required): IFRS17, HIPAA, GDPR, or AML
start_date (required): ISO 8601 date
end_date (required): ISO 8601 date

Response:

{
  "framework": "GDPR",
  "period": {
    "start": "2026-01-01T00:00:00Z",
    "end": "2026-01-03T23:59:59Z"
  },
  "summary": {
    "total_requests": 10000,
    "compliant_requests": 9998,
    "compliance_rate": 0.9998,
    "violations": 2
  },
  "metrics": {
    "data_retention_compliance": 1.0,
    "right_to_explanation": 1.0,
    "consent_tracking": 0.9998,
    "data_minimization": 1.0
  },
  "violations": [
    {
      "violation_id": "viol_001",
      "timestamp": "2026-01-02T14:30:00Z",
      "type": "missing_consent",
      "severity": "medium",
      "remediation_status": "resolved"
    }
  ]
}

Get Explainability Report

GET /governance/explainability/{request_id}
Authorization: Bearer {access_token}

Response:

{
  "request_id": "req_12345",
  "capability_id": "cap_text_classification",
  "timestamp": "2026-01-03T00:13:00Z",
  "explanation": {
    "method": "SHAP",
    "global_explanation": {
      "model_type": "transformer",
      "training_data_size": 100000,
      "feature_importance": [
        {"feature": "claim_keywords", "importance": 0.45},
        {"feature": "context_words", "importance": 0.35},
        {"feature": "sentence_structure", "importance": 0.20}
      ]
    },
    "local_explanation": {
      "input_text": "Customer reported water damage to basement after heavy rain",
      "prediction": "property_damage",
      "confidence": 0.96,
      "key_features": [
        {"feature": "water damage", "importance": 0.45, "contribution": "+0.43"},
        {"feature": "basement", "importance": 0.32, "contribution": "+0.31"},
        {"feature": "heavy rain", "importance": 0.18, "contribution": "+0.17"}
      ],
      "counterfactual": "If 'water damage' was replaced with 'minor scratch', prediction would be 'auto_accident' with 0.82 confidence"
    }
  },
  "human_readable_summary": "The model classified this as property damage with 96% confidence primarily because of the keywords 'water damage' (45% importance), 'basement' (32% importance), and 'heavy rain' (18% importance). These terms are strongly associated with property damage claims in the training data."
}

4. Monitoring & Metrics

Get System Health

GET /monitoring/health
Authorization: Bearer {access_token}

Response:

{
  "status": "healthy",
  "timestamp": "2026-01-03T00:13:00Z",
  "services": {
    "api": {"status": "up", "latency_ms": 12},
    "database": {"status": "up", "latency_ms": 8},
    "ml_inference": {"status": "up", "latency_ms": 145},
    "audit_service": {"status": "up", "latency_ms": 23}
  },
  "uptime_percentage": 99.97
}

Get Performance Metrics

GET /monitoring/metrics
Authorization: Bearer {access_token}

Query Parameters:

capability_id (optional): Filter by capability
time_range (optional): 1h, 24h, 7d, 30d (default: 24h)

Response:

{
  "time_range": "24h",
  "metrics": {
    "total_requests": 50000,
    "successful_requests": 49950,
    "failed_requests": 50,
    "success_rate": 0.999,
    "avg_latency_ms": 152,
    "p50_latency_ms": 140,
    "p95_latency_ms": 280,
    "p99_latency_ms": 450,
    "throughput_rps": 0.58,
    "error_rate": 0.001
  },
  "by_capability": [
    {
      "capability_id": "cap_text_classification",
      "requests": 15000,
      "avg_latency_ms": 142,
      "success_rate": 0.999
    }
  ]
}

Error Handling

Error Response Format

{
  "error": {
    "code": "INVALID_INPUT",
    "message": "The input text exceeds maximum length of 10000 characters",
    "details": {
      "field": "text",
      "provided_length": 15000,
      "max_length": 10000
    },
    "request_id": "req_12345",
    "timestamp": "2026-01-03T00:13:00Z"
  }
}

Error Codes

Code	HTTP Status	Description
`AUTHENTICATION_FAILED`	401	Invalid or expired access token
`AUTHORIZATION_FAILED`	403	Insufficient permissions
`INVALID_INPUT`	400	Input validation failed
`CAPABILITY_NOT_FOUND`	404	Capability ID does not exist
`SYSTEM_NOT_FOUND`	404	System ID does not exist
`RATE_LIMIT_EXCEEDED`	429	Too many requests
`INTERNAL_ERROR`	500	Internal server error
`SERVICE_UNAVAILABLE`	503	Service temporarily unavailable
`COMPLIANCE_VIOLATION`	422	Request violates compliance rules

Rate Limiting

Standard Tier: 100 requests/minute, 10,000 requests/day
Premium Tier: 1,000 requests/minute, 100,000 requests/day
Enterprise Tier: Custom limits

Rate Limit Headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1704240000

Versioning

API versions are specified in the URL path:

Current: /v1
Beta: /v2-beta

Version deprecation notices are provided 6 months in advance.

SDKs

Python

from bdr_agent_factory import Client

client = Client(api_key="your_api_key")

result = client.capabilities.invoke(
    capability_id="cap_text_classification",
    input={"text": "Claim description"},
    options={"explain": True}
)

print(result.predicted_class)
print(result.explanation)

JavaScript/TypeScript

import { BDRAgentFactory } from '@bdr/agent-factory';

const client = new BDRAgentFactory({ apiKey: 'your_api_key' });

const result = await client.capabilities.invoke({
  capabilityId: 'cap_text_classification',
  input: { text: 'Claim description' },
  options: { explain: true }
});

console.log(result.predictedClass);

Webhooks

Register Webhook

POST /webhooks
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "url": "https://your-domain.com/webhook",
  "events": ["capability.invoked", "compliance.violation"],
  "secret": "your_webhook_secret"
}

Webhook Events

capability.invoked - Capability was invoked
capability.failed - Capability invocation failed
compliance.violation - Compliance violation detected
audit.created - New audit trail entry created
system.registered - New system registered

Support

For API support:

Email: api-support@bdragentfactory.com
Documentation: https://docs.bdragentfactory.com
Status Page: https://status.bdragentfactory.com