traigent-schema 4.1.0__py3-none-any.whl

traigent_schema/__init__.py

@@ -0,0 +1,37 @@
+"""
+Traigent Schema Library
+
+Provides JSON Schema definitions and validation utilities for the Traigent
+AI optimization platform. This package serves as the single source of truth
+for data contracts across all Traigent services.
+
+Example:
+    from traigent_schema import SchemaValidator, get_schemas_dir
+
+    validator = SchemaValidator()
+    validator.validate_request('/api/v1/agents', 'POST', request_data)
+"""
+
+from traigent_schema.analytics_validators import AnalyticsValidator
+from traigent_schema.utils import (
+    get_all_schema_files,
+    get_contract_path,
+    get_openapi_path,
+    get_schema_path,
+    get_schemas_dir,
+    load_schema,
+)
+from traigent_schema.validator import SchemaValidator
+from traigent_schema.version import __version__
+
+__all__ = [
+    "AnalyticsValidator",
+    "SchemaValidator",
+    "get_schemas_dir",
+    "get_schema_path",
+    "get_all_schema_files",
+    "get_contract_path",
+    "get_openapi_path",
+    "load_schema",
+    "__version__",
+]

traigent_schema/analytics_validators.py

@@ -0,0 +1,226 @@
+"""Validation utilities for analytics schemas.
+
+Provides helper functions and a validator class for validating
+example scores, dataset quality, and scoring job status data
+against their respective JSON schemas.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from traigent_schema.validator import SchemaValidator
+
+
+class AnalyticsValidator:
+    """Validator for analytics-related schemas.
+
+    Provides convenience methods for validating ExampleScore, DatasetQuality,
+    and ScoringJobStatus data against their JSON schemas.
+
+    Example:
+        validator = AnalyticsValidator()
+        errors = validator.validate_example_score(score_data)
+        if not errors:
+            print("Score data is valid")
+    """
+
+    # Pre-compiled regex patterns for validation
+    _EXAMPLE_ID_PATTERN = re.compile(r'^ex_[a-f0-9]{8,12}_\d+$')
+    _JOB_ID_PATTERN = re.compile(r'^score_[a-zA-Z0-9_-]+_\d+$')
+    _ALGORITHM_VERSION_PATTERN = re.compile(r'^\d+\.\d+\.\d+$')
+
+    def __init__(self) -> None:
+        """Initialize the validator with schema validator."""
+        self._validator = SchemaValidator()
+
+    def validate_example_score(self, score_data: dict[str, Any]) -> list[str]:
+        """Validate ExampleScore data against schema.
+
+        Args:
+            score_data: Dictionary containing example score data
+
+        Returns:
+            List of validation error messages. Empty if valid.
+        """
+        return self._validator.validate_json(
+            score_data,
+            "example_score_schema"
+        )
+
+    def validate_dataset_quality(self, quality_data: dict[str, Any]) -> list[str]:
+        """Validate DatasetQuality data against schema.
+
+        Args:
+            quality_data: Dictionary containing dataset quality data
+
+        Returns:
+            List of validation error messages. Empty if valid.
+        """
+        return self._validator.validate_json(
+            quality_data,
+            "dataset_quality_schema"
+        )
+
+    def validate_scoring_job_status(self, status_data: dict[str, Any]) -> list[str]:
+        """Validate ScoringJobStatus data against schema.
+
+        Args:
+            status_data: Dictionary containing job status data
+
+        Returns:
+            List of validation error messages. Empty if valid.
+        """
+        return self._validator.validate_json(
+            status_data,
+            "scoring_job_status_schema"
+        )
+
+    def validate_example_metrics(self, data: dict[str, Any]) -> list[str]:
+        """Validate ExampleMetrics structure (nested example format).
+
+        Validates the nested structure used for per-example metrics where
+        example_id is separated from the numeric metrics.
+
+        Args:
+            data: Dictionary containing example metrics data with structure:
+                  {"example_id": "ex_...", "metrics": {"score": 0.85, ...}}
+
+        Returns:
+            List of validation error messages. Empty if valid.
+
+        Example:
+            >>> validator.validate_example_metrics({
+            ...     "example_id": "ex_abc12345_0",
+            ...     "metrics": {"score": 0.85, "cost": 0.05}
+            ... })
+            []
+        """
+        errors = []
+
+        # Check required field: example_id
+        if "example_id" not in data:
+            errors.append("Missing required field: example_id")
+        elif not isinstance(data["example_id"], str):
+            errors.append("example_id must be a string")
+        elif not self.validate_example_id_format(data["example_id"]):
+            errors.append(f"Invalid example_id format: {data['example_id']}")
+
+        # Check required field: metrics
+        if "metrics" not in data:
+            errors.append("Missing required field: metrics")
+        elif not isinstance(data["metrics"], dict):
+            errors.append("metrics must be a dict")
+        elif len(data["metrics"]) > 50:
+            errors.append(f"Too many metrics ({len(data['metrics'])}): max 50 allowed")
+        else:
+            # Validate each metric value is numeric or null
+            for key, value in data["metrics"].items():
+                if value is not None and (
+                    isinstance(value, bool) or not isinstance(value, (int, float))
+                ):
+                    errors.append(
+                        f"Metric '{key}' must be numeric or null, got {type(value).__name__}"
+                    )
+
+        return errors
+
+    def validate_example_id_format(self, example_id: str) -> bool:
+        """Validate example ID follows the required pattern.
+
+        The pattern is: ex_{hash}_{index} where hash is 8-12 hex characters
+        and index is a non-negative integer.
+
+        Args:
+            example_id: Example ID string to validate
+
+        Returns:
+            True if valid format, False otherwise
+
+        Example:
+            >>> validator.validate_example_id_format("ex_abc12345_0")
+            True
+            >>> validator.validate_example_id_format("invalid")
+            False
+        """
+        return bool(self._EXAMPLE_ID_PATTERN.match(example_id))
+
+    def validate_job_id_format(self, job_id: str) -> bool:
+        """Validate job ID follows the required pattern.
+
+        The pattern is: score_{identifier}_{timestamp} where identifier
+        can contain alphanumeric characters, underscores, and hyphens.
+
+        Args:
+            job_id: Job ID string to validate
+
+        Returns:
+            True if valid format, False otherwise
+
+        Example:
+            >>> validator.validate_job_id_format("score_exp_run_abc123_1705320600")
+            True
+            >>> validator.validate_job_id_format("invalid_job")
+            False
+        """
+        return bool(self._JOB_ID_PATTERN.match(job_id))
+
+    def validate_score_range(self, score: float) -> bool:
+        """Validate score is in valid range [0, 1].
+
+        Args:
+            score: Score value to validate
+
+        Returns:
+            True if in range [0, 1], False otherwise
+        """
+        return 0.0 <= score <= 1.0
+
+    def validate_algorithm_version(self, version: str) -> bool:
+        """Validate algorithm version follows semver pattern.
+
+        Args:
+            version: Version string (e.g., '1.0.0')
+
+        Returns:
+            True if valid semver (MAJOR.MINOR.PATCH), False otherwise
+
+        Example:
+            >>> validator.validate_algorithm_version("1.0.0")
+            True
+            >>> validator.validate_algorithm_version("v1.0.0")
+            False
+        """
+        return bool(self._ALGORITHM_VERSION_PATTERN.match(version))
+
+    def validate_recommendation_type(self, rec_type: str) -> bool:
+        """Validate recommendation type is valid.
+
+        Args:
+            rec_type: Recommendation type string
+
+        Returns:
+            True if valid type (info, warning, critical), False otherwise
+        """
+        return rec_type in ("info", "warning", "critical")
+
+    def validate_recommendation_action(self, action: str | None) -> bool:
+        """Validate recommendation action is valid.
+
+        Args:
+            action: Action string or None
+
+        Returns:
+            True if valid action (remove, add_similar, review, None), False otherwise
+        """
+        return action in ("remove", "add_similar", "review", None)
+
+    @property
+    def available_schemas(self) -> list[str]:
+        """Get list of analytics schema names."""
+        return [
+            "example_score_schema",
+            "dataset_quality_schema",
+            "scoring_job_status_schema",
+        ]

traigent_schema/schemas/agents/agent_deployment_schema.json

@@ -0,0 +1,221 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "title": "Agent Deployment Schema",
+  "description": "Defines the deployment configuration and runtime state of an AI agent in the system",
+  "version": "1.0.0",
+  "definitions": {
+    "DeploymentStatus": {
+      "type": "string",
+      "enum": ["deployed", "undeployed", "pending_deployment", "deployment_failed"],
+      "description": "Possible deployment statuses for an agent"
+    },
+    "RuntimeStatus": {
+      "type": "string",
+      "enum": ["running", "stopped", "paused", "error"],
+      "description": "Possible runtime statuses for an agent"
+    },
+    "Environment": {
+      "type": "string",
+      "enum": ["development", "staging", "production", "testing"],
+      "description": "Deployment environments for an agent"
+    },
+    "LoggingLevel": {
+      "type": "string",
+      "enum": ["error", "warn", "info", "debug", "trace"],
+      "description": "Logging levels for monitoring"
+    }
+  },
+  "properties": {
+    "id": {
+      "type": "string",
+      "description": "Unique identifier for this specific agent deployment",
+      "x-identifier": true
+    },
+    "agent_id": {
+      "type": "string",
+      "description": "Reference to the agent definition this deployment is based on"
+    },
+    "name": {
+      "type": "string",
+      "description": "Human-readable name for this deployment instance"
+    },
+    "deployment_status": {
+      "$ref": "#/definitions/DeploymentStatus"
+    },
+    "runtime_status": {
+      "$ref": "#/definitions/RuntimeStatus"
+    },
+    "environment": {
+      "$ref": "#/definitions/Environment"
+    },
+    "endpoint_url": {
+      "type": "string",
+      "format": "uri",
+      "description": "The URL where this deployed agent can be accessed"
+    },
+    "version": {
+      "type": "string",
+      "description": "Version identifier for this deployment"
+    },
+    "resource_allocation": {
+      "type": "object",
+      "description": "Resources allocated to this deployment",
+      "properties": {
+        "cpu": {
+          "type": "string",
+          "description": "CPU allocation (e.g., '0.5', '1')"
+        },
+        "memory": {
+          "type": "string",
+          "description": "Memory allocation (e.g., '512M', '1G')"
+        },
+        "gpu": {
+          "type": "string",
+          "description": "GPU allocation if applicable"
+        },
+        "concurrency": {
+          "type": "integer",
+          "description": "Maximum number of concurrent requests"
+        }
+      }
+    },
+    "scaling_config": {
+      "type": "object",
+      "description": "Configuration for auto-scaling the deployment",
+      "properties": {
+        "min_instances": {
+          "type": "integer",
+          "description": "Minimum number of instances"
+        },
+        "max_instances": {
+          "type": "integer",
+          "description": "Maximum number of instances"
+        },
+        "target_concurrency": {
+          "type": "integer",
+          "description": "Target concurrency for scaling decisions"
+        }
+      }
+    },
+    "rate_limits": {
+      "type": "object",
+      "description": "Rate limiting configuration",
+      "properties": {
+        "requests_per_minute": {
+          "type": "integer",
+          "description": "Maximum requests per minute"
+        },
+        "burst_limit": {
+          "type": "integer",
+          "description": "Maximum burst of requests allowed"
+        }
+      }
+    },
+    "deployment_config": {
+      "type": "object",
+      "description": "Additional deployment-specific configuration",
+      "additionalProperties": true
+    },
+    "monitoring": {
+      "type": "object",
+      "description": "Monitoring configuration for this deployment",
+      "properties": {
+        "logging_level": {
+          "$ref": "#/definitions/LoggingLevel"
+        },
+        "metrics_enabled": {
+          "type": "boolean",
+          "description": "Whether metrics collection is enabled"
+        },
+        "alerting_enabled": {
+          "type": "boolean",
+          "description": "Whether alerting is enabled"
+        }
+      }
+    },
+    "timestamps": {
+      "type": "object",
+      "description": "Important timestamps for this deployment",
+      "properties": {
+        "created_at": {
+          "type": "string",
+          "format": "date-time",
+          "description": "When this deployment was created"
+        },
+        "updated_at": {
+          "type": "string",
+          "format": "date-time",
+          "description": "When this deployment was last updated"
+        },
+        "deployed_at": {
+          "type": "string",
+          "format": "date-time",
+          "description": "When this agent was last deployed"
+        },
+        "started_at": {
+          "type": "string",
+          "format": "date-time",
+          "description": "When this agent was last started"
+        },
+        "stopped_at": {
+          "type": "string",
+          "format": "date-time",
+          "description": "When this agent was last stopped"
+        }
+      }
+    },
+    "creator": {
+      "type": "string",
+      "description": "Identifier of the user who created this deployment"
+    },
+    "last_modified_by": {
+      "type": "string",
+      "description": "Identifier of the user who last modified this deployment"
+    },
+    "metadata": {
+      "type": "object",
+      "description": "Additional metadata for this deployment",
+      "additionalProperties": true
+    },
+    "health_check": {
+      "type": "object",
+      "description": "Health check configuration",
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "description": "Whether health checking is enabled"
+        },
+        "path": {
+          "type": "string",
+          "description": "Path for health check requests"
+        },
+        "interval_seconds": {
+          "type": "integer",
+          "description": "Interval between health checks in seconds"
+        },
+        "timeout_seconds": {
+          "type": "integer",
+          "description": "Timeout for health check in seconds"
+        },
+        "healthy_threshold": {
+          "type": "integer",
+          "description": "Number of consecutive successful checks to be considered healthy"
+        },
+        "unhealthy_threshold": {
+          "type": "integer",
+          "description": "Number of consecutive failed checks to be considered unhealthy"
+        }
+      }
+    },
+    "tags": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Tags associated with this deployment"
+    }
+  },
+  "required": ["id", "agent_id", "deployment_status", "runtime_status", "environment", "timestamps", "creator"],
+  "additionalProperties": false
+} 

traigent_schema/schemas/agents/agent_response_schema.json

@@ -0,0 +1,188 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Agent Response Schema",
+  "description": "Schema for agent responses following OpenAI API format",
+  "version": "1.0.0",
+  "definitions": {
+    "NonStreamResponse": {
+      "type": "object",
+      "description": "A non-streaming response object following the format of the response object from the OpenAI API",
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "Unique identifier for the completion"
+        },
+        "object": {
+          "type": "string",
+          "description": "The object type (e.g., 'text_completion')"
+        },
+        "created": {
+          "type": "integer",
+          "description": "Unix timestamp of when the completion was created"
+        },
+        "model": {
+          "type": "string",
+          "description": "The model used for completion"
+        },
+        "system_fingerprint": {
+          "type": "string",
+          "description": "Fingerprint of the system configuration"
+        },
+        "choices": {
+          "type": "array",
+          "description": "Array of completion choices",
+          "items": {
+            "type": "object",
+            "properties": {
+              "text": {
+                "type": "string",
+                "description": "The completion text"
+              },
+              "index": {
+                "type": "integer",
+                "description": "Index of the choice in the array"
+              },
+              "logprobs": {
+                "type": ["object", "null"],
+                "description": "Log probabilities of tokens"
+              },
+              "finish_reason": {
+                "type": ["string", "null"],
+                "description": "Reason why the completion finished"
+              }
+            }
+          }
+        },
+        "usage": {
+          "type": "object",
+          "description": "Usage statistics for the completion",
+          "properties": {
+            "prompt_tokens": {
+              "type": "integer",
+              "description": "Number of tokens in the prompt"
+            },
+            "completion_tokens": {
+              "type": "integer",
+              "description": "Number of tokens in the completion"
+            },
+            "total_tokens": {
+              "type": "integer",
+              "description": "Total number of tokens used"
+            }
+          }
+        },
+        "metadata": {
+          "type": "object",
+          "description": "Additional metadata about the completion",
+          "additionalProperties": true
+        }
+      },
+      "additionalProperties": true
+    },
+    "StreamResponse": {
+      "type": "object",
+      "description": "A streaming response object following the format of the response object from the OpenAI API",
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "Unique identifier for the completion"
+        },
+        "object": {
+          "type": "string",
+          "description": "The object type (e.g., 'text_completion')"
+        },
+        "created": {
+          "type": "integer",
+          "description": "Unix timestamp of when the completion was created"
+        },
+        "choices": {
+          "type": "array",
+          "description": "Array of completion choices",
+          "items": {
+            "type": "object",
+            "properties": {
+              "text": {
+                "type": "string",
+                "description": "The completion text"
+              },
+              "index": {
+                "type": "integer",
+                "description": "Index of the choice in the array"
+              },
+              "logprobs": {
+                "type": ["object", "null"],
+                "description": "Log probabilities of tokens"
+              },
+              "finish_reason": {
+                "type": ["string", "null"],
+                "description": "Reason why the completion finished"
+              }
+            }
+          }
+        },
+        "model": {
+          "type": "string",
+          "description": "The model used for completion"
+        },
+        "system_fingerprint": {
+          "type": "string",
+          "description": "Fingerprint of the system configuration"
+        }
+      },
+      "additionalProperties": true
+    },
+    "AgentExecutionStatus": {
+      "type": "string",
+      "enum": ["success", "failed", "cancelled", "timeout"],
+      "description": "Status of the agent execution"
+    }
+  },
+  "type": "object",
+  "description": "Agent execution response containing input, output, and execution metadata",
+  "properties": {
+    "id": {
+      "type": "string",
+      "description": "Unique identifier for the execution response"
+    },
+    "input": {
+      "type": "object",
+      "description": "Input provided to the agent",
+      "additionalProperties": true
+    },
+    "expected_output": {
+      "type": ["string", "null"],
+      "description": "Expected output for evaluation purposes"
+    },
+    "status": {
+      "$ref": "#/definitions/AgentExecutionStatus",
+      "description": "Status of the agent execution"
+    },
+    "result": {
+      "oneOf": [
+        { "$ref": "#/definitions/NonStreamResponse" },
+        { "$ref": "#/definitions/StreamResponse" }
+      ],
+      "description": "Result of the agent execution"
+    },
+    "created_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "Timestamp when the execution was created"
+    },
+    "error": {
+      "type": ["string", "null"],
+      "description": "Error message if execution failed"
+    },
+    "message": {
+      "type": ["string", "null"],
+      "description": "Additional message about the execution"
+    },
+    "metadata": {
+      "type": "object",
+      "description": "Additional metadata about the execution",
+      "additionalProperties": true
+    }
+  },
+  "required": ["id", "input", "status", "result", "created_at"],
+  "additionalProperties": false
+}