Taimoe Engineering Standards (Google-Scale)

This document defines the engineering rigor required for the Taimoe Enterprise AI Gateway, drawing from Google's internal development practices.

1. Error Handling (Canonical Errors)

All gateway services MUST use standard error codes. Do not return arbitrary strings.

• INVALID_ARGUMENT: Client specified an invalid argument (e.g. malformed model_alias).
• FAILED_PRECONDITION: System is not in a state to perform the request.
• PERMISSION_DENIED: Caller does not have permission, or Virtual Key is invalid.
• RESOURCE_EXHAUSTED: Quota limit reached (Rate Limiting).
• INTERNAL: Internal errors (Unexpected crashes).

2. Python Style Guide (Readability)

Follow the Google Python Style Guide.

• Type Hints: Mandatory for all function signatures.
• Docstrings: Every function/method must use the Google format:

  def execute_policy(request_payload: dict) -> bool:
      """Executes the defined policy checks on the incoming request.
  
      Args:
          request_payload: The incoming JSON payload.
  
      Returns:
          A boolean indicating success.
  
      Raises:
          ValueError: If payload is malformed.
      """

3. Testing Hierarchy

• Small Tests (Unit): MUST be hermetic (no network, no disk, no external dependencies). Use unittest.mock. Execution time < 100ms per test.
• Medium Tests (Integration): Can interact with local emulators or databases (PostgreSQL/Redis) in Docker.
• Large Tests (End-to-End): Full system tests with real external APIs (e.g., Vertex AI endpoints).

4. Gateway Engine Components

Every core feature within the gateway must be modular:

• router/: Routing logic for multi-model selection.
• policies/: Business logic for rate limits, PII redaction.
• auth/: Virtual Key verification and IAM binding checks.
• tests/: Small/Medium tests colocated with the feature.

5. Observability (Traceability)

• Every API request execution must yield structured JSON logs.
• Include trace_id and span_id for distributed tracing across services.
• Never log real provider API Keys or sensitive user PII in standard logs.