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