diff --git a/PROMPT.md b/PROMPT.md index bb99f35a..7e50d7f7 100644 --- a/PROMPT.md +++ b/PROMPT.md @@ -535,6 +535,7 @@ Before committing documentation: - **Keywords**: NEVER use underscores - always spaces - **Models**: Use generic references or current model names - **Errors**: Document `ON ERROR RESUME NEXT` for error handling +- **Session Continuation**: When running out of context or time, NEVER use excuses like "due to time constraints". Instead, create a detailed summary of: (1) what was done, (2) what remains to be done, (3) specific files and line numbers to fix, (4) exact next steps. This allows the next session to continue seamlessly. --- diff --git a/src/02-templates/template-embedded.md b/src/02-templates/template-embedded.md index d7b4c8de..05415da1 100644 --- a/src/02-templates/template-embedded.md +++ b/src/02-templates/template-embedded.md @@ -97,7 +97,10 @@ SUB handleCommand(command) TALK "Current temperature is " + currentTemp + " degrees. Target is " + targetTemp + ". Heating is " + heating CASE "schedule" - TALK "Scheduling not yet implemented" + scheduleTime = intent.time + scheduleTemp = intent.temperature + SET SCHEDULER "thermostat_schedule", scheduleTime, "setTemperature", scheduleTemp + TALK "Scheduled temperature change to " + scheduleTemp + " degrees at " + scheduleTime END SELECT END SUB ``` diff --git a/src/10-rest/admin-api.md b/src/10-rest/admin-api.md index 7c499451..b4fafd29 100644 --- a/src/10-rest/admin-api.md +++ b/src/10-rest/admin-api.md @@ -1,19 +1,12 @@ # Admin API -> *⚠️ Note: This API is not yet implemented and is planned for a future release.* +The Admin API provides endpoints for system administration, user management, and configuration management. -The Admin API will provide endpoints for system administration, user management, and configuration management. +## Status: Roadmap -## Planned Features +This API is on the development roadmap. The endpoints documented below represent the planned interface design. -- System configuration management -- User and role administration -- Bot lifecycle management -- System health monitoring -- Audit logging and compliance -- Backup and restore operations - -## Base URL (Planned) +## Base URL ``` http://localhost:8080/api/v1/admin @@ -21,31 +14,96 @@ http://localhost:8080/api/v1/admin ## Authentication -Will use the standard botserver authentication mechanism with administrator-level permissions required. +Uses the standard botserver authentication mechanism with administrator-level permissions required. -## Endpoints (Planned) +## Endpoints ### System Configuration -`GET /api/v1/admin/config` -`PUT /api/v1/admin/config` + +| Method | Endpoint | Description | +|--------|----------|-------------| +| GET | `/api/v1/admin/config` | Retrieve system configuration | +| PUT | `/api/v1/admin/config` | Update system configuration | ### User Management -`GET /api/v1/admin/users` -`POST /api/v1/admin/users` -`DELETE /api/v1/admin/users/{user_id}` + +| Method | Endpoint | Description | +|--------|----------|-------------| +| GET | `/api/v1/admin/users` | List all users | +| POST | `/api/v1/admin/users` | Create a new user | +| GET | `/api/v1/admin/users/{user_id}` | Get user details | +| PUT | `/api/v1/admin/users/{user_id}` | Update user | +| DELETE | `/api/v1/admin/users/{user_id}` | Delete user | ### Bot Management -`GET /api/v1/admin/bots` -`POST /api/v1/admin/bots/{bot_id}/restart` -`DELETE /api/v1/admin/bots/{bot_id}` + +| Method | Endpoint | Description | +|--------|----------|-------------| +| GET | `/api/v1/admin/bots` | List all bots | +| GET | `/api/v1/admin/bots/{bot_id}` | Get bot details | +| POST | `/api/v1/admin/bots/{bot_id}/restart` | Restart a bot | +| DELETE | `/api/v1/admin/bots/{bot_id}` | Delete a bot | ### System Health -`GET /api/v1/admin/health` -`GET /api/v1/admin/metrics` + +| Method | Endpoint | Description | +|--------|----------|-------------| +| GET | `/api/v1/admin/health` | System health check | +| GET | `/api/v1/admin/metrics` | System metrics | ### Audit Logs -`GET /api/v1/admin/audit` -## Implementation Status +| Method | Endpoint | Description | +|--------|----------|-------------| +| GET | `/api/v1/admin/audit` | Retrieve audit logs | +| GET | `/api/v1/admin/audit/{event_id}` | Get specific audit event | -This API is currently in the planning phase. Check back in future releases for availability. \ No newline at end of file +## Request Examples + +### Get System Configuration + +```bas +config = GET "/api/v1/admin/config" +TALK "Server port: " + config.server_port +``` + +### Create User + +```bas +user_data = NEW OBJECT +user_data.email = "admin@example.com" +user_data.role = "administrator" + +result = POST "/api/v1/admin/users", user_data +TALK "Created user: " + result.id +``` + +### Restart Bot + +```bas +POST "/api/v1/admin/bots/my-bot/restart", {} +TALK "Bot restart initiated" +``` + +## Response Codes + +| Code | Description | +|------|-------------| +| 200 | Success | +| 201 | Created | +| 204 | No Content (successful deletion) | +| 400 | Bad Request | +| 401 | Unauthorized | +| 403 | Forbidden (insufficient permissions) | +| 404 | Not Found | +| 500 | Internal Server Error | + +## Required Permissions + +| Endpoint Category | Required Role | +|-------------------|---------------| +| System Configuration | `admin` | +| User Management | `admin` | +| Bot Management | `admin` or `bot_manager` | +| System Health | `admin` or `monitor` | +| Audit Logs | `admin` or `auditor` | \ No newline at end of file diff --git a/src/10-rest/ai-api.md b/src/10-rest/ai-api.md index 3c6e5ed5..1c2b9284 100644 --- a/src/10-rest/ai-api.md +++ b/src/10-rest/ai-api.md @@ -1,19 +1,12 @@ # AI API -> *⚠️ Note: This API is not yet implemented and is planned for a future release.* +The AI API provides endpoints for managing AI models, inference, training, and advanced AI operations. -The AI API will provide endpoints for managing AI models, inference, training, and advanced AI operations. +## Status: Roadmap -## Planned Features +This API is on the development roadmap. The endpoints documented below represent the planned interface design. -- Model management and deployment -- Inference endpoints for various AI tasks -- Fine-tuning and training capabilities -- Model versioning and rollback -- Performance optimization settings -- Custom AI pipeline configuration - -## Base URL (Planned) +## Base URL ``` http://localhost:8080/api/v1/ai @@ -21,27 +14,107 @@ http://localhost:8080/api/v1/ai ## Authentication -Will use the standard botserver authentication mechanism with appropriate role-based permissions. +Uses the standard botserver authentication mechanism with appropriate role-based permissions. -## Endpoints (Planned) +## Endpoints ### Model Management -`GET /api/v1/ai/models` -`POST /api/v1/ai/models/deploy` -`DELETE /api/v1/ai/models/{model_id}` + +| Method | Endpoint | Description | +|--------|----------|-------------| +| GET | `/api/v1/ai/models` | List available models | +| GET | `/api/v1/ai/models/{model_id}` | Get model details | +| POST | `/api/v1/ai/models/deploy` | Deploy a new model | +| DELETE | `/api/v1/ai/models/{model_id}` | Remove a model | ### Inference -`POST /api/v1/ai/inference` -`POST /api/v1/ai/chat/completions` + +| Method | Endpoint | Description | +|--------|----------|-------------| +| POST | `/api/v1/ai/inference` | Run inference on input data | +| POST | `/api/v1/ai/chat/completions` | Chat completion endpoint | +| POST | `/api/v1/ai/embeddings` | Generate embeddings | ### Training -`POST /api/v1/ai/training/start` -`GET /api/v1/ai/training/{job_id}/status` + +| Method | Endpoint | Description | +|--------|----------|-------------| +| POST | `/api/v1/ai/training/start` | Start a training job | +| GET | `/api/v1/ai/training/{job_id}/status` | Get training job status | +| POST | `/api/v1/ai/training/{job_id}/cancel` | Cancel training job | ### Model Configuration -`GET /api/v1/ai/models/{model_id}/config` -`PUT /api/v1/ai/models/{model_id}/config` -## Implementation Status +| Method | Endpoint | Description | +|--------|----------|-------------| +| GET | `/api/v1/ai/models/{model_id}/config` | Get model configuration | +| PUT | `/api/v1/ai/models/{model_id}/config` | Update model configuration | -This API is currently in the planning phase. Check back in future releases for availability. \ No newline at end of file +## Request Examples + +### List Available Models + +```bas +models = GET "/api/v1/ai/models" +FOR EACH model IN models + TALK model.name + " - " + model.status +NEXT +``` + +### Chat Completion + +```bas +request = NEW OBJECT +request.model = "gpt-4" +request.messages = NEW ARRAY +request.messages.ADD({"role": "user", "content": "Hello, how are you?"}) + +response = POST "/api/v1/ai/chat/completions", request +TALK response.choices[0].message.content +``` + +### Generate Embeddings + +```bas +request = NEW OBJECT +request.input = "Convert this text to embeddings" +request.model = "text-embedding-3-small" + +result = POST "/api/v1/ai/embeddings", request +embedding = result.data[0].embedding +``` + +### Start Training Job + +```bas +training_config = NEW OBJECT +training_config.base_model = "llama-2-7b" +training_config.dataset = "my-training-data" +training_config.epochs = 3 + +job = POST "/api/v1/ai/training/start", training_config +TALK "Training job started: " + job.id +``` + +## Response Codes + +| Code | Description | +|------|-------------| +| 200 | Success | +| 201 | Created | +| 202 | Accepted (for async operations) | +| 400 | Bad Request | +| 401 | Unauthorized | +| 403 | Forbidden | +| 404 | Model or resource not found | +| 429 | Rate limit exceeded | +| 500 | Internal Server Error | + +## Required Permissions + +| Endpoint Category | Required Role | +|-------------------|---------------| +| Model Management | `admin` or `model_manager` | +| Inference | `user` or higher | +| Training | `admin` or `trainer` | +| Model Configuration | `admin` | \ No newline at end of file diff --git a/src/10-rest/analytics-api.md b/src/10-rest/analytics-api.md index 690d316a..57c7f99a 100644 --- a/src/10-rest/analytics-api.md +++ b/src/10-rest/analytics-api.md @@ -1,19 +1,12 @@ # Analytics API -> *⚠️ Note: This API is not yet implemented and is planned for a future release.* +The Analytics API provides endpoints for tracking, analyzing, and reporting on bot usage and performance metrics. -The Analytics API will provide endpoints for tracking, analyzing, and reporting on bot usage and performance metrics. +## Status: Roadmap -## Planned Features +This API is on the development roadmap. The endpoints documented below represent the planned interface design. -- Usage analytics and statistics -- Conversation metrics and insights -- User engagement tracking -- Performance monitoring -- Custom report generation -- Real-time analytics dashboard - -## Base URL (Planned) +## Base URL ``` http://localhost:8080/api/v1/analytics @@ -21,25 +14,126 @@ http://localhost:8080/api/v1/analytics ## Authentication -Will use the standard botserver authentication mechanism with appropriate role-based permissions. +Uses the standard botserver authentication mechanism with appropriate role-based permissions. -## Endpoints (Planned) +## Endpoints + +### Usage Statistics + +| Method | Endpoint | Description | +|--------|----------|-------------| +| GET | `/api/v1/analytics/usage` | Get overall usage statistics | +| GET | `/api/v1/analytics/usage/daily` | Get daily usage breakdown | +| GET | `/api/v1/analytics/usage/monthly` | Get monthly usage summary | + +### Conversation Metrics + +| Method | Endpoint | Description | +|--------|----------|-------------| +| GET | `/api/v1/analytics/conversations` | Get conversation metrics | +| GET | `/api/v1/analytics/conversations/volume` | Get conversation volume over time | +| GET | `/api/v1/analytics/conversations/duration` | Get average conversation duration | +| GET | `/api/v1/analytics/conversations/resolution` | Get resolution rate metrics | + +### User Engagement + +| Method | Endpoint | Description | +|--------|----------|-------------| +| GET | `/api/v1/analytics/engagement` | Get user engagement metrics | +| GET | `/api/v1/analytics/engagement/retention` | Get user retention data | +| GET | `/api/v1/analytics/engagement/satisfaction` | Get satisfaction scores | + +### Reports + +| Method | Endpoint | Description | +|--------|----------|-------------| +| POST | `/api/v1/analytics/reports` | Generate a custom report | +| GET | `/api/v1/analytics/reports/{report_id}` | Get report by ID | +| GET | `/api/v1/analytics/reports` | List all reports | + +### Real-time Metrics + +| Method | Endpoint | Description | +|--------|----------|-------------| +| GET | `/api/v1/analytics/realtime` | Get real-time metrics | +| GET | `/api/v1/analytics/realtime/active` | Get active sessions count | + +## Request Examples ### Get Usage Statistics -`GET /api/v1/analytics/usage` -### Get Conversation Metrics -`GET /api/v1/analytics/conversations` +```bas +stats = GET "/api/v1/analytics/usage" +TALK "Total conversations: " + stats.total_conversations +TALK "Active users: " + stats.active_users +``` -### Get User Engagement -`GET /api/v1/analytics/engagement` +### Get Daily Usage + +```bas +daily = GET "/api/v1/analytics/usage/daily?days=7" +FOR EACH day IN daily.data + TALK day.date + ": " + day.conversations + " conversations" +NEXT +``` ### Generate Custom Report -`POST /api/v1/analytics/reports` + +```bas +report_config = NEW OBJECT +report_config.type = "engagement" +report_config.start_date = "2025-01-01" +report_config.end_date = "2025-01-31" +report_config.format = "pdf" + +report = POST "/api/v1/analytics/reports", report_config +TALK "Report ID: " + report.id +``` ### Get Real-time Metrics -`GET /api/v1/analytics/realtime` -## Implementation Status +```bas +realtime = GET "/api/v1/analytics/realtime" +TALK "Active sessions: " + realtime.active_sessions +TALK "Messages per minute: " + realtime.messages_per_minute +``` -This API is currently in the planning phase. Check back in future releases for availability. \ No newline at end of file +## Response Codes + +| Code | Description | +|------|-------------| +| 200 | Success | +| 400 | Bad Request (invalid parameters) | +| 401 | Unauthorized | +| 403 | Forbidden (insufficient permissions) | +| 404 | Not Found | +| 500 | Internal Server Error | + +## Query Parameters + +### Time Range Filters + +| Parameter | Type | Description | +|-----------|------|-------------| +| `start_date` | String | Start date (ISO 8601 format) | +| `end_date` | String | End date (ISO 8601 format) | +| `days` | Integer | Number of days to include | +| `period` | String | Predefined period (today, week, month, year) | + +### Grouping Options + +| Parameter | Type | Description | +|-----------|------|-------------| +| `group_by` | String | Group results by (hour, day, week, month) | +| `bot_id` | UUID | Filter by specific bot | +| `user_id` | UUID | Filter by specific user | + +## Required Permissions + +| Endpoint Category | Required Role | +|-------------------|---------------| +| Usage Statistics | `analytics_viewer` or `admin` | +| Conversation Metrics | `analytics_viewer` or `admin` | +| User Engagement | `analytics_viewer` or `admin` | +| Reports | `analytics_admin` or `admin` | +| Real-time Metrics | `analytics_viewer` or `admin` | \ No newline at end of file diff --git a/src/10-rest/backup-api.md b/src/10-rest/backup-api.md index 0f7d5f40..a396eef6 100644 --- a/src/10-rest/backup-api.md +++ b/src/10-rest/backup-api.md @@ -1,18 +1,12 @@ # Backup API -> *⚠️ Note: This API is not yet implemented and is planned for a future release.* +The Backup API provides endpoints for creating, managing, and restoring backups of bot data and configurations. -The Backup API will provide endpoints for creating, managing, and restoring backups of bot data and configurations. +## Status: Roadmap -## Planned Features +This API is on the development roadmap. The endpoints documented below represent the planned interface design. -- Automated backup scheduling -- Point-in-time recovery -- Export/import bot configurations -- Data archival and retention policies -- Incremental and full backup options - -## Base URL (Planned) +## Base URL ``` http://localhost:8080/api/v1/backup @@ -20,25 +14,108 @@ http://localhost:8080/api/v1/backup ## Authentication -Will use the standard botserver authentication mechanism with appropriate role-based permissions. +Uses the standard botserver authentication mechanism with administrator-level permissions required. -## Endpoints (Planned) +## Endpoints + +### Backup Operations + +| Method | Endpoint | Description | +|--------|----------|-------------| +| POST | `/api/v1/backup/create` | Create a new backup | +| GET | `/api/v1/backup/list` | List all backups | +| GET | `/api/v1/backup/{backup_id}` | Get backup details | +| DELETE | `/api/v1/backup/{backup_id}` | Delete a backup | + +### Restore Operations + +| Method | Endpoint | Description | +|--------|----------|-------------| +| POST | `/api/v1/backup/restore/{backup_id}` | Restore from backup | +| GET | `/api/v1/backup/restore/{job_id}/status` | Check restore status | + +### Scheduling + +| Method | Endpoint | Description | +|--------|----------|-------------| +| POST | `/api/v1/backup/schedule` | Create backup schedule | +| GET | `/api/v1/backup/schedule` | List backup schedules | +| PUT | `/api/v1/backup/schedule/{schedule_id}` | Update schedule | +| DELETE | `/api/v1/backup/schedule/{schedule_id}` | Delete schedule | + +## Request Examples ### Create Backup -`POST /api/v1/backup/create` + +```bas +backup_options = NEW OBJECT +backup_options.type = "full" +backup_options.include_files = true +backup_options.include_database = true + +result = POST "/api/v1/backup/create", backup_options +TALK "Backup created: " + result.backup_id +``` ### List Backups -`GET /api/v1/backup/list` -### Restore Backup -`POST /api/v1/backup/restore/{backup_id}` +```bas +backups = GET "/api/v1/backup/list" +FOR EACH backup IN backups + TALK backup.id + " - " + backup.created_at + " (" + backup.size + ")" +NEXT +``` -### Delete Backup -`DELETE /api/v1/backup/{backup_id}` +### Restore from Backup -### Schedule Backup -`POST /api/v1/backup/schedule` +```bas +restore_options = NEW OBJECT +restore_options.target = "staging" -## Implementation Status +result = POST "/api/v1/backup/restore/backup-123", restore_options +TALK "Restore job started: " + result.job_id +``` -This API is currently in the planning phase. Check back in future releases for availability. \ No newline at end of file +### Schedule Automated Backup + +```bas +schedule = NEW OBJECT +schedule.cron = "0 2 * * *" +schedule.type = "incremental" +schedule.retention_days = 30 + +POST "/api/v1/backup/schedule", schedule +TALK "Backup schedule created" +``` + +## Backup Types + +| Type | Description | +|------|-------------| +| `full` | Complete backup of all data | +| `incremental` | Only changes since last backup | +| `differential` | Changes since last full backup | + +## Response Codes + +| Code | Description | +|------|-------------| +| 200 | Success | +| 201 | Backup created | +| 202 | Restore job accepted | +| 400 | Bad Request | +| 401 | Unauthorized | +| 403 | Forbidden | +| 404 | Backup not found | +| 409 | Restore already in progress | +| 500 | Internal Server Error | + +## Required Permissions + +| Operation | Required Role | +|-----------|---------------| +| Create backup | `admin` or `backup_operator` | +| List backups | `admin` or `backup_operator` | +| Restore backup | `admin` | +| Manage schedules | `admin` | +| Delete backup | `admin` | \ No newline at end of file diff --git a/src/10-rest/compliance-api.md b/src/10-rest/compliance-api.md index c87e72f9..74619bd2 100644 --- a/src/10-rest/compliance-api.md +++ b/src/10-rest/compliance-api.md @@ -1,21 +1,12 @@ # Compliance API -> *⚠️ Note: This API is not yet implemented and is planned for a future release.* +The Compliance API provides endpoints for regulatory compliance management, audit trails, and policy enforcement. -The Compliance API will provide endpoints for regulatory compliance management, audit trails, and policy enforcement. +## Status: Roadmap -## Planned Features +This API is on the development roadmap. The endpoints documented below represent the planned interface design. -- Regulatory compliance tracking -- Audit trail management -- Policy enforcement and validation -- Compliance reporting -- Data governance controls -- Privacy management (GDPR, CCPA) -- Retention policy management -- Compliance dashboards - -## Base URL (Planned) +## Base URL ``` http://localhost:8080/api/v1/compliance @@ -23,38 +14,144 @@ http://localhost:8080/api/v1/compliance ## Authentication -Will use the standard botserver authentication mechanism with appropriate role-based permissions. +Uses the standard botserver authentication mechanism with appropriate role-based permissions. -## Endpoints (Planned) +## Endpoints ### Compliance Status -`GET /api/v1/compliance/status` + +| Method | Endpoint | Description | +|--------|----------|-------------| +| GET | `/api/v1/compliance/status` | Get overall compliance status | +| GET | `/api/v1/compliance/status/{framework}` | Get status for specific framework (GDPR, CCPA, HIPAA) | ### Audit Trails -`GET /api/v1/compliance/audit-trails` -`POST /api/v1/compliance/audit-trails/export` + +| Method | Endpoint | Description | +|--------|----------|-------------| +| GET | `/api/v1/compliance/audit-trails` | List audit trail entries | +| GET | `/api/v1/compliance/audit-trails/{id}` | Get specific audit entry | +| POST | `/api/v1/compliance/audit-trails/export` | Export audit trails to file | ### Policy Management -`GET /api/v1/compliance/policies` -`POST /api/v1/compliance/policies` -`PUT /api/v1/compliance/policies/{policy_id}` + +| Method | Endpoint | Description | +|--------|----------|-------------| +| GET | `/api/v1/compliance/policies` | List all policies | +| POST | `/api/v1/compliance/policies` | Create a new policy | +| GET | `/api/v1/compliance/policies/{policy_id}` | Get policy details | +| PUT | `/api/v1/compliance/policies/{policy_id}` | Update a policy | +| DELETE | `/api/v1/compliance/policies/{policy_id}` | Delete a policy | ### Compliance Reports -`POST /api/v1/compliance/reports/generate` -`GET /api/v1/compliance/reports/{report_id}` + +| Method | Endpoint | Description | +|--------|----------|-------------| +| POST | `/api/v1/compliance/reports/generate` | Generate a compliance report | +| GET | `/api/v1/compliance/reports` | List generated reports | +| GET | `/api/v1/compliance/reports/{report_id}` | Download a report | ### Data Governance -`GET /api/v1/compliance/data-governance` -`POST /api/v1/compliance/data-governance/scan` + +| Method | Endpoint | Description | +|--------|----------|-------------| +| GET | `/api/v1/compliance/data-governance` | Get data governance status | +| POST | `/api/v1/compliance/data-governance/scan` | Initiate data classification scan | +| GET | `/api/v1/compliance/data-governance/scan/{scan_id}` | Get scan results | ### Privacy Management -`POST /api/v1/compliance/privacy/request` -`GET /api/v1/compliance/privacy/status` + +| Method | Endpoint | Description | +|--------|----------|-------------| +| POST | `/api/v1/compliance/privacy/request` | Submit privacy request (DSAR) | +| GET | `/api/v1/compliance/privacy/requests` | List privacy requests | +| GET | `/api/v1/compliance/privacy/status/{request_id}` | Get request status | ### Retention Policies -`GET /api/v1/compliance/retention` -`PUT /api/v1/compliance/retention` -## Implementation Status +| Method | Endpoint | Description | +|--------|----------|-------------| +| GET | `/api/v1/compliance/retention` | Get retention policies | +| PUT | `/api/v1/compliance/retention` | Update retention policies | +| POST | `/api/v1/compliance/retention/apply` | Apply retention policy | -This API is currently in the planning phase. Check back in future releases for availability. \ No newline at end of file +## Request Examples + +### Check Compliance Status + +```bas +status = GET "/api/v1/compliance/status" +TALK "GDPR Status: " + status.gdpr.status +TALK "Last Audit: " + status.last_audit_date +``` + +### Create a Policy + +```bas +policy = NEW OBJECT +policy.name = "Data Retention Policy" +policy.framework = "GDPR" +policy.rules = ["retain_logs_90_days", "anonymize_pii_on_request"] + +result = POST "/api/v1/compliance/policies", policy +TALK "Policy created: " + result.id +``` + +### Submit Privacy Request + +```bas +request = NEW OBJECT +request.type = "data_export" +request.email = "user@example.com" +request.reason = "GDPR Article 20 - Data Portability" + +result = POST "/api/v1/compliance/privacy/request", request +TALK "Request ID: " + result.request_id +``` + +### Generate Compliance Report + +```bas +report_config = NEW OBJECT +report_config.framework = "GDPR" +report_config.period = "2024-Q1" +report_config.format = "pdf" + +result = POST "/api/v1/compliance/reports/generate", report_config +TALK "Report generation started: " + result.report_id +``` + +## Response Codes + +| Code | Description | +|------|-------------| +| 200 | Success | +| 201 | Created | +| 202 | Accepted (async operation started) | +| 400 | Bad Request | +| 401 | Unauthorized | +| 403 | Forbidden (insufficient permissions) | +| 404 | Not Found | +| 500 | Internal Server Error | + +## Supported Compliance Frameworks + +| Framework | Description | +|-----------|-------------| +| GDPR | General Data Protection Regulation (EU) | +| CCPA | California Consumer Privacy Act | +| HIPAA | Health Insurance Portability and Accountability Act | +| SOC2 | Service Organization Control 2 | +| ISO27001 | Information Security Management | + +## Required Permissions + +| Endpoint Category | Required Role | +|-------------------|---------------| +| Compliance Status | `compliance_viewer` or higher | +| Audit Trails | `compliance_auditor` or `admin` | +| Policy Management | `compliance_admin` or `admin` | +| Reports | `compliance_viewer` or higher | +| Data Governance | `compliance_admin` or `admin` | +| Privacy Requests | `privacy_officer` or `admin` | +| Retention Policies | `compliance_admin` or `admin` | \ No newline at end of file diff --git a/src/10-rest/ml-api.md b/src/10-rest/ml-api.md index 64514778..1fb644b4 100644 --- a/src/10-rest/ml-api.md +++ b/src/10-rest/ml-api.md @@ -1,20 +1,12 @@ # ML API -> *⚠️ Note: This API is not yet implemented and is planned for a future release.* +The ML API provides endpoints for machine learning operations, model training, and predictive analytics. -The ML API will provide endpoints for machine learning operations, model training, and predictive analytics. +## Status: Roadmap -## Planned Features +This API is on the development roadmap. The endpoints documented below represent the planned interface design. -- Dataset management and preprocessing -- Model training and evaluation -- Hyperparameter tuning -- Batch predictions -- Model performance monitoring -- A/B testing for models -- Feature engineering tools - -## Base URL (Planned) +## Base URL ``` http://localhost:8080/api/v1/ml @@ -22,32 +14,178 @@ http://localhost:8080/api/v1/ml ## Authentication -Will use the standard botserver authentication mechanism with appropriate role-based permissions. +Uses the standard botserver authentication mechanism with appropriate role-based permissions. -## Endpoints (Planned) +## Endpoints ### Dataset Management -`POST /api/v1/ml/datasets` -`GET /api/v1/ml/datasets` -`DELETE /api/v1/ml/datasets/{dataset_id}` + +| Method | Endpoint | Description | +|--------|----------|-------------| +| POST | `/api/v1/ml/datasets` | Create a new dataset | +| GET | `/api/v1/ml/datasets` | List all datasets | +| GET | `/api/v1/ml/datasets/{dataset_id}` | Get dataset details | +| PUT | `/api/v1/ml/datasets/{dataset_id}` | Update dataset | +| DELETE | `/api/v1/ml/datasets/{dataset_id}` | Delete dataset | ### Model Training -`POST /api/v1/ml/train` -`GET /api/v1/ml/jobs/{job_id}` -`POST /api/v1/ml/jobs/{job_id}/stop` + +| Method | Endpoint | Description | +|--------|----------|-------------| +| POST | `/api/v1/ml/train` | Start a training job | +| GET | `/api/v1/ml/jobs` | List all training jobs | +| GET | `/api/v1/ml/jobs/{job_id}` | Get job details | +| POST | `/api/v1/ml/jobs/{job_id}/stop` | Stop a training job | ### Predictions -`POST /api/v1/ml/predict` -`POST /api/v1/ml/batch-predict` + +| Method | Endpoint | Description | +|--------|----------|-------------| +| POST | `/api/v1/ml/predict` | Make a single prediction | +| POST | `/api/v1/ml/batch-predict` | Make batch predictions | +| GET | `/api/v1/ml/predictions/{prediction_id}` | Get prediction result | ### Model Evaluation -`GET /api/v1/ml/models/{model_id}/metrics` -`POST /api/v1/ml/models/{model_id}/evaluate` + +| Method | Endpoint | Description | +|--------|----------|-------------| +| GET | `/api/v1/ml/models/{model_id}/metrics` | Get model metrics | +| POST | `/api/v1/ml/models/{model_id}/evaluate` | Evaluate model on test data | +| GET | `/api/v1/ml/models/{model_id}/confusion-matrix` | Get confusion matrix | ### Feature Engineering -`POST /api/v1/ml/features/extract` -`GET /api/v1/ml/features/importance` -## Implementation Status +| Method | Endpoint | Description | +|--------|----------|-------------| +| POST | `/api/v1/ml/features/extract` | Extract features from data | +| GET | `/api/v1/ml/features/importance` | Get feature importance scores | +| POST | `/api/v1/ml/features/transform` | Transform features | -This API is currently in the planning phase. Check back in future releases for availability. \ No newline at end of file +## Request Examples + +### Create Dataset + +```bas +dataset = NEW OBJECT +dataset.name = "customer_churn" +dataset.source = "customers_table" +dataset.target_column = "churned" + +result = POST "/api/v1/ml/datasets", dataset +TALK "Dataset created: " + result.id +``` + +### Start Training Job + +```bas +training_config = NEW OBJECT +training_config.dataset_id = "ds-123" +training_config.model_type = "classification" +training_config.algorithm = "random_forest" +training_config.parameters = {"n_estimators": 100, "max_depth": 10} + +job = POST "/api/v1/ml/train", training_config +TALK "Training job started: " + job.job_id +``` + +### Make Prediction + +```bas +input = NEW OBJECT +input.model_id = "model-456" +input.features = {"age": 35, "tenure": 24, "monthly_charges": 75.50} + +result = POST "/api/v1/ml/predict", input +TALK "Prediction: " + result.prediction +TALK "Confidence: " + result.confidence +``` + +### Batch Predictions + +```bas +batch_input = NEW OBJECT +batch_input.model_id = "model-456" +batch_input.data = [ + {"age": 25, "tenure": 12, "monthly_charges": 50.00}, + {"age": 45, "tenure": 36, "monthly_charges": 95.00}, + {"age": 30, "tenure": 6, "monthly_charges": 65.00} +] + +results = POST "/api/v1/ml/batch-predict", batch_input +FOR EACH result IN results.predictions + TALK result.id + ": " + result.prediction +NEXT +``` + +### Get Model Metrics + +```bas +metrics = GET "/api/v1/ml/models/model-456/metrics" +TALK "Accuracy: " + metrics.accuracy +TALK "Precision: " + metrics.precision +TALK "Recall: " + metrics.recall +TALK "F1 Score: " + metrics.f1_score +``` + +## Supported Algorithms + +### Classification + +| Algorithm | Description | +|-----------|-------------| +| `random_forest` | Random Forest Classifier | +| `gradient_boosting` | Gradient Boosting Classifier | +| `logistic_regression` | Logistic Regression | +| `svm` | Support Vector Machine | +| `neural_network` | Neural Network Classifier | + +### Regression + +| Algorithm | Description | +|-----------|-------------| +| `linear_regression` | Linear Regression | +| `random_forest_regressor` | Random Forest Regressor | +| `gradient_boosting_regressor` | Gradient Boosting Regressor | +| `neural_network_regressor` | Neural Network Regressor | + +### Clustering + +| Algorithm | Description | +|-----------|-------------| +| `kmeans` | K-Means Clustering | +| `dbscan` | DBSCAN Clustering | +| `hierarchical` | Hierarchical Clustering | + +## Response Codes + +| Code | Description | +|------|-------------| +| 200 | Success | +| 201 | Created | +| 202 | Accepted (async job started) | +| 400 | Bad Request (invalid parameters) | +| 401 | Unauthorized | +| 403 | Forbidden | +| 404 | Model or dataset not found | +| 422 | Unprocessable Entity (invalid data format) | +| 500 | Internal Server Error | + +## Job Status Values + +| Status | Description | +|--------|-------------| +| `queued` | Job is waiting to start | +| `running` | Job is in progress | +| `completed` | Job finished successfully | +| `failed` | Job encountered an error | +| `cancelled` | Job was manually stopped | + +## Required Permissions + +| Endpoint Category | Required Role | +|-------------------|---------------| +| Dataset Management | `ml_user` or higher | +| Model Training | `ml_trainer` or `admin` | +| Predictions | `ml_user` or higher | +| Model Evaluation | `ml_user` or higher | +| Feature Engineering | `ml_trainer` or `admin` | \ No newline at end of file diff --git a/src/10-rest/monitoring-api.md b/src/10-rest/monitoring-api.md index 2e83eff6..04ff4c30 100644 --- a/src/10-rest/monitoring-api.md +++ b/src/10-rest/monitoring-api.md @@ -1,20 +1,12 @@ # Monitoring API -> *⚠️ Note: This API is not yet implemented and is planned for a future release.* +The Monitoring API provides endpoints for real-time system monitoring, performance metrics, and health checks. -The Monitoring API will provide endpoints for real-time system monitoring, performance metrics, and health checks. +## Status: Roadmap -## Planned Features +This API is on the development roadmap. The endpoints documented below represent the planned interface design. -- Real-time system metrics -- Performance monitoring -- Health check endpoints -- Alert configuration -- Log aggregation -- Resource usage tracking -- Service status monitoring - -## Base URL (Planned) +## Base URL ``` http://localhost:8080/api/v1/monitoring @@ -22,29 +14,200 @@ http://localhost:8080/api/v1/monitoring ## Authentication -Will use the standard botserver authentication mechanism with appropriate role-based permissions. +Uses the standard botserver authentication mechanism with appropriate role-based permissions. -## Endpoints (Planned) +## Endpoints ### System Health -`GET /api/v1/monitoring/health` + +| Method | Endpoint | Description | +|--------|----------|-------------| +| GET | `/api/v1/monitoring/health` | Get overall system health | +| GET | `/api/v1/monitoring/health/live` | Kubernetes liveness probe | +| GET | `/api/v1/monitoring/health/ready` | Kubernetes readiness probe | ### Performance Metrics -`GET /api/v1/monitoring/metrics` + +| Method | Endpoint | Description | +|--------|----------|-------------| +| GET | `/api/v1/monitoring/metrics` | Get all metrics (Prometheus format) | +| GET | `/api/v1/monitoring/metrics/summary` | Get metrics summary | +| GET | `/api/v1/monitoring/metrics/{metric_name}` | Get specific metric | ### Service Status -`GET /api/v1/monitoring/services` + +| Method | Endpoint | Description | +|--------|----------|-------------| +| GET | `/api/v1/monitoring/services` | List all services status | +| GET | `/api/v1/monitoring/services/{service_id}` | Get specific service status | +| POST | `/api/v1/monitoring/services/{service_id}/restart` | Restart a service | ### Resource Usage -`GET /api/v1/monitoring/resources` + +| Method | Endpoint | Description | +|--------|----------|-------------| +| GET | `/api/v1/monitoring/resources` | Get resource usage overview | +| GET | `/api/v1/monitoring/resources/cpu` | Get CPU usage | +| GET | `/api/v1/monitoring/resources/memory` | Get memory usage | +| GET | `/api/v1/monitoring/resources/disk` | Get disk usage | +| GET | `/api/v1/monitoring/resources/network` | Get network statistics | ### Alert Configuration -`POST /api/v1/monitoring/alerts` -`GET /api/v1/monitoring/alerts` + +| Method | Endpoint | Description | +|--------|----------|-------------| +| GET | `/api/v1/monitoring/alerts` | List all alerts | +| POST | `/api/v1/monitoring/alerts` | Create a new alert rule | +| GET | `/api/v1/monitoring/alerts/{alert_id}` | Get alert details | +| PUT | `/api/v1/monitoring/alerts/{alert_id}` | Update alert rule | +| DELETE | `/api/v1/monitoring/alerts/{alert_id}` | Delete alert rule | +| GET | `/api/v1/monitoring/alerts/active` | Get currently firing alerts | ### Log Stream -`GET /api/v1/monitoring/logs` -## Implementation Status +| Method | Endpoint | Description | +|--------|----------|-------------| +| GET | `/api/v1/monitoring/logs` | Get recent logs | +| GET | `/api/v1/monitoring/logs/stream` | Stream logs via WebSocket | +| GET | `/api/v1/monitoring/logs/search` | Search logs with query | -This API is currently in the planning phase. Check back in future releases for availability. \ No newline at end of file +## Request Examples + +### Check System Health + +```bas +health = GET "/api/v1/monitoring/health" +TALK "System Status: " + health.status +TALK "Uptime: " + health.uptime +FOR EACH component IN health.components + TALK component.name + ": " + component.status +NEXT +``` + +### Get Performance Metrics + +```bas +metrics = GET "/api/v1/monitoring/metrics/summary" +TALK "Request Rate: " + metrics.requests_per_second + "/s" +TALK "Average Latency: " + metrics.avg_latency_ms + "ms" +TALK "Error Rate: " + metrics.error_rate + "%" +``` + +### Check Resource Usage + +```bas +resources = GET "/api/v1/monitoring/resources" +TALK "CPU: " + resources.cpu.usage_percent + "%" +TALK "Memory: " + resources.memory.used_mb + "/" + resources.memory.total_mb + " MB" +TALK "Disk: " + resources.disk.used_gb + "/" + resources.disk.total_gb + " GB" +``` + +### Create Alert Rule + +```bas +alert = NEW OBJECT +alert.name = "High CPU Alert" +alert.metric = "cpu_usage_percent" +alert.condition = ">" +alert.threshold = 80 +alert.duration = "5m" +alert.severity = "warning" +alert.notify = ["ops@example.com"] + +result = POST "/api/v1/monitoring/alerts", alert +TALK "Alert created: " + result.alert_id +``` + +### Get Active Alerts + +```bas +alerts = GET "/api/v1/monitoring/alerts/active" +IF alerts.count > 0 THEN + TALK "Active alerts: " + alerts.count + FOR EACH alert IN alerts.items + TALK alert.severity + ": " + alert.message + NEXT +ELSE + TALK "No active alerts" +END IF +``` + +### Search Logs + +```bas +params = NEW OBJECT +params.query = "error" +params.level = "error" +params.start_time = "2025-01-01T00:00:00Z" +params.limit = 100 + +logs = GET "/api/v1/monitoring/logs/search?" + ENCODE_PARAMS(params) +FOR EACH log IN logs.entries + TALK log.timestamp + " [" + log.level + "] " + log.message +NEXT +``` + +## Health Response Format + +```json +{ + "status": "healthy", + "uptime": "5d 12h 30m", + "version": "6.1.0", + "components": [ + {"name": "database", "status": "healthy", "latency_ms": 2}, + {"name": "cache", "status": "healthy", "latency_ms": 1}, + {"name": "storage", "status": "healthy", "latency_ms": 5}, + {"name": "llm", "status": "healthy", "latency_ms": 150} + ] +} +``` + +## Metrics Format + +Metrics are exposed in Prometheus format: + +``` +# HELP http_requests_total Total HTTP requests +# TYPE http_requests_total counter +http_requests_total{method="GET",status="200"} 12345 + +# HELP http_request_duration_seconds HTTP request latency +# TYPE http_request_duration_seconds histogram +http_request_duration_seconds_bucket{le="0.1"} 8000 +http_request_duration_seconds_bucket{le="0.5"} 11000 +http_request_duration_seconds_bucket{le="1"} 12000 +``` + +## Alert Severity Levels + +| Level | Description | +|-------|-------------| +| `info` | Informational, no action required | +| `warning` | Attention needed, not critical | +| `error` | Error condition, requires attention | +| `critical` | Critical, immediate action required | + +## Response Codes + +| Code | Description | +|------|-------------| +| 200 | Success | +| 201 | Alert created | +| 400 | Bad Request (invalid parameters) | +| 401 | Unauthorized | +| 403 | Forbidden (insufficient permissions) | +| 404 | Resource not found | +| 500 | Internal Server Error | +| 503 | Service Unavailable | + +## Required Permissions + +| Endpoint Category | Required Role | +|-------------------|---------------| +| Health Checks | Public (no auth for basic health) | +| Metrics | `monitor` or `admin` | +| Service Status | `monitor` or `admin` | +| Resource Usage | `monitor` or `admin` | +| Alert Configuration | `admin` | +| Logs | `admin` or `log_viewer` | \ No newline at end of file diff --git a/src/10-rest/reports-api.md b/src/10-rest/reports-api.md index 7ff765a1..b1605bbb 100644 --- a/src/10-rest/reports-api.md +++ b/src/10-rest/reports-api.md @@ -1,19 +1,12 @@ # Reports API -> *⚠️ Note: This API is not yet implemented and is planned for a future release.* +The Reports API provides endpoints for generating, managing, and exporting various types of reports from bot data and analytics. -The Reports API will provide endpoints for generating, managing, and exporting various types of reports from bot data and analytics. +## Status: Roadmap -## Planned Features +This API is on the development roadmap. The endpoints documented below represent the planned interface design. -- Custom report generation -- Scheduled report delivery -- Multiple export formats (PDF, CSV, Excel) -- Report templates and presets -- Historical data reporting -- Compliance and audit reports - -## Base URL (Planned) +## Base URL ``` http://localhost:8080/api/v1/reports @@ -21,28 +14,170 @@ http://localhost:8080/api/v1/reports ## Authentication -Will use the standard botserver authentication mechanism with appropriate role-based permissions. +Uses the standard botserver authentication mechanism with appropriate role-based permissions. -## Endpoints (Planned) +## Endpoints -### Generate Report -`POST /api/v1/reports/generate` +### Report Generation -### List Reports -`GET /api/v1/reports/list` +| Method | Endpoint | Description | +|--------|----------|-------------| +| POST | `/api/v1/reports/generate` | Generate a new report | +| GET | `/api/v1/reports/{report_id}/status` | Get report generation status | +| GET | `/api/v1/reports/{report_id}` | Get report metadata | -### Get Report Status -`GET /api/v1/reports/{report_id}/status` +### Report Management -### Download Report -`GET /api/v1/reports/{report_id}/download` +| Method | Endpoint | Description | +|--------|----------|-------------| +| GET | `/api/v1/reports` | List all reports | +| GET | `/api/v1/reports/{report_id}/download` | Download report file | +| DELETE | `/api/v1/reports/{report_id}` | Delete a report | -### Schedule Report -`POST /api/v1/reports/schedule` +### Report Scheduling -### Delete Report -`DELETE /api/v1/reports/{report_id}` +| Method | Endpoint | Description | +|--------|----------|-------------| +| POST | `/api/v1/reports/schedule` | Create scheduled report | +| GET | `/api/v1/reports/schedule` | List scheduled reports | +| PUT | `/api/v1/reports/schedule/{schedule_id}` | Update schedule | +| DELETE | `/api/v1/reports/schedule/{schedule_id}` | Delete schedule | -## Implementation Status +### Report Templates -This API is currently in the planning phase. Check back in future releases for availability. \ No newline at end of file +| Method | Endpoint | Description | +|--------|----------|-------------| +| GET | `/api/v1/reports/templates` | List available templates | +| POST | `/api/v1/reports/templates` | Create custom template | +| GET | `/api/v1/reports/templates/{template_id}` | Get template details | + +## Report Types + +| Type | Description | +|------|-------------| +| `usage` | Bot usage and activity metrics | +| `conversations` | Conversation analysis and statistics | +| `performance` | System performance metrics | +| `compliance` | Compliance and audit reports | +| `custom` | Custom report with user-defined metrics | + +## Export Formats + +| Format | Extension | Description | +|--------|-----------|-------------| +| PDF | `.pdf` | Formatted document with charts | +| CSV | `.csv` | Raw data export | +| Excel | `.xlsx` | Spreadsheet with multiple sheets | +| JSON | `.json` | Machine-readable format | +| HTML | `.html` | Web-viewable format | + +## Request Examples + +### Generate Usage Report + +```bas +report_config = NEW OBJECT +report_config.type = "usage" +report_config.start_date = "2025-01-01" +report_config.end_date = "2025-01-31" +report_config.format = "pdf" +report_config.include_charts = true + +result = POST "/api/v1/reports/generate", report_config +TALK "Report ID: " + result.report_id +``` + +### Check Report Status + +```bas +status = GET "/api/v1/reports/rpt-123/status" + +IF status.state = "completed" THEN + TALK "Report ready for download" + url = GET "/api/v1/reports/rpt-123/download" +ELSE + TALK "Report generation: " + status.progress + "%" +END IF +``` + +### Schedule Weekly Report + +```bas +schedule = NEW OBJECT +schedule.type = "conversations" +schedule.format = "pdf" +schedule.cron = "0 8 * * 1" +schedule.recipients = ["manager@company.com"] +schedule.timezone = "America/New_York" + +result = POST "/api/v1/reports/schedule", schedule +TALK "Scheduled report: " + result.schedule_id +``` + +### List Available Templates + +```bas +templates = GET "/api/v1/reports/templates" +FOR EACH template IN templates + TALK template.name + " - " + template.description +NEXT +``` + +### Generate Custom Report + +```bas +report = NEW OBJECT +report.type = "custom" +report.title = "Monthly Executive Summary" +report.sections = NEW ARRAY +report.sections.ADD({"type": "usage_summary"}) +report.sections.ADD({"type": "top_conversations"}) +report.sections.ADD({"type": "satisfaction_scores"}) +report.format = "pdf" + +result = POST "/api/v1/reports/generate", report +``` + +## Response Codes + +| Code | Description | +|------|-------------| +| 200 | Success | +| 201 | Report created | +| 202 | Report generation started | +| 400 | Bad Request (invalid parameters) | +| 401 | Unauthorized | +| 403 | Forbidden | +| 404 | Report not found | +| 500 | Internal Server Error | + +## Query Parameters + +### Filtering + +| Parameter | Type | Description | +|-----------|------|-------------| +| `type` | String | Filter by report type | +| `status` | String | Filter by status (pending, completed, failed) | +| `created_after` | DateTime | Reports created after date | +| `created_before` | DateTime | Reports created before date | + +### Pagination + +| Parameter | Type | Description | +|-----------|------|-------------| +| `limit` | Integer | Number of results (default: 20, max: 100) | +| `offset` | Integer | Pagination offset | +| `sort` | String | Sort field (created_at, name, type) | +| `order` | String | Sort order (asc, desc) | + +## Required Permissions + +| Operation | Required Role | +|-----------|---------------| +| Generate report | `report_creator` or `admin` | +| View reports | `report_viewer` or higher | +| Download reports | `report_viewer` or higher | +| Delete reports | `report_admin` or `admin` | +| Manage schedules | `report_admin` or `admin` | +| Manage templates | `report_admin` or `admin` | \ No newline at end of file diff --git a/src/10-rest/security-api.md b/src/10-rest/security-api.md index c6a58338..b4a07b4d 100644 --- a/src/10-rest/security-api.md +++ b/src/10-rest/security-api.md @@ -1,21 +1,12 @@ # Security API -> *⚠️ Note: This API is not yet implemented and is planned for a future release.* +The Security API provides endpoints for security management, access control, and threat monitoring. -The Security API will provide endpoints for security management, access control, and threat monitoring. +## Status: Roadmap -## Planned Features +This API is on the development roadmap. The endpoints documented below represent the planned interface design. -- Authentication and authorization management -- API key generation and management -- Role-based access control (RBAC) -- Security audit logging -- Threat detection and prevention -- Encryption key management -- Session management -- OAuth integration - -## Base URL (Planned) +## Base URL ``` http://localhost:8080/api/v1/security @@ -23,37 +14,187 @@ http://localhost:8080/api/v1/security ## Authentication -Will use the standard botserver authentication mechanism with elevated security permissions required. +Uses the standard botserver authentication mechanism with elevated security permissions required. -## Endpoints (Planned) +## Endpoints ### Authentication -`POST /api/v1/security/auth/login` -`POST /api/v1/security/auth/logout` -`POST /api/v1/security/auth/refresh` + +| Method | Endpoint | Description | +|--------|----------|-------------| +| POST | `/api/v1/security/auth/login` | Authenticate user | +| POST | `/api/v1/security/auth/logout` | End session | +| POST | `/api/v1/security/auth/refresh` | Refresh access token | +| POST | `/api/v1/security/auth/mfa/setup` | Setup MFA | +| POST | `/api/v1/security/auth/mfa/verify` | Verify MFA code | ### API Keys -`POST /api/v1/security/keys/generate` -`GET /api/v1/security/keys` -`DELETE /api/v1/security/keys/{key_id}` + +| Method | Endpoint | Description | +|--------|----------|-------------| +| POST | `/api/v1/security/keys/generate` | Generate new API key | +| GET | `/api/v1/security/keys` | List API keys | +| GET | `/api/v1/security/keys/{key_id}` | Get key details | +| PUT | `/api/v1/security/keys/{key_id}` | Update key permissions | +| DELETE | `/api/v1/security/keys/{key_id}` | Revoke API key | ### Access Control -`GET /api/v1/security/roles` -`POST /api/v1/security/roles` -`PUT /api/v1/security/permissions` + +| Method | Endpoint | Description | +|--------|----------|-------------| +| GET | `/api/v1/security/roles` | List all roles | +| POST | `/api/v1/security/roles` | Create a role | +| GET | `/api/v1/security/roles/{role_id}` | Get role details | +| PUT | `/api/v1/security/roles/{role_id}` | Update role | +| DELETE | `/api/v1/security/roles/{role_id}` | Delete role | +| GET | `/api/v1/security/permissions` | List all permissions | +| PUT | `/api/v1/security/permissions` | Update permissions | ### Audit Logs -`GET /api/v1/security/audit` -`GET /api/v1/security/audit/export` + +| Method | Endpoint | Description | +|--------|----------|-------------| +| GET | `/api/v1/security/audit` | List audit log entries | +| GET | `/api/v1/security/audit/{id}` | Get specific audit entry | +| POST | `/api/v1/security/audit/export` | Export audit logs | +| GET | `/api/v1/security/audit/summary` | Get audit summary | ### Session Management -`GET /api/v1/security/sessions` -`DELETE /api/v1/security/sessions/{session_id}` + +| Method | Endpoint | Description | +|--------|----------|-------------| +| GET | `/api/v1/security/sessions` | List active sessions | +| GET | `/api/v1/security/sessions/{session_id}` | Get session details | +| DELETE | `/api/v1/security/sessions/{session_id}` | Terminate session | +| DELETE | `/api/v1/security/sessions/user/{user_id}` | Terminate all user sessions | ### Security Monitoring -`GET /api/v1/security/threats` -`GET /api/v1/security/vulnerabilities` -## Implementation Status +| Method | Endpoint | Description | +|--------|----------|-------------| +| GET | `/api/v1/security/threats` | List detected threats | +| GET | `/api/v1/security/vulnerabilities` | List vulnerabilities | +| POST | `/api/v1/security/scan` | Initiate security scan | +| GET | `/api/v1/security/scan/{scan_id}` | Get scan results | -This API is currently in the planning phase. Check back in future releases for availability. \ No newline at end of file +## Request Examples + +### Login + +```bas +credentials = NEW OBJECT +credentials.email = "admin@example.com" +credentials.password = "secure_password" + +result = POST "/api/v1/security/auth/login", credentials +token = result.access_token +TALK "Logged in successfully" +``` + +### Generate API Key + +```bas +key_config = NEW OBJECT +key_config.name = "Integration Key" +key_config.scopes = ["read:bots", "write:messages"] +key_config.expires_in_days = 90 + +result = POST "/api/v1/security/keys/generate", key_config +TALK "API Key: " + result.key +TALK "Expires: " + result.expires_at +``` + +### Create Role + +```bas +role = NEW OBJECT +role.name = "bot_manager" +role.description = "Can manage bots and configurations" +role.permissions = ["bot:read", "bot:write", "bot:delete", "config:read", "config:write"] + +result = POST "/api/v1/security/roles", role +TALK "Role created: " + result.id +``` + +### List Active Sessions + +```bas +sessions = GET "/api/v1/security/sessions" +FOR EACH session IN sessions + TALK session.user_email + " - " + session.ip_address + " (" + session.last_activity + ")" +NEXT +``` + +### Query Audit Logs + +```bas +audit = GET "/api/v1/security/audit?action=login&days=7" +FOR EACH entry IN audit + TALK entry.timestamp + " | " + entry.user + " | " + entry.action + " | " + entry.result +NEXT +``` + +### Terminate Session + +```bas +DELETE "/api/v1/security/sessions/session-123" +TALK "Session terminated" +``` + +## Response Codes + +| Code | Description | +|------|-------------| +| 200 | Success | +| 201 | Created | +| 204 | No Content (successful deletion) | +| 400 | Bad Request | +| 401 | Unauthorized (invalid credentials) | +| 403 | Forbidden (insufficient permissions) | +| 404 | Not Found | +| 429 | Too Many Requests (rate limited) | +| 500 | Internal Server Error | + +## Security Event Types + +| Event Type | Description | +|------------|-------------| +| `login_success` | Successful authentication | +| `login_failed` | Failed authentication attempt | +| `logout` | User logged out | +| `password_changed` | Password was changed | +| `mfa_enabled` | MFA was enabled | +| `api_key_created` | New API key generated | +| `api_key_revoked` | API key was revoked | +| `role_changed` | User role was modified | +| `permission_denied` | Access denied to resource | +| `suspicious_activity` | Potential security threat detected | + +## Rate Limiting + +| Endpoint | Limit | +|----------|-------| +| `/auth/login` | 5 requests per minute | +| `/auth/mfa/verify` | 3 requests per minute | +| `/keys/generate` | 10 requests per hour | +| Other endpoints | 100 requests per minute | + +## Required Permissions + +| Endpoint Category | Required Role | +|-------------------|---------------| +| Authentication | Public (login) / Authenticated (others) | +| API Keys | `admin` or `key_manager` | +| Access Control | `admin` | +| Audit Logs | `admin` or `auditor` | +| Session Management | `admin` or `session_manager` | +| Security Monitoring | `admin` or `security_analyst` | + +## Best Practices + +1. **Use strong passwords** - Minimum 12 characters with mixed case, numbers, and symbols +2. **Enable MFA** - Two-factor authentication for all admin accounts +3. **Rotate API keys** - Set expiration dates and rotate keys regularly +4. **Monitor audit logs** - Review security events daily +5. **Principle of least privilege** - Grant minimum necessary permissions +6. **Terminate inactive sessions** - Auto-expire sessions after inactivity \ No newline at end of file diff --git a/src/10-rest/storage-api.md b/src/10-rest/storage-api.md index 045871a1..0a7635c7 100644 --- a/src/10-rest/storage-api.md +++ b/src/10-rest/storage-api.md @@ -1,7 +1,5 @@ # Storage API -> *⚠️ Note: This API is not yet implemented and is planned for a future release.* - botserver provides a RESTful API for managing file storage and object management through its S3-compatible storage backend. ## Overview diff --git a/src/11-features/multi-agent-design.md b/src/11-features/multi-agent-design.md index 0aacb097..1e421ec9 100644 --- a/src/11-features/multi-agent-design.md +++ b/src/11-features/multi-agent-design.md @@ -2207,23 +2207,88 @@ impl FormulaEngine { // Lookup functions self.register("VLOOKUP", |args| { - // Implementation for VLOOKUP - CellValue::Error("#N/A".to_string()) // Placeholder + if args.len() < 3 { + return CellValue::Error("#VALUE!".to_string()); + } + let lookup_value = &args[0]; + let table_array = args.get(1); + let col_index = args.get(2).and_then(|v| v.as_number()).unwrap_or(1.0) as usize; + + if let Some(CellValue::Array(rows)) = table_array { + for row in rows { + if let CellValue::Array(cells) = row { + if let Some(first_cell) = cells.get(0) { + if first_cell == lookup_value { + if let Some(result) = cells.get(col_index.saturating_sub(1)) { + return result.clone(); + } + } + } + } + } + } + CellValue::Error("#N/A".to_string()) }); self.register("HLOOKUP", |args| { - // Implementation for HLOOKUP - CellValue::Error("#N/A".to_string()) // Placeholder + if args.len() < 3 { + return CellValue::Error("#VALUE!".to_string()); + } + let lookup_value = &args[0]; + let table_array = args.get(1); + let row_index = args.get(2).and_then(|v| v.as_number()).unwrap_or(1.0) as usize; + + if let Some(CellValue::Array(rows)) = table_array { + if let Some(CellValue::Array(header_row)) = rows.get(0) { + for (col_idx, cell) in header_row.iter().enumerate() { + if cell == lookup_value { + if let Some(CellValue::Array(target_row)) = rows.get(row_index.saturating_sub(1)) { + if let Some(result) = target_row.get(col_idx) { + return result.clone(); + } + } + } + } + } + } + CellValue::Error("#N/A".to_string()) }); self.register("INDEX", |args| { - // Implementation for INDEX - CellValue::Error("#REF!".to_string()) // Placeholder + if args.len() < 2 { + return CellValue::Error("#VALUE!".to_string()); + } + let array = args.get(0); + let row_num = args.get(1).and_then(|v| v.as_number()).unwrap_or(1.0) as usize; + let col_num = args.get(2).and_then(|v| v.as_number()).unwrap_or(1.0) as usize; + + if let Some(CellValue::Array(rows)) = array { + if let Some(CellValue::Array(row)) = rows.get(row_num.saturating_sub(1)) { + if let Some(cell) = row.get(col_num.saturating_sub(1)) { + return cell.clone(); + } + } else if let Some(cell) = rows.get(row_num.saturating_sub(1)) { + return cell.clone(); + } + } + CellValue::Error("#REF!".to_string()) }); self.register("MATCH", |args| { - // Implementation for MATCH - CellValue::Error("#N/A".to_string()) // Placeholder + if args.len() < 2 { + return CellValue::Error("#VALUE!".to_string()); + } + let lookup_value = &args[0]; + let lookup_array = args.get(1); + + if let Some(CellValue::Array(cells)) = lookup_array { + for (idx, cell) in cells.iter().enumerate() { + if cell == lookup_value { + return CellValue::Number((idx + 1) as f64); + } + } + } + CellValue::Error("#N/A".to_string()) }); // Date functions diff --git a/src/theme-sync.js b/src/theme-sync.js index 5d5446e6..1500b266 100644 --- a/src/theme-sync.js +++ b/src/theme-sync.js @@ -1,115 +1,109 @@ -// Theme synchronization for SVG documents in object elements -(function() { - 'use strict'; +(function () { + "use strict"; - // Function to update SVG theme - function updateSVGTheme(objectElement) { - try { - const svgDoc = objectElement.contentDocument; - if (!svgDoc) return; + function updateSVGTheme(objectElement) { + try { + const svgDoc = objectElement.contentDocument; + if (!svgDoc) return; - const html = document.documentElement; - const body = document.body; - const svgRoot = svgDoc.documentElement; + const html = document.documentElement; + const body = document.body; + const svgRoot = svgDoc.documentElement; - // Detect current theme - const isRust = html.classList.contains('rust') || body.classList.contains('rust'); - const isLight = html.classList.contains('light') || body.classList.contains('light'); - const isDark = html.classList.contains('dark') || - html.classList.contains('ayu') || - html.classList.contains('navy') || - html.classList.contains('coal') || - body.classList.contains('theme--dark'); + const isRust = + html.classList.contains("rust") || body.classList.contains("rust"); + const isLight = + html.classList.contains("light") || body.classList.contains("light"); + const isDark = + html.classList.contains("coal") || + body.classList.contains("coal") || + html.classList.contains("navy") || + body.classList.contains("navy") || + html.classList.contains("ayu") || + body.classList.contains("ayu") || + body.classList.contains("theme--dark"); - // Set CSS variables in SVG - if (isRust || isLight) { - svgRoot.style.setProperty('--main-text-color', '#1a1a1a'); - svgRoot.style.setProperty('--secondary-text-color', '#666'); - svgRoot.style.setProperty('--arrow-color', '#666'); - } else if (isDark) { - svgRoot.style.setProperty('--main-text-color', '#ffffff'); - svgRoot.style.setProperty('--secondary-text-color', '#b0b0b0'); - svgRoot.style.setProperty('--arrow-color', '#b0b0b0'); - } + if (isRust || isLight) { + svgRoot.style.setProperty("--main-text-color", "#1a1a1a"); + svgRoot.style.setProperty("--main-bg-color", "#ffffff"); + svgRoot.style.setProperty("--accent-color", "#4a90d9"); + svgRoot.style.setProperty("--border-color", "#e0e0e0"); + } else if (isDark) { + svgRoot.style.setProperty("--main-text-color", "#e0e0e0"); + svgRoot.style.setProperty("--main-bg-color", "#1a1a2e"); + svgRoot.style.setProperty("--accent-color", "#64b5f6"); + svgRoot.style.setProperty("--border-color", "#333355"); + } - // Also try to call the SVG's internal updateTheme function if it exists - if (svgDoc.defaultView && typeof svgDoc.defaultView.updateTheme === 'function') { - svgDoc.defaultView.updateTheme(); - } - } catch (e) { - // Silent fail for cross-origin or other errors - console.debug('Could not update SVG theme:', e); - } + if ( + svgDoc.defaultView && + typeof svgDoc.defaultView.updateTheme === "function" + ) { + svgDoc.defaultView.updateTheme(); + } + } catch (e) { + console.debug("Could not update SVG theme:", e); } + } - // Function to initialize all SVG objects - function initializeSVGThemes() { - const objects = document.querySelectorAll('object[type="image/svg+xml"]'); - objects.forEach(obj => { - // Wait for object to load - if (obj.contentDocument) { - updateSVGTheme(obj); - } else { - obj.addEventListener('load', () => updateSVGTheme(obj)); - } - }); - } + function initializeSVGThemes() { + const objects = document.querySelectorAll('object[type="image/svg+xml"]'); + objects.forEach((obj) => { + if (obj.contentDocument) { + updateSVGTheme(obj); + } else { + obj.addEventListener("load", () => updateSVGTheme(obj)); + } + }); + } - // Watch for theme changes - function watchThemeChanges() { - const observer = new MutationObserver((mutations) => { - // Check if class attribute changed - const classChanged = mutations.some(m => - m.type === 'attributes' && m.attributeName === 'class' - ); + function watchThemeChanges() { + const observer = new MutationObserver((mutations) => { + const classChanged = mutations.some( + (m) => m.type === "attributes" && m.attributeName === "class", + ); - if (classChanged) { - initializeSVGThemes(); - } - }); - - // Observe both html and body elements - observer.observe(document.documentElement, { - attributes: true, - attributeFilter: ['class'] - }); - - observer.observe(document.body, { - attributes: true, - attributeFilter: ['class'] - }); - } - - // Initialize on DOM ready - if (document.readyState === 'loading') { - document.addEventListener('DOMContentLoaded', () => { - initializeSVGThemes(); - watchThemeChanges(); - }); - } else { + if (classChanged) { initializeSVGThemes(); - watchThemeChanges(); + } + }); + + observer.observe(document.documentElement, { + attributes: true, + attributeFilter: ["class"], + }); + + observer.observe(document.body, { + attributes: true, + attributeFilter: ["class"], + }); + } + + if (document.readyState === "loading") { + document.addEventListener("DOMContentLoaded", () => { + initializeSVGThemes(); + watchThemeChanges(); + }); + } else { + initializeSVGThemes(); + watchThemeChanges(); + } + + if (window.playground_text) { + const themeToggle = document.getElementById("theme-toggle"); + if (themeToggle) { + themeToggle.addEventListener("click", () => { + setTimeout(initializeSVGThemes, 100); + }); } - // Re-initialize on mdBook theme change (mdBook specific) - if (window.playground_text) { - // mdBook is present - const themeToggle = document.getElementById('theme-toggle'); - if (themeToggle) { - themeToggle.addEventListener('click', () => { - setTimeout(initializeSVGThemes, 100); - }); - } + const themeChoices = document.querySelectorAll("#theme-list button"); + themeChoices.forEach((button) => { + button.addEventListener("click", () => { + setTimeout(initializeSVGThemes, 100); + }); + }); + } - // Also watch for theme picker changes - const themeChoices = document.querySelectorAll('#theme-list button'); - themeChoices.forEach(btn => { - btn.addEventListener('click', () => { - setTimeout(initializeSVGThemes, 100); - }); - }); - } - - // Expose function globally for manual updates - window.updateAllSVGThemes = initializeSVGThemes; + window.updateAllSVGThemes = initializeSVGThemes; })();