Lightweight AI Model API Runtime Specification 1.2

Overview

The Lightweight AI Model API Runtime Specification 1.2 defines a standardized REST API interface for AI model deployment and inference. This specification enables consistent integration of AI models across different platforms and applications, providing a uniform interface for health monitoring, capability discovery, prediction, and operational metrics. Version 1.2 Changes: Enhanced port registry integration with process tracking, improved startup sequence, and more robust shutdown handling.

Design Principles

Simplicity: Minimal required endpoints with clear semantics

Consistency: Uniform request/response patterns across all endpoints

Observability: Built-in health checks and metrics

Flexibility: Generic data structures supporting various input/output types

Testability: Built-in test examples for validation and learning

Registration Required: All deployments must be registered with Paramus Transform LLC

---

API Endpoints

1. Health Check

Endpoint: GET /health Description: Returns the operational status of the model service. Response:

{
  "status": "ok",
  "model": "ModelName",
  "version": "1.2.0"
}

Status Codes:

200 OK: Service is operational

503 Service Unavailable: Service is not ready

---

2. Capabilities

Endpoint: GET /capabilities Description: Returns the model's capabilities, supported input types, and output schema. Response:

{
  "model": "ModelName",
  "capabilities": [
    {
      "name": "embedding",
      "input_types": ["text"],
      "output_schema": {
        "embedding": "array"
      },
      "description": "Generates a fixed-size embedding vector from input text."
    }
  ],
  "elements": ["C", "H", "O", "N", "..."]
}

Fields:

model: Model identifier

capabilities: Array of capability objects

- name: Capability identifier (e.g., "embedding", "classification", "regression") - input_types: Array of supported input types (e.g., "text", "image", "audio") - output_schema: Structure of the output data - description: Human-readable description

elements: Optional array of supported elements or features

---

3. Acceptable Ranges

Endpoint: GET /acceptable_ranges Description: Returns proven acceptable input/output ranges based on training data. These ranges represent the chemical space and property values where the model has been validated through training and experimental verification. Response:

{
  "model": "PolyNC",
  "version": "1.2.0",
  "description": "Proven acceptable ranges based on training data (22,970 samples)",
  "property_ranges": {
    "Tg": {
      "property_name": "Glass Transition Temperature",
      "unit": "°C",
      "training_range": {
        "min": -85.15,
        "max": 442.0,
        "mean": 195.46
      },
      "reliable_range": {
        "min": -150.0,
        "max": 450.0,
        "note": "Predictions outside this range may be less reliable"
      },
      "training_samples": 685,
      "validation_metrics": {
        "R2": "0.85-0.92",
        "typical_error": "±15-25°C"
      }
    }
  },
  "chemical_scope": {
    "supported_features": [
      "Aromatic systems",
      "Aliphatic chains",
      "Heteroatoms (O, N, S, P, halogens)"
    ],
    "limitations": [
      "Organometallic polymers (limited support)",
      "Very large molecules (SMILES length > 1024 tokens)"
    ]
  },
  "usage_recommendations": [
    "Predictions within training_range are most reliable",
    "Out-of-range predictions should be validated experimentally"
  ]
}

Fields:

model: Model identifier

version: API version

description: Overview of the data source

property_ranges: Detailed ranges for each supported property

- property_name: Human-readable property name - unit: Unit of measurement - training_range: Min, max, and mean values from training data - reliable_range: Extended range where predictions may still be reasonable - training_samples: Number of samples used for this property - validation_metrics: Performance metrics (R², error ranges)

chemical_scope: Supported chemical features and limitations

usage_recommendations: Best practices for interpretation

Status Codes:

200 OK: Acceptable ranges returned successfully

Note: This endpoint provides transparency about the model's validated operating ranges. Predictions outside these ranges should be treated with increased skepticism and validated experimentally. ---

4. Prediction

Endpoint: POST /predict Description: Executes model inference on provided input data. Request Body:

{
  "input_type": "text",
  "data": {
    "text": "CC"
  }
}

Request Fields:

input_type: Type of input being provided (must match supported types from /capabilities)

data: Object containing the actual input data, structure varies by input_type

Response:

{
  "success": true,
  "model_name": "ModelName",
  "results": {
    "embedding": [0.45, -1.58, -0.08, "..."]
  },
  "computation_time_ms": 32.016,
  "error_message": null
}

Response Fields:

success: Boolean indicating whether prediction succeeded

model_name: Name of the model that generated the prediction

results: Object containing prediction results (structure varies by capability)

computation_time_ms: Time taken for inference in milliseconds

error_message: Error description if success is false, otherwise null

Status Codes:

200 OK: Prediction completed (check success field for actual status)

400 Bad Request: Invalid input format

500 Internal Server Error: Server error during processing

---

5. Model Information

Endpoint: GET /info Description: Returns metadata about the model including citation, license, and maintainer information. Response:

{
  "name": "ModelName",
  "description": "Description of the model's purpose and capabilities.",
  "license": "MIT",
  "citation": "https://doi.org/...",
  "maintainer": "Organization or Individual"
}

Fields:

name: Model name

description: Detailed description of model functionality

license: Software license type

citation: URL or DOI to academic paper or documentation

maintainer: Entity responsible for the model deployment

---

6. Metrics

Endpoint: GET /metrics Description: Returns operational metrics for monitoring and observability. Response:

{
  "uptime_s": 3600,
  "requests_served": 150,
  "avg_latency_ms": 45.2,
  "last_error": null
}

Fields:

uptime_s: Seconds since service started

requests_served: Total number of prediction requests processed

avg_latency_ms: Average prediction latency in milliseconds

last_error: Description of most recent error, or null if no errors

---

7. Citation

Endpoint: GET /citation Description: Returns human-readable citation information and BibTeX entries for both the underlying model and the software platform. Response:

{
  "paper_citation": "Xu, C.; Wang, Y.; Barati Farimani, A.\nTransPolymer: a Transformer-based language model for polymer property predictions.\nnpj Computational Materials 9, 64 (2023). DOI:10.1038/s41524-023-01009-9",
  "software_bibtex": "@software{paramus_ai_2025,\n  author       = {Gressling, Thorsten},\n  title        = {Paramus.ai: An Agent-Driven Chemistry Platform for AI-Augmented Scientific Workflows},\n  year         = {2025},\n  publisher    = {Paramus Transform LLC},\n  url          = {https://paramus.ai},\n  version      = {v1.0},\n  note         = {Available at https://paramus.ai}\n}"
}

Fields:

paper_citation: Human-readable citation string for the underlying research paper or model

software_bibtex: BibTeX entry for the software platform/API implementation

Status Codes:

200 OK: Citations returned successfully

Note: This endpoint provides proper attribution for both the scientific work and the software infrastructure. ---

8. Test Examples

Endpoint: GET /test_examples Description: Returns example inputs and usage patterns for testing the model API. Response:

{
  "examples": [
    {
      "name": "Ethylene",
      "smiles": "CC",
      "description": "Simple alkene polymer building block",
      "category": "basic_polymer"
    },
    {
      "name": "Styrene", 
      "smiles": "CC(c1ccccc1)",
      "description": "Aromatic polymer monomer (polystyrene)",
      "category": "aromatic_polymer"
    }
  ],
  "usage_instructions": {
    "endpoint": "/predict",
    "method": "POST",
    "body_format": {
      "input_type": "text",
      "data": {
        "text": "SMILES_STRING_HERE"
      }
    }
  },
  "expected_output": {
    "success": true,
    "model_name": "ModelName",
    "results": {
      "embedding": "Array of N floating-point numbers"
    },
    "computation_time_ms": "Typical range varies by model",
    "error_message": null
  },
  "notes": [
    "Input format varies by model type",
    "Examples are model-specific",
    "Computation time varies with input complexity"
  ]
}

Fields:

examples: Array of sample inputs with metadata

- name: Human-readable identifier for the example - [input_field]: Model-specific input (e.g., "smiles", "text", "image_url") - description: Explanation of what the example represents - category: Classification or grouping of the example

usage_instructions: How to use the examples with the prediction endpoint

expected_output: Template showing the expected response structure

notes: Important information about using the examples

Status Codes:

200 OK: Examples returned successfully

Note: This endpoint provides ready-to-use test cases for validating model functionality and learning the API usage patterns. ---

9. Shutdown

Endpoint: POST /shutdown Description: Initiates graceful shutdown of the service. Response:

{
  "success": true,
  "message": "Shutdown process initiated."
}

Status Codes:

200 OK: Shutdown initiated successfully

403 Forbidden: Shutdown not allowed (optional implementation)

Note: This endpoint is optional and may be disabled in production environments. ---

Port Registry Service

Overview

The BRAIN ecosystem uses a centralized port registry service to manage dynamic port allocation for multiple model instances. This prevents port conflicts and enables service discovery.

Registry Service

Location: /service_tester/port_registry.py Default Port: 5000 (reserved) Purpose:

Assigns unique ports to model instances (starting from 5100)

Tracks active registrations with metadata

Provides heartbeat monitoring

Enables graceful cleanup on shutdown

Tracks process IDs for health monitoring

Registry API Endpoints

1. Register Service

Endpoint: POST /register Request:

{
  "app_name": "PolyNC_API",
  "app_version": "1.2.0",
  "model_name": "PolyNC",
  "process_id": 12345,
  "preferred_port": null,
  "reason": "Starting model instance",
  "metadata": {
    "model_type": "transformer",
    "capabilities": ["polymer_property_prediction"]
  }
}

Required Fields (v1.2):

app_name: Application identifier

app_version: Application version (should be "1.2.0" or higher)

model_name: Model identifier

process_id: Operating system process ID (REQUIRED in v1.2)

preferred_port: Requested port or null for auto-assignment

reason: Human-readable reason for registration

metadata: Additional information about the service

Response:

{
  "success": true,
  "assigned_port": 5100,
  "registration_id": "brain_reg_1234567890_0001",
  "message": "Successfully registered",
  "expires_at": "2025-12-05T12:00:00"
}

2. Unregister Service

Endpoint: DELETE /unregister/{port} Query Parameters: registration_id (required) Response:

{
  "success": true,
  "message": "Unregistered from port 5100",
  "freed_port": 5100
}

3. View Registry

Endpoint: GET /registry Response: Returns all active registrations with process information

4. Heartbeat

Endpoint: POST /heartbeat/{port} Purpose: Keep registration alive and update last_heartbeat timestamp

Version 1.2 Startup Sequence (CRITICAL)

CORRECT FLOW (API 1.2 compliant):

1. Request port from registry (POST /register with process_id)
   ↓
Receive assigned port (e.g., 5100)

   ↓
Start HTTP server on ASSIGNED port

   ↓
Service ready on correct port

INCORRECT FLOW (causes port conflicts):

1. Start server on hardcoded port (e.g., 5001)  ❌
   ↓
Request port from registry → gets different port (e.g., 5100)

   ↓
Service running on wrong port (5001 instead of 5100)  ❌

Implementation Requirements (v1.2)

All v1.2 implementations MUST:

Request Port BEFORE Starting Server

# Get port from registry FIRST
   port = await get_port_from_registry()
   
   # THEN start server on assigned port
   uvicorn.run(app, host="127.0.0.1", port=port)

Include Process ID in Registration

registration_data = {
       "app_name": "YourApp_API",
       "app_version": "1.2.0",
       "model_name": "YourModel",
       "process_id": os.getpid(),  # REQUIRED
       "preferred_port": None
   }

Initialize Heartbeat Task Attribute

class AppState:
       def __init__(self):
           self.heartbeat_task: Optional[asyncio.Task] = None
           self.registry_available: bool = False

Guard Heartbeat Cancellation

if hasattr(app_state, 'heartbeat_task') and app_state.heartbeat_task:
       app_state.heartbeat_task.cancel()

Handle Registry Unavailable During Shutdown

except Exception as e:
       # Registry may be stopped - this is normal
       logger.info("Registry unavailable - skipping unregistration (normal during shutdown)")

Starting the Registry

Windows:

run_service_tester.bat

Direct:

python service_tester/port_registry.py

The registry will start on http://127.0.0.1:5000 and display all registration activity.

Testing

Use the included test suite to verify registry integration:

python service_tester/test_registry_integration.py

See /service_tester/README.md for detailed documentation. ---

Implementation Requirements

Required Headers

All requests should include:

Content-Type: application/json

Error Handling

All endpoints must handle errors gracefully and return appropriate HTTP status codes. Error responses should follow this format:

{
  "success": false,
  "error": "Error description",
  "error_code": "ERROR_CODE"
}

Versioning

API version is embedded in the specification name (e.g., "1.2"). Future versions will increment accordingly.

Required Endpoints

Version 1.2 implementations must include:

/health - Service status

/capabilities - Model capabilities and schemas

/acceptable_ranges - Proven acceptable ranges based on training data (NEW in v1.2)

/predict - Primary inference endpoint

/info - Model metadata and attribution

/metrics - Operational metrics

/citation - Research and software citations

/test_examples - Sample inputs and usage patterns

/shutdown - Graceful shutdown (optional)

Performance Guidelines

/health endpoint should respond in < 100ms

/predict endpoint should include timeout mechanisms

Services should handle concurrent requests appropriately

---

Example Implementation

PolyNC API Example (v1.2 Compliant)

The PolyNC API demonstrates a complete implementation of specification v1.2, available as both a standalone executable and Windows installer: Startup Output:

================================================================================
PolyNC API - Polymer Property Prediction Service
================================================================================

CITATION:
  PolyNC: Polymer Natural and Chemical language model
  for unified polymer property prediction
  GitHub Repository: https://github.com/Gressling/BRAIN_PolyNC

API SPECIFICATION:
  Using the Lightweight AI Model API Runtime Specification 1.2 from:
  © 2025 Paramus Transform LLC
  2020 N ACADEMY BLVD, STE 261 #3770
  COLORADO SPRINGS, CO 80909, U.S.

NOTICE: Registration is required to use this service.
================================================================================

REGISTRATION_SUCCESS: PolyNC_API registered on port 5100
Starting PolyNC API server on port 5100

Example Prediction Request:

$body = @{
    input_type = "text"
    data = @{
        text = "CC"
        property = "Tg"
    }
} | ConvertTo-Json

Invoke-RestMethod -Uri "http://127.0.0.1:5100/predict" 
    -Method Post 
    -Body $body 
    -ContentType "application/json"



Example Response:
{
  "success": true,
  "model_name": "PolyNC",
  "results": {
    "prediction": "284.5",
    "property_type": "Tg",
    "smiles": "CC"
  },
  "computation_time_ms": 156.32,
  "error_message": null
}


Deployment Options


Windows Installer:

Professional Windows installer (PolyNC_Installer.exe

Installs to %APPDATA%\Paramus\Brain\models\PolyNC


Start Menu integration: Paramus → Brain → models → PolyNC

Silent install support: PolyNC_Installer.exe /S


Automatic uninstall of previous versions

Windows registry integration (Add/Remove Programs)


Standalone Executable:

Self-contained PolyNC_API.exe

 with all dependencies


No installation required - runs directly

Portable deployment for testing and development


Service Management:
Port registry integration for multi-instance deployment

Automatic port assignment (default: 5100+)

Process ID tracking for health monitoring

Graceful shutdown and cleanup

Health monitoring and metrics collection


---

Registration and Licensing


Registration Requirement


All implementations of this specification require registration with Paramus Transform LLC. To register your deployment:

Contact: Paramus Transform LLC

Address: 2020 N ACADEMY BLVD, STE 261 #3770, COLORADO SPRINGS, CO 80909, U.S.

Provide: Model name, deployment environment, intended use case


Compliance


Implementations must:
Display the specification attribution on startup

Include registration notice in documentation

Implement all required endpoints (/health, /capabilities, /predict, /info, /metrics)

Follow the standardized request/response formats

Request port from registry BEFORE starting server (v1.2)

Include process ID in registration (v1.2)


Prohibited Uses


Implementations of this specification may not be used for:
Purposes that violate applicable laws

Harmful, unethical, or malicious applications

Deployment without proper registration


---

Specification History


| Version | Date | Changes |
|---------|------|---------|
| 1.0 | 2025 | Initial release |
| 1.1 | 2025 | Added /test_examples endpoint, enhanced testability principle |
| 1.2 | December 2025 | Enhanced port registry integration: Process ID tracking, startup sequence fix (request port BEFORE starting server), improved shutdown handling, heartbeat task initialization, graceful registry unavailability handling |

---

Migration from v1.1 to v1.2


Required Changes


Add AppState attributes:

   self.heartbeat_task: Optional[asyncio.Task] = None
   self.registry_available: bool = False
   

Include process_id in registration:

   "process_id": os.getpid()
   

Request port BEFORE starting server:

   port = await get_port_from_registry()
   uvicorn.run(app, host="127.0.0.1", port=port)
   

Guard heartbeat_task access:

   if hasattr(app_state, 'heartbeat_task') and app_state.heartbeat_task:
   

Update version strings to "1.2.0"


Backwards Compatibility


v1.2 implementations remain compatible with v1.1 registries, but v1.2 registries provide enhanced features:
Process health monitoring

Better port conflict detection

Improved service discovery


---

Contact Information


Paramus Transform LLC  
2020 N ACADEMY BLVD, STE 261 #3770  
COLORADO SPRINGS, CO 80909  
United States

For questions, registration, or support regarding this specification, please contact Paramus Transform LLC.

---

Appendix: Data Type Definitions


Input Types

text

: String data (e.g., SMILES, natural language)

image

: Image data (base64 encoded or URL)

audio

: Audio data (base64 encoded or URL)

tabular

: Structured data (JSON object or array)



Output Types

array

: Array of floating-point numbers (e.g., embeddings)

array

: Array of strings (e.g., classifications)

object

: JSON object with arbitrary structure

float

: Single floating-point number (e.g., regression value)

string`: Single string (e.g., label)

--- END OF SPECIFICATION ---

License

MIT License

Copyright (c) 2025 Paramus Transform LLC Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.