chore: standardize environment variable naming for Graph API configuration

[jfrench9]

Summary

This PR refactors the environment variable configuration system to establish consistent naming conventions across the Graph API and related components. The changes affect configuration management, client factories, middleware components, and infrastructure definitions.

Key Accomplishments

• Standardized environment variable naming: Updated variable names across configuration files, CloudFormation templates, and Docker Compose to follow consistent patterns
• Refactored configuration management: Enhanced the environment configuration system in robosystems/config/ with improved structure and validation
• Updated Graph API references: Modernized client factories, cluster managers, and middleware components to use the new configuration approach
• Comprehensive test coverage updates: Modified all affected test files to align with the new environment variable structure
• Infrastructure alignment: Updated CloudFormation templates and deployment configurations to use standardized variable names

Breaking Changes

⚠️ Environment Variables: This change introduces new environment variable names that replace existing ones. Teams will need to update their:

• Local development environment files
• CI/CD pipeline configurations
• Production environment settings
• Any scripts or tooling that reference the old variable names

Testing Notes

• All existing tests have been updated to reflect the new environment variable structure
• Configuration validation tests have been enhanced to cover the new naming patterns
• Graph API client and middleware tests verify proper integration with the updated configuration system
• No functional behavior changes - only configuration interface updates

Infrastructure Considerations

• CloudFormation stacks will require parameter updates during deployment
• Container orchestration configurations need environment variable updates
• Secret management systems may need key mapping updates
• Monitoring and logging configurations should be reviewed for any hardcoded references to old variable names

The refactoring maintains backward compatibility in terms of functionality while establishing a cleaner, more maintainable configuration structure for future development.

---

🤖 Generated with Claude Code

Branch Info:

• Source: chore/rename-graph-env-vars
• Target: main
• Type: chore

Co-Authored-By: Claude noreply@anthropic.com

[jfrench9]

@claude please review this PR

[claude]

Claude finished @jfrench9's task —— View job

---

Code Review Complete ✅

I've completed a thorough review of this PR which refactors environment variable naming for Graph API configuration. Overall, this is a well-executed refactoring that successfully standardizes naming conventions across the codebase.

---

Summary

This PR transitions from Kuzu-specific environment variable names (e.g., KUZU_API_URL, KUZU_CIRCUIT_BREAKERS_ENABLED) to backend-agnostic names (e.g., GRAPH_API_URL, GRAPH_CIRCUIT_BREAKERS_ENABLED). The refactoring spans 39 files with comprehensive updates to configuration, infrastructure templates, application code, and tests.

Key Changes:

• Environment Variables: Renamed 20+ variables from KUZU_* to GRAPH_* prefix
• Configuration: Reorganized env.py with clearer multi-backend structure
• Infrastructure: Updated CloudFormation templates and Docker Compose
• Tests: Updated all test configurations and mocks
• Documentation: Enhanced comments to reflect multi-backend architecture

---

Strengths 💪

1. Comprehensive Coverage: The refactoring touches all necessary files consistently - configuration, application code, tests, infrastructure templates, and documentation.

2. Backward Compatibility Maintained: While variable names changed, the functional behavior remains identical. No logic changes, only interface updates.

3. Multi-Backend Architecture: The new naming better reflects the system's capability to support multiple graph backends (Kuzu, Neo4j Community, Neo4j Enterprise).

4. Well-Organized Configuration: The updated robosystems/config/env.py has improved structure with clear sections:

   • Lines 368-414: Generic GRAPH_* configuration (applies to all backends)
   • Lines 415-461: Kuzu-specific configuration
   • Lines 472-481: Neo4j-specific configuration

5. Test Coverage: All test files properly updated with new variable names in mocks and fixtures.

6. Infrastructure Consistency: CloudFormation templates consistently updated across all stacks (api.yaml, worker.yaml, beat.yaml, kuzu-infra.yaml, etc.).

---

Issues & Recommendations 🔍

Critical Issues

1. Missing Backward Compatibility in allocation_manager.py

The DatabaseLocation dataclass adds a new field without a default value initially, then adds backend_type: str = "kuzu" as a default. However, existing DynamoDB records won't have this field. Lines 429 and 553 handle this with .get("backend_type", "kuzu"), which is good, but:

# robosystems/middleware/graph/allocation_manager.py:84
backend_type: str = "kuzu"  # ✅ Has default

Recommendation: Consider a migration strategy if there are existing production databases. The current approach with defaults should work, but verify:

• Existing DynamoDB items can be read without errors
• The backend_type field is properly backfilled for existing allocations

2. Incomplete Variable Renaming in Test Fixtures

In tests/graph_api/client/test_factory.py:118, I see:

mock.KUZU_REPLICA_ENDPOINT = "http://replica.example.com"
mock.KUZU_MASTER_ENDPOINT = "http://master.example.com"

These variables still use KUZU_* prefix but I don't see them being renamed. Check if these are:

• Still in use in the codebase (if so, they should be renamed to GRAPH_*)
• Deprecated variables that can be removed from tests

3. CloudFormation Secret Key Name Change

In cloudformation/kuzu-infra.yaml:227, the secret key changed from KUZU_API_KEY to GRAPH_API_KEY. This is a breaking change for:

• Existing secret retrievals in running applications
• Any automation that reads these secrets
• CloudFormation stack updates

Recommendation: Document the secret key migration path:

1. Does the old KUZU_API_KEY need to be maintained during transition?
2. Should there be a migration period with both keys?
3. Update deployment runbooks to handle this change

---

Medium Priority Issues

4. Mixed Naming in Comments and Documentation

Some comments still reference "Kuzu" specifically when they should be backend-agnostic:

# robosystems/config/env.py:71-73 (from constants import)
KUZU_MAX_REQUEST_SIZE,
KUZU_CONNECT_TIMEOUT,
KUZU_READ_TIMEOUT,

These constants are imported and used as GRAPH_* values, but the constant names themselves remain KUZU_*. This creates confusion.

Recommendation: Consider renaming these constants in constants.py to use GRAPH_* prefix as well for consistency.

5. Environment Variable Documentation in .env.example

The .env.example file has excellent organization with the new structure (lines 89-163), but there's a potential inconsistency:

## Graph API Configuration (unified access layer for all backends)
GRAPH_API_URL=http://kuzu-api:8001  # Still references 'kuzu-api' service name

While this is technically correct for the current Docker Compose setup, it might be confusing. Consider:

• Renaming the service to graph-api in compose.yaml
• OR adding a comment explaining that kuzu-api is the service name regardless of backend

6. KUZU_DATABASES_PER_INSTANCE Still Backend-Specific

In .env.example:140 and throughout the code, KUZU_DATABASES_PER_INSTANCE remains Kuzu-specific, which makes sense since Neo4j has different capacity models. However, this creates an asymmetry in the configuration.

Recommendation: Consider adding a generic GRAPH_DATABASES_PER_INSTANCE that routes to the appropriate backend-specific variable, or document why this remains backend-specific.

---

Minor Issues & Suggestions

7. Pytest Configuration Comments

The pytest.ini file was updated correctly, but consider adding comments to explain why some variables remain KUZU_*:

# Backend-agnostic configuration
GRAPH_API_URL=http://localhost:8001
GRAPH_BACKUP_ENCRYPTION_KEY=test-encryption-key-dev

# Kuzu-specific configuration (when BACKEND_TYPE=kuzu)
KUZU_DATABASE_PATH=./data/kuzu-dbs
KUZU_MAX_DATABASES_PER_NODE=50

8. Potential Variable Name Collision

In robosystems/middleware/graph/allocation_manager.py:299, there's a local variable:

backend_type = tier_config.get("backend_type", "kuzu")

This shadows the field name in DatabaseLocation. While not a bug, using allocated_backend_type or tier_backend_type would be clearer.

9. Type Hints for Backend Type

The backend_type field uses str type. Consider using a typed enum:

from enum import Enum

class BackendType(str, Enum):
    KUZU = "kuzu"
    NEO4J_COMMUNITY = "neo4j_community"
    NEO4J_ENTERPRISE = "neo4j_enterprise"

# Then use:
backend_type: BackendType = BackendType.KUZU

This provides type safety and prevents typos.

10. Lock File Changes

The uv.lock file shows significant changes (+198/-197 lines). While this is expected when dependencies are updated, verify:

• Are these changes intentional or just lock file drift?
• Were any dependencies actually added/removed/updated as part of this refactoring?

If no intentional dependency changes were made, this might indicate the lock file was regenerated unnecessarily.

---

Testing Recommendations 🧪

1. Environment Variable Migration Tests: Add tests that verify old variable names no longer work (to prevent regressions).

2. Cross-Backend Configuration Tests: Verify that configuration correctly switches behavior based on BACKEND_TYPE setting.

3. DynamoDB Migration Test: Test that existing database allocations without backend_type field can be read successfully with the default value.

4. CloudFormation Stack Update Test: In staging, test updating an existing stack with the new secret key name to ensure smooth transition.

---

Security Considerations 🔒

No security issues identified. The refactoring maintains existing security patterns:

• ✅ Secrets continue to use get_secret_value() from AWS Secrets Manager
• ✅ Encryption key naming updated consistently
• ✅ No hardcoded credentials introduced
• ✅ API key handling remains unchanged

Note: The renaming of KUZU_BACKUP_ENCRYPTION_KEY to GRAPH_BACKUP_ENCRYPTION_KEY is consistent and properly propagated through all encryption modules.

---

Migration Checklist for Deployment 📋

Before merging and deploying, ensure:

• Update AWS Secrets Manager with new key names (GRAPH_API_KEY, GRAPH_BACKUP_ENCRYPTION_KEY)
• Update CI/CD pipelines to use new environment variable names
• Update deployment documentation with new variable names
• Update monitoring/alerting configurations that may reference old variable names
• Communicate breaking changes to team members and update local .env files
• Plan CloudFormation stack updates to handle secret key renaming
• Verify existing DynamoDB allocations work with new backend_type field
• Update infrastructure-as-code (Terraform, CDK, etc.) if used elsewhere

---

Performance Impact

No performance impact expected. This is a pure refactoring with:

• No algorithmic changes
• No new database queries
• No additional network calls
• Same configuration access patterns

---

Conclusion

This is a high-quality refactoring that successfully modernizes the environment variable naming scheme to support multi-backend architecture. The implementation is thorough, consistent, and well-tested.

Recommendation: ✅ Approve with minor fixes

Address the critical issues (#1-3) before merging, particularly:

1. Verify DynamoDB backward compatibility for existing allocations
2. Check for any remaining KUZU_* variables that should be renamed
3. Document the CloudFormation secret migration strategy

The medium and minor issues can be addressed in follow-up PRs if needed, but the critical issues should be resolved before deployment to production.

Great work on this comprehensive refactoring! 🎉

---

Job Run: https://github.com/RoboFinSystems/robosystems/actions/runs/${{ github.run_id }}
Branch: chore/rename-graph-env-vars

[chatgpt-codex-connector]

💡 Codex Review

robosystems/robosystems/config/validation.py

Lines 151 to 187 in 0404866

	def _validate_urls(env_config, errors: List[str]) -> None:
	"""Validate URL format for various endpoints."""
	url_vars = [
	"DATABASE_URL",
	"VALKEY_URL", # CELERY_BROKER_URL is now auto-constructed
	"KUZU_API_URL",
	]
	# Also validate CELERY_BROKER_URL if it's explicitly set
	if getattr(env_config, "CELERY_BROKER_URL", None):
	url_vars.append("CELERY_BROKER_URL")
	for var_name in url_vars:
	value = getattr(env_config, var_name, None)
	if value and not (
	value.startswith(
	(
	"http://",
	"https://",
	"redis://",
	"rediss://",
	"postgresql://",
	"postgres://",
	)
	)
	):
	errors.append(f"{var_name}: Invalid URL format - {value}")
	# Special validation for KUZU_API_URL
	# In production, this should NOT be explicitly set via environment variable
	# The factory handles dynamic endpoint selection based on the database
	# The default value in env.py is fine and will be ignored by the factory
	if var_name == "KUZU_API_URL" and env_config.ENVIRONMENT == "prod":
	import os
	# Only error if explicitly set via environment variable, not if using default
	if os.getenv("KUZU_API_URL"):

Production URL guard still tied to KUZU_API_URL

The URL validation routine continues to inspect KUZU_API_URL and the KUZU_API_URL environment variable when enforcing the “do not set an explicit API URL in prod” rule. After the rename, runtime code reads GRAPH_API_URL; therefore this check no longer runs and a manually configured GRAPH_API_URL in production will slip through without warnings, allowing deployments to bypass the intended dynamic endpoint discovery. Update the list and guard to use GRAPH_API_URL.

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting

• @codex fix this CI failure
• @codex address that feedback