Sukriti Chatterjee | Senior Architect

About / Description: Zero-dependency Python compiler that validates, translates, and syncs configs between JSON, YAML, and TOML with graph cycle detection.

Problem Statement

DevOps and software engineering teams frequently manage environment configurations fragmented across JSON, YAML, TOML, and .env files. Manual conversion and standard naive parsers lack strict type preservation, fail to catch runtime schema violations prior to deployment, and choke on dynamic variable references—causing silent failures, unhandled exceptions, or infinite recursion loops during deployment.

Solution Objective

Build a zero-dependency Python 3.10+ configuration compiler that ingests multi-format configurations, parses them into a unified In-Memory Abstract Syntax Tree (IR AST), validates structural types/schemas, resolves dynamic variable interpolations using $O(V + E)$ Directed Acyclic Graph (DAG) cycle detection, and emits lossless target configurations (JSON, YAML, TOML) with sub-millisecond compilation speed.

Architecture Overview

Architecture Diagram

Here's how PolyConfig fits into a four-environment enterprise GitOps/CI-CD architecture.

In modern enterprise setups, separating application source code from configuration files is standard practice (often called Config/GitOps Repositories). polyconfig acts as a unified compilation step between your configuration repositories and deployment targets:

Input Stage: Ingests raw JSON, YAML, or TOML configuration files.
IR AST Generation: Parses heterogeneous inputs into a strongly-typed In-Memory Abstract Syntax Tree.
Validation & Resolution: Executes DFS cycle detection ($O(V+E)$) for variables, validates schema constraints, and resolves environment variable overrides.
Emitter: Generates lossless, byte-for-byte deterministic config files for your infrastructure.

Tech Stack

Python 3.10+ Standard Library (json, tomllib, typing, dataclasses, re, argparse), zero external dependencies.

📊 Performance & System Bounds

Metric	Target / Benchmark	Technical Mechanic
Parsing Throughput	< 2.5 ms for 5,000-line configs	Compiled pattern matching & single-pass AST construction
Cycle Detection Complexity	$O(V + E)$ execution time	In-memory adjacency matrix with recursive DFS stack tracking
Runtime RAM Ceiling	< 15 MB RSS peak memory usage	Minimal memory footprint using Python `__slots__` on AST nodes
Dependencies	0 External Packages	Standard Library native execution (`json`, `tomllib`, `re`)

Recent Core Improvements

Env-Aware Cycle Detection: DFS cycle detection now recursively traces variables supplied via environment overrides, preventing hidden cycles.
Strict Type Validation: Python's native bool class overlapping with int has been strictly isolated, ensuring boolean values cannot masquerade as integers during JSON Schema validation.
Infinite Loop Safeguards: Variable interpolation features a max-depth safeguard, automatically breaking and raising a ResolutionError to prevent CI/CD runners from hanging on undetected loops.
Deterministic Array Merging: Configured to cleanly replace, rather than unpredictably append, list items during cross-format deep merges.

Setup

Prerequisites

Python 3.10+
Zero external dependencies (relies entirely on the Python Standard Library).

Installation

Clone the repository and install it locally:

git clone https://github.com/SukritiC/Poly-Config
cd Poly-Config

# (Optional) Create and activate a virtual environment
python3 -m venv venv
source venv/bin/activate

# Install the CLI tool
pip install -e .

Usage & Testing

Basic Usage

Convert and validate a configuration file from YAML to JSON, seamlessly resolving environment variables (e.g., ${ENV} and ${DB_HOST}):

ENV=production DB_HOST=db.example.com DB_PASSWORD=secret \
python3 -m polyconfig build config/sample.yaml --format json --output build/sample.json

Note on Strict Resolution: PolyConfig enforces strict variable interpolation by default. If a required variable like ${ENV} is not provided in the environment, the compiler will safely abort with a PolyConfig Error: Variable 'ENV' is not defined. to prevent misconfigured deployments.

Schema Validation

Pass a schema definition file to strictly validate structural types before compilation:

ENV=production DB_HOST=db.example.com DB_PASSWORD=secret \
python3 -m polyconfig build config/sample.toml \
    --format json \
    --output build/compiled_sample.json \
    --schema config/schema.json

Strict Mode & Sanitization

Run validation in strict mode and sanitize secrets for an audit-safe preview:

ENV=production DB_HOST=db.example.com DB_PASSWORD=secret \
python3 -m polyconfig build config/sample.toml \
    --strict \
    --sanitize \
    --format toml \
    --output build/public_preview.toml

Running Tests

The test suite is built using the standard library unittest framework:

# Run the complete test suite
python3 -m unittest discover tests/ -v

🤝 Contributing

We welcome contributions! If you have suggestions for improvements, found a bug, or want to add support for a new browser:

Fork the repository
Create your feature branch (git checkout -b feature/AmazingFeature)
Commit your changes (git commit -m 'Add some AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
Open a Pull Request

🚀 Check Out TBRly!

	If you appreciate tools like ZeroTab that streamline your workflow and boost productivity, you'll love TBRly! It's our product built for professionals who want to organize and reclaim their time.
	🔗 Visit the TBRly Website 📺 Watch the TBRly YouTube Demo

🤝 Share the Knowledge

Found these notes helpful?
Feel free to share them with your peers, friends, or anyone in your learning circle who might benefit from them. Learning is better when it’s collaborative!

⚠️ Please note: These notes are shared under the Apache License 2.0. While you're welcome to use, modify, and share them, make sure to provide proper credit and include the original license file if you redistribute or adapt the content.