Kailash Gold Standards - Mandatory Best Practices

Mandatory best practices and standards for all Kailash SDK development. These are required patterns that must be followed.

Overview

Gold standards are mandatory practices for:

• Absolute imports (no relative imports)
• Parameter passing patterns
• Error handling strategies
• Testing policies (NO MOCKING in Tiers 2-3)
• Workflow design principles
• Custom node development
• Security requirements
• Documentation standards
• Test creation guidelines

IMPORTANT: These are not suggestions - they are required standards that prevent bugs, ensure consistency, and maintain code quality.

Reference Documentation

Code Organization

Absolute Imports (MANDATORY)

• gold-absolute-imports - Absolute import requirement
  • Rule: ALWAYS use absolute imports, NEVER relative
  • Reason: Prevents import errors, enables refactoring
  • Pattern: from kailash.workflow.builder import WorkflowBuilder
  • Never: from ..workflow import builder

Parameter Passing (MANDATORY)

• gold-parameter-passing - Parameter standards
  • Rule: Use 4-parameter connection format
  • Pattern: workflow.add_connection(source_id, source_param, target_id, target_param)
  • Rule: Access results with dict pattern
  • Pattern: results["node_id"]["result"]
  • Never: results["node_id"].result

Testing Standards

NO MOCKING Policy (MANDATORY)

• gold-mocking-policy - NO MOCKING in Tiers 2-3
  • Rule: NO mocking in integration (Tier 2) or E2E (Tier 3) tests
  • Reason: Mocking hides real-world issues
  • Required: Use real databases, APIs, infrastructure
  • Allowed: Mocking ONLY in Tier 1 unit tests

Testing Standards (MANDATORY)

• gold-testing - Testing requirements
  • Rule: Follow 3-tier strategy (Unit, Integration, E2E)
  • Rule: Tiers 2-3 use real infrastructure
  • Rule: All tests must clean up resources
  • Rule: Tests must be deterministic

Test Creation (MANDATORY)

• gold-test-creation - Test creation standards
  • Rule: Write tests BEFORE implementation (TDD)
  • Rule: One assertion focus per test
  • Rule: Use AAA pattern (Arrange, Act, Assert)
  • Rule: Descriptive test names

Error Handling

Error Handling (MANDATORY)

• gold-error-handling - Error handling requirements
  • Rule: Always handle errors explicitly
  • Rule: Never swallow exceptions silently
  • Rule: Provide actionable error messages
  • Rule: Clean up resources in finally blocks
  • Rule: Log errors with context

Workflow & Node Design

Workflow Design (MANDATORY)

• gold-workflow-design - Workflow standards
  • Rule: Always call .build() before execution
  • Pattern: runtime.execute(workflow.build())
  • Rule: Use string-based node API
  • Rule: Validate inputs before processing
  • Rule: Single responsibility per workflow

Custom Node Development (MANDATORY)

• gold-custom-nodes - Custom node standards
  • Rule: Extend BaseNode
  • Rule: Validate all inputs
  • Rule: Handle errors gracefully
  • Rule: Document parameters clearly
  • Rule: Return consistent output format

Security & Documentation

Security (MANDATORY)

• gold-security - Security requirements
  • Rule: NEVER hardcode secrets
  • Rule: Use environment variables for credentials
  • Rule: Validate all user inputs
  • Rule: Prevent SQL injection
  • Rule: Prevent code injection
  • Rule: Use HTTPS for API calls

Documentation (MANDATORY)

• gold-documentation - Documentation standards
  • Rule: Document all public APIs
  • Rule: Include code examples
  • Rule: Keep docs updated with code
  • Rule: Use docstrings for all functions/classes
  • Rule: Explain WHY, not just WHAT

Critical Gold Standards

1. Absolute Imports ALWAYS

# ✅ CORRECT (Gold Standard)
from kailash.workflow.builder import WorkflowBuilder
from kailash.runtime.local import LocalRuntime

# ❌ WRONG (Violates Gold Standard)
from ..workflow.builder import WorkflowBuilder
from .runtime import LocalRuntime

2. NO MOCKING in Tiers 2-3

# ✅ CORRECT (Gold Standard - Tier 2)
def test_dataflow_crud(db: DataFlow):  # Real database
    """Test with real PostgreSQL/SQLite."""
    workflow = db.create_workflow(...)
    results = runtime.execute(workflow.build())
    # Verify in actual database

# ❌ WRONG (Violates Gold Standard)
def test_dataflow_crud():
    """Test with mocked database."""
    db = Mock(spec=DataFlow)  # NO MOCKING in Tier 2!
    db.create_workflow.return_value = mock_workflow

3. 4-Parameter Connections ALWAYS

# ✅ CORRECT (Gold Standard)
workflow.add_connection("node1", "result", "node2", "input_data")

# ❌ WRONG (Violates Gold Standard)
workflow.add_connection("node1", "node2")

4. Always Call .build()

# ✅ CORRECT (Gold Standard)
results = runtime.execute(workflow.build())

# ❌ WRONG (Violates Gold Standard)
results = runtime.execute(workflow)

5. Dict-Based Result Access

# ✅ CORRECT (Gold Standard)
value = results["node_id"]["result"]

# ❌ WRONG (Violates Gold Standard)
value = results["node_id"].result

6. Environment Variables for Secrets

# ✅ CORRECT (Gold Standard)
import os
api_key = os.environ["API_KEY"]

# ❌ WRONG (Violates Gold Standard)
api_key = "sk-1234567890abcdef"  # Hardcoded!

7. TDD (Test-First Development)

# ✅ CORRECT (Gold Standard)
# 1. Write test first
def test_user_creation():
    user = create_user("test@example.com")
    assert user.email == "test@example.com"

# 2. Then implement
def create_user(email):
    return User(email=email)

# ❌ WRONG (Violates Gold Standard)
# Write implementation first, then add tests

8. Explicit Error Handling

# ✅ CORRECT (Gold Standard)
try:
    results = runtime.execute(workflow.build())
except WorkflowExecutionError as e:
    logger.error(f"Workflow failed: {e}")
    raise
finally:
    cleanup_resources()

# ❌ WRONG (Violates Gold Standard)
try:
    results = runtime.execute(workflow.build())
except:  # Too broad, swallows errors
    pass  # Silent failure!

Compliance Checklist

Before Every Commit

• All imports are absolute
• All connections use 4 parameters
• Called .build() before execute
• No hardcoded secrets
• Error handling present
• Tests written (TDD)
• No mocking in Tier 2-3 tests
• Documentation updated

Before Every PR

• Gold standards validator passed
• All tests passing
• Code reviewed for compliance
• Security validation passed
• Documentation complete

Before Every Release

• Full gold standards audit
• All patterns compliant
• Security audit complete
• Documentation verified

Enforcement

Automated Validation

# Run gold standards validator
python -m kailash.validation.gold_standards validate-all

# Check specific standards
python -m kailash.validation.gold_standards check-imports
python -m kailash.validation.gold_standards check-mocking
python -m kailash.validation.gold_standards check-security

Code Review Focus

• Check absolute imports
• Verify NO MOCKING policy
• Validate connection format
• Check error handling
• Verify TDD approach
• Review security patterns

Why Gold Standards Matter

Problems They Prevent

Absolute Imports: Prevent import errors during refactoring

NO MOCKING: Catch real database issues, API timeouts, race conditions

4-Parameter Connections: Prevent wrong data routing

.build() Requirement: Prevent TypeError at runtime

Error Handling: Prevent silent failures

TDD: Prevent bugs before they exist

Security Standards: Prevent credential leaks, injection attacks

When to Use This Skill

Use this skill:

• Before writing code - Know the standards
• During code review - Validate compliance
• When in doubt - Check gold standards
• Before deployment - Ensure compliance
• When onboarding - Learn required patterns

Related Skills

• 16-validation-patterns - Validation tools
• 15-error-troubleshooting - Error patterns
• 12-testing-strategies - Testing strategies
• 01-core-sdk - Core patterns

Support

For gold standards compliance, invoke:

• gold-standards-validator - Automated compliance checking
• pattern-expert - Pattern validation
• testing-specialist - Testing compliance
• requirements-analyst - Standards documentation