Initial MobilityOps build pack (docs, contracts, scaffold)
This commit is contained in:
NuklearRabbit
@@ -0,0 +1,35 @@
|
||||
{
|
||||
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
||||
"$id": "https://itworx.tech/schemas/mobilityops-events-v1.json",
|
||||
"title": "MobilityOps event envelope",
|
||||
"type": "object",
|
||||
"required": ["event_id", "event_type", "occurred_at", "correlation_id", "aggregate", "data"],
|
||||
"properties": {
|
||||
"event_id": {"type": "string", "format": "uuid"},
|
||||
"event_type": {"const": "vehicle.returned.v1"},
|
||||
"occurred_at": {"type": "string", "format": "date-time"},
|
||||
"correlation_id": {"type": "string"},
|
||||
"aggregate": {
|
||||
"type": "object",
|
||||
"required": ["type", "id", "public_ref"],
|
||||
"properties": {
|
||||
"type": {"const": "booking"},
|
||||
"id": {"type": "string", "format": "uuid"},
|
||||
"public_ref": {"type": "string"}
|
||||
},
|
||||
"additionalProperties": false
|
||||
},
|
||||
"data": {
|
||||
"type": "object",
|
||||
"required": ["vehicle_ref", "inspection_ref", "resulting_vehicle_status", "attention_reasons"],
|
||||
"properties": {
|
||||
"vehicle_ref": {"type": "string"},
|
||||
"inspection_ref": {"type": "string"},
|
||||
"resulting_vehicle_status": {"enum": ["cleaning", "maintenance", "blocked"]},
|
||||
"attention_reasons": {"type": "array", "items": {"type": "string"}}
|
||||
},
|
||||
"additionalProperties": false
|
||||
}
|
||||
},
|
||||
"additionalProperties": false
|
||||
}
|
||||
@@ -0,0 +1,61 @@
|
||||
{
|
||||
"provider_id": "mobilityops",
|
||||
"version": "1.0.0",
|
||||
"required_scope": "mobilityops.read",
|
||||
"tools": [
|
||||
{
|
||||
"name": "mobilityops_get_operations_summary",
|
||||
"description": "Return current high-level vehicle, data-quality and workflow counts for the synthetic MobilityOps demo tenant.",
|
||||
"read_only": true,
|
||||
"inputSchema": {"type": "object", "additionalProperties": false},
|
||||
"endpoint": {"method": "GET", "path": "/api/v1/integrations/mcp/operations-summary"}
|
||||
},
|
||||
{
|
||||
"name": "mobilityops_list_attention_vehicles",
|
||||
"description": "List vehicles that require operational attention, optionally filtered by minimum severity and date.",
|
||||
"read_only": true,
|
||||
"inputSchema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"minimum_severity": {"enum": ["low", "medium", "high"], "default": "medium"},
|
||||
"date": {"type": "string", "format": "date"},
|
||||
"limit": {"type": "integer", "minimum": 1, "maximum": 50, "default": 20}
|
||||
},
|
||||
"additionalProperties": false
|
||||
},
|
||||
"endpoint": {"method": "GET", "path": "/api/v1/integrations/mcp/attention-vehicles"}
|
||||
},
|
||||
{
|
||||
"name": "mobilityops_get_vehicle_details",
|
||||
"description": "Return a read-only operational view of one vehicle by its stable public reference.",
|
||||
"read_only": true,
|
||||
"inputSchema": {
|
||||
"type": "object",
|
||||
"required": ["vehicle_ref"],
|
||||
"properties": {"vehicle_ref": {"type": "string", "pattern": "^MO-[0-9]{3}$"}},
|
||||
"additionalProperties": false
|
||||
},
|
||||
"endpoint": {"method": "GET", "path": "/api/v1/integrations/mcp/vehicles/{vehicle_ref}"}
|
||||
},
|
||||
{
|
||||
"name": "mobilityops_search_knowledge",
|
||||
"description": "Search versioned MobilityOps internal procedures through the dedicated RAGcore workspace and return grounded source references.",
|
||||
"read_only": true,
|
||||
"inputSchema": {
|
||||
"type": "object",
|
||||
"required": ["question"],
|
||||
"properties": {
|
||||
"question": {"type": "string", "minLength": 3, "maxLength": 1000},
|
||||
"max_sources": {"type": "integer", "minimum": 1, "maximum": 8, "default": 4}
|
||||
},
|
||||
"additionalProperties": false
|
||||
},
|
||||
"routing": {
|
||||
"preferred": "ragcore",
|
||||
"tenant": "northstar-mobility-demo",
|
||||
"workspace": "mobilityops",
|
||||
"collection": "internal-procedures"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,218 @@
|
||||
openapi: 3.1.0
|
||||
info:
|
||||
title: MobilityOps API
|
||||
version: 0.1.0
|
||||
description: Contract baseline for the MobilityOps proof of concept.
|
||||
servers:
|
||||
- url: http://localhost:8128
|
||||
paths:
|
||||
/health:
|
||||
get:
|
||||
operationId: health
|
||||
responses:
|
||||
'200':
|
||||
description: Healthy
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/Health'
|
||||
/api/v1/dashboard:
|
||||
get:
|
||||
operationId: getDashboard
|
||||
responses:
|
||||
'200':
|
||||
description: Persisted operational summary
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/Dashboard'
|
||||
/api/v1/vehicles:
|
||||
get:
|
||||
operationId: listVehicles
|
||||
parameters:
|
||||
- in: query
|
||||
name: status
|
||||
schema:
|
||||
type: string
|
||||
- in: query
|
||||
name: attention_only
|
||||
schema:
|
||||
type: boolean
|
||||
default: false
|
||||
responses:
|
||||
'200':
|
||||
description: Vehicle list
|
||||
/api/v1/vehicles/{public_ref}:
|
||||
get:
|
||||
operationId: getVehicle
|
||||
parameters:
|
||||
- $ref: '#/components/parameters/PublicRef'
|
||||
responses:
|
||||
'200':
|
||||
description: Vehicle detail
|
||||
'404':
|
||||
$ref: '#/components/responses/NotFound'
|
||||
/api/v1/bookings:
|
||||
get:
|
||||
operationId: listBookings
|
||||
responses:
|
||||
'200':
|
||||
description: Booking list
|
||||
/api/v1/bookings/{public_ref}:
|
||||
get:
|
||||
operationId: getBooking
|
||||
parameters:
|
||||
- $ref: '#/components/parameters/PublicRef'
|
||||
responses:
|
||||
'200':
|
||||
description: Booking detail
|
||||
/api/v1/bookings/{public_ref}/return:
|
||||
post:
|
||||
operationId: registerVehicleReturn
|
||||
parameters:
|
||||
- $ref: '#/components/parameters/PublicRef'
|
||||
- in: header
|
||||
name: Idempotency-Key
|
||||
required: true
|
||||
schema:
|
||||
type: string
|
||||
minLength: 8
|
||||
maxLength: 128
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/RegisterReturnRequest'
|
||||
responses:
|
||||
'200':
|
||||
description: Existing idempotent result replayed
|
||||
'201':
|
||||
description: Return registered
|
||||
'409':
|
||||
description: State or concurrency conflict
|
||||
/api/v1/data-quality/issues:
|
||||
get:
|
||||
operationId: listDataQualityIssues
|
||||
responses:
|
||||
'200':
|
||||
description: Quality issues
|
||||
/api/v1/data-quality/issues/{public_ref}/merge-customers:
|
||||
post:
|
||||
operationId: mergeDuplicateCustomers
|
||||
parameters:
|
||||
- $ref: '#/components/parameters/PublicRef'
|
||||
responses:
|
||||
'200':
|
||||
description: Merge completed
|
||||
'409':
|
||||
description: Issue no longer mergeable
|
||||
/api/v1/knowledge/questions:
|
||||
post:
|
||||
operationId: askKnowledgeQuestion
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
required: [question]
|
||||
properties:
|
||||
question:
|
||||
type: string
|
||||
minLength: 3
|
||||
maxLength: 1000
|
||||
responses:
|
||||
'200':
|
||||
description: Grounded, insufficient or unavailable answer
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/GroundedAnswer'
|
||||
/api/v1/integrations/mcp/operations-summary:
|
||||
get:
|
||||
operationId: mcpOperationsSummary
|
||||
security:
|
||||
- serviceToken: []
|
||||
responses:
|
||||
'200':
|
||||
description: Read-only operational summary
|
||||
components:
|
||||
securitySchemes:
|
||||
serviceToken:
|
||||
type: http
|
||||
scheme: bearer
|
||||
parameters:
|
||||
PublicRef:
|
||||
in: path
|
||||
name: public_ref
|
||||
required: true
|
||||
schema:
|
||||
type: string
|
||||
responses:
|
||||
NotFound:
|
||||
description: Not found
|
||||
schemas:
|
||||
Health:
|
||||
type: object
|
||||
required: [status, service]
|
||||
properties:
|
||||
status:
|
||||
const: ok
|
||||
service:
|
||||
const: mobilityops-api
|
||||
Dashboard:
|
||||
type: object
|
||||
required: [metrics, attention_items]
|
||||
properties:
|
||||
metrics:
|
||||
type: object
|
||||
additionalProperties:
|
||||
type: integer
|
||||
attention_items:
|
||||
type: array
|
||||
items:
|
||||
type: object
|
||||
RegisterReturnRequest:
|
||||
type: object
|
||||
required: [end_odometer_km, fuel_level_percent, cleanliness_ok, damage_reported, technical_warning]
|
||||
properties:
|
||||
end_odometer_km:
|
||||
type: integer
|
||||
minimum: 0
|
||||
fuel_level_percent:
|
||||
type: integer
|
||||
minimum: 0
|
||||
maximum: 100
|
||||
cleanliness_ok:
|
||||
type: boolean
|
||||
damage_reported:
|
||||
type: boolean
|
||||
technical_warning:
|
||||
type: boolean
|
||||
notes:
|
||||
type: string
|
||||
maxLength: 2000
|
||||
GroundedAnswer:
|
||||
type: object
|
||||
required: [answer, evidence_state, sources, provider, correlation_id]
|
||||
properties:
|
||||
answer:
|
||||
type: string
|
||||
evidence_state:
|
||||
enum: [grounded, insufficient, unavailable]
|
||||
sources:
|
||||
type: array
|
||||
items:
|
||||
type: object
|
||||
required: [document_id, title, version, section, excerpt]
|
||||
properties:
|
||||
document_id: {type: string}
|
||||
title: {type: string}
|
||||
version: {type: string}
|
||||
section: {type: string}
|
||||
excerpt: {type: string}
|
||||
provider:
|
||||
type: string
|
||||
correlation_id:
|
||||
type: string
|
||||
@@ -0,0 +1,13 @@
|
||||
# RAGcore contract assumptions
|
||||
|
||||
RAGcore is being built separately, so Claude must inspect its actual exposed API before finalizing the adapter. Do not edit RAGcore from this repository.
|
||||
|
||||
The MobilityOps adapter needs only these capabilities:
|
||||
|
||||
1. health/status;
|
||||
2. synchronize or ingest a document with stable ID and metadata;
|
||||
3. ask/search within one tenant/workspace/collection;
|
||||
4. receive source document ID, title, version, section and excerpt;
|
||||
5. distinguish unavailable from insufficient evidence.
|
||||
|
||||
When the actual RAGcore API differs, adapt MobilityOps behind `KnowledgeProvider`; do not leak RAGcore-specific response shapes into UI/domain code.
|
||||
Reference in New Issue
Block a user