cngx 0.1.0__tar.gz

cngx-0.1.0/.dockerignore

@@ -0,0 +1,31 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.eggs/
+
+# Environments
+.env
+.venv/
+venv/
+
+# IDE
+.vscode/
+.idea/
+
+# Data (don't ship databases)
+*.db
+*.duckdb
+/data/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Test / CI
+.pytest_cache/
+htmlcov/
+.coverage
+.cngx/

cngx-0.1.0/.env.example

@@ -0,0 +1,20 @@
+# ─────────────────────────────────────────────
+# cngx Environment Variables
+# Copy this file to .env and fill in your values
+# ─────────────────────────────────────────────
+
+# ── LLM Provider API Keys ──
+# At least one is required for live testing.
+# Mock adapter works without any keys.
+GOOGLE_API_KEY=
+OPENAI_API_KEY=
+ANTHROPIC_API_KEY=
+
+# ── Server (optional self-hosted UI) ──
+CNGX_HOST=0.0.0.0
+CNGX_PORT=8642
+CNGX_SECRET_KEY=change-me-to-a-random-secret
+
+# ── Optional ──
+CNGX_LOG_LEVEL=INFO
+CNGX_STORAGE_DIR=.cngx

cngx-0.1.0/.gitignore

@@ -0,0 +1,46 @@
+# Python bytecode and caches
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+.eggs/
+dist/
+build/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+.venv-pyinstaller/
+env/
+
+# Test and type checker caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Secrets and local runtime data
+.env
+.cngx/
+.cogscope/
+
+# Generated documentation and tracker site
+site/
+tracker/site/index.html
+tracker/site/data.js
+tracker/site/site.css
+tracker/site/app.js
+tracker/site/docs.js
+tracker/site/docs/
+tracker/screenshots/
+
+# VHS tooling (MSVC ttyd binaries, not committed)
+.vhs-tools/
+
+# IDE and OS
+.vscode/
+.idea/
+.DS_Store
+Thumbs.db

cngx-0.1.0/CHANGELOG.md

@@ -0,0 +1,78 @@
+# Changelog
+
+All notable changes to cngx will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-07-06
+
+### Changed
+- **Fresh public relaunch** under the name **cngx** (renamed from the private `rvc` package).
+- Prior GitHub and PyPI name was **cogscope**; releases now ship as **cngx**.
+- **Version reset to 0.1.0**, new version scheme for the open-source developer tool; supersedes the prior 1.0.0/2.0.0 mismatch in the private tree.
+- Enterprise/SaaS surfaces (`platform/`, `cloud/`, `sdk/`, `rvc-demo/`, `rvc-prod/`) moved to `_archive_pre_oss/`.
+- Phase-2 modules (correctness, robustness, governance, benchmarks, etc.) archived for future releases.
+
+### Removed
+- Cloud platform CLI commands, enterprise SDK tests, and multi-service `docker-compose.yml` from the public tree.
+
+## [1.0.0] - 2026-02-11
+
+### Added
+- **Claude/Anthropic adapter**, full support for Claude Opus, Sonnet, Haiku (3, 3.5, 4) with extended thinking extraction
+- **RBAC role system**, admin, member, viewer roles with scope-based enforcement
+- **Webhook notifications**, real-time alerts on gate blocks, drift detection, contract violations
+- **Batch enforcement API**, validate multiple prompts/fingerprints in a single API call
+- **Structured JSON logging**, production-grade log output with correlation IDs, compatible with ELK/Datadog
+- **Prometheus metrics**, `/metrics` endpoint with enforcement counters, latency histograms, active org gauges
+- **PostgreSQL support**, cloud database can use PostgreSQL for horizontal scaling via `CNGX_DATABASE_URL`
+- **Streaming capture**, capture reasoning traces from streaming LLM responses
+- **GitHub Actions CI/CD**, automated testing, linting, and PyPI publishing on release
+- **MkDocs documentation site**, comprehensive docs with tutorials, API reference, contract authoring guide
+- **LICENSE file** (MIT)
+- **CHANGELOG.md**
+- **CONTRIBUTING.md**
+
+### Changed
+- **Version bumped to 1.0.0**, production-ready release
+- **Cloud auth hardened**, API keys removed from query strings, secure cookie-based web UI auth
+- **Rate limiter**, configurable per org plan tier (free: 100/min, team: 500/min, enterprise: 2000/min)
+- **pyproject.toml**, updated with all new optional dependencies, proper classifiers
+- **CLI error handling**, all commands wrapped with structured error reporting
+
+### Fixed
+- API key revoke now uses correct `AuditAction.API_KEY_REVOKE` instead of reusing `API_KEY_CREATE`
+- Cloud login page now uses Jinja2 template instead of inline HTML
+- Adapters `__init__.py` exports all adapters (was missing GeminiAdapter)
+- Circuit breaker in SDK client is now class-level (shared across instances)
+
+### Security
+- ReDoS regex sandbox hardened with additional pattern detection
+- API keys never appear in server logs or query strings
+- Web UI auth uses HttpOnly secure cookies instead of URL parameters
+- TLS enforcement flag added to cloud server config
+
+## [0.2.0] - 2025-12-01
+
+### Added
+- Cloud platform (multi-tenant SaaS)
+- Contract enforcement engine
+- Behavioral fingerprinting (30+ metrics)
+- DuckDB storage
+- OpenAI and Gemini adapters
+- CLI with gate, capture, diff, drift, eval, pin commands
+- System demo module
+- Cross-model validation
+- Calibration profiles for 12 model families
+- Explainability engine
+- Remediation engine
+
+## [0.1.0] - 2025-09-01
+
+### Added
+- Initial release
+- Core reasoning trace capture
+- Basic fingerprinting
+- Diff engine
+- CLI scaffolding

cngx-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,130 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement by opening a
+private GitHub Security Advisory on this repository, or by contacting
+[@aadi-joshi](https://github.com/aadi-joshi) directly via GitHub.
+
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact:** Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence:** A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact:** A violation through a single incident or series
+of actions.
+
+**Consequence:** A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or
+permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact:** A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence:** A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact:** Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior,  harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence:** A permanent ban from any sort of public interaction within
+the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.0, available at
+https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct
+enforcement ladder](https://github.com/mozilla/diversity).
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq. Translations are available at
+https://www.contributor-covenant.org/translations.

cngx-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,165 @@
+# Contributing to cngx
+
+Thank you for helping improve cngx. This guide covers local development, code style, and how to extend the project.
+
+## Development setup
+
+### Prerequisites
+
+- Python 3.10+
+- Git
+
+### Local install
+
+```bash
+git clone https://github.com/aadi-joshi/cngx.git
+cd cngx
+
+python -m venv .venv
+# Windows: .venv\Scripts\activate
+# macOS/Linux: source .venv/bin/activate
+
+pip install -e ".[dev]"
+```
+
+Optional provider extras (only if you are working on or testing that adapter):
+
+```bash
+pip install -e ".[dev,gemini]"   # Google Gemini
+pip install -e ".[dev,claude]"   # Anthropic Claude
+```
+
+### Run tests
+
+```bash
+pytest                    # full suite
+pytest tests/unit/ -q     # unit tests only
+pytest tests/unit/test_drift_alerting.py -v   # statistical alerting tests
+```
+
+### Lint and format
+
+The repo uses **Ruff** (lint + isort), **Black** (format), and **mypy** (types). Config lives in `pyproject.toml`.
+
+```bash
+ruff check .
+black --check .
+mypy cngx/
+```
+
+Auto-format before committing:
+
+```bash
+ruff check --fix .
+black .
+```
+
+Optional: `pre-commit install` if you use pre-commit hooks locally.
+
+## Project layout (active OSS tree)
+
+```
+cngx/
+├── capture/        # Tracing and LLM adapters
+├── proxy/          # Local ASGI reverse proxy
+├── tui/            # Live terminal dashboard
+├── fingerprint/    # Metric extraction (see metrics.py)
+├── diff/           # Trace/fingerprint comparison
+├── drift/          # Baseline-relative drift detection
+├── calibration/    # Model profiles and adaptive thresholds
+├── contracts/      # Behavior policies (YAML) and validation
+├── versioning/     # Baseline pinning
+├── storage/        # Local DuckDB
+├── cli/            # Typer CLI entry points
+└── system_demo/    # Reference pipeline scenarios
+```
+
+Hosted SaaS and marketing-site code from earlier development is **not** in this repository and is out of scope for new contributions.
+
+## Proposing a new behavioral metric
+
+1. Read `cngx/fingerprint/metrics.py`, `MetricsCalculator` holds regex patterns and counting logic for each signal.
+2. Add your metric computation there (keep it fast and deterministic; prefer explicit patterns over NLP).
+3. Wire the new field through `cngx/fingerprint/extractor.py` into `BehavioralFingerprint` in `cngx/core/models.py` if it is a new top-level metric.
+4. If the metric should influence drift alerting, update `cngx/calibration/profiles.py` (`QUALITY_METRICS` / `LENGTH_METRICS`) and review `cngx/drift/detector.py`.
+5. Add unit tests in `tests/unit/test_metrics.py` or `tests/unit/test_fingerprint.py` with a minimal synthetic trace.
+
+Design note: metrics are heuristics. Document what each pattern captures and what it will miss.
+
+## Adding a new LLM provider adapter
+
+1. Create `cngx/capture/adapters/your_provider.py`.
+2. Subclass `BaseAdapter` in `cngx/capture/adapters/base.py` and implement:
+   - `async def call(...)`, primary async entry point
+   - `def call_sync(...)`, synchronous wrapper (often `asyncio.run` or shared core)
+   - Streaming via `StreamChunk` if the provider supports it
+3. Register the adapter in `cngx/capture/adapters/__init__.py` and in `CngxTracer`’s adapter map (`cngx/capture/tracer.py`).
+4. Add routing in `cngx/proxy/app.py` if the proxy should forward that provider’s API shape.
+5. Add a model profile stub in `cngx/calibration/profiles.py` if the family has distinct baseline behavior.
+6. Add optional dependency in `pyproject.toml` under `[project.optional-dependencies]`.
+7. Add tests in `tests/unit/` with mocked HTTP or the `mock` adapter pattern; skip live tests when API keys are absent.
+
+Never log or persist API keys. Read them from environment variables only.
+
+## Pull requests
+
+1. Open an issue or discussion for large changes before investing heavily.
+2. Fork, branch from `main` (or the active launch branch), keep PRs focused.
+3. Include tests for behavior changes.
+4. Run `pytest`, `ruff check .`, `black --check .`, and `mypy cngx/` before opening the PR.
+5. Use clear commit messages (`feat:`, `fix:`, `docs:`, etc.).
+6. Fill out the PR template; link related issues.
+
+Maintainers review for correctness, test coverage, user-facing clarity (plain language in CLI/docs), and whether new metrics respect the statistical alerting design (no single-metric or length-only false alarms).
+
+## Reporting bugs and suggesting features
+
+- **Bugs:** use the [bug report template](.github/ISSUE_TEMPLATE/bug_report.md).
+- **Features:** use the [feature request template](.github/ISSUE_TEMPLATE/feature_request.md).
+
+## CI integration and README badge
+
+**GitHub Action:** add `uses: aadi-joshi/cngx@v0.1.0` to your workflow. See [docs/guides/github-action.md](docs/guides/github-action.md).
+
+**README badge** (shields.io):
+
+```markdown
+[![Monitored by cngx](https://img.shields.io/badge/Monitored%20by-cngx-22c55e?style=flat-square)](https://github.com/aadi-joshi/cngx)
+```
+
+More options: [docs/guides/badge.md](docs/guides/badge.md).
+
+Local smoke test for the action logic:
+
+```bash
+python scripts/test_github_action_local.py
+```
+
+## Demo assets (dev tooling only)
+
+Regenerate README/docs media with scripts under `scripts/demo/`. See `scripts/demo/README.md`.
+
+Terminal quickstart GIF:
+
+```bash
+vhs scripts/demo/quickstart.tape
+```
+
+Tracker site recording:
+
+```bash
+pip install -e ".[dev]"
+playwright install chromium
+python scripts/demo/record_tracker.py
+```
+
+Playwright is listed under `[project.optional-dependencies] dev` only, not in runtime dependencies.
+
+
+## Code of conduct
+
+This project follows the [Contributor Covenant](CODE_OF_CONDUCT.md). Be respectful and constructive.
+
+## License
+
+By contributing, you agree your contributions are licensed under the MIT License.

cngx-0.1.0/Dockerfile

@@ -0,0 +1,44 @@
+# cngx local proxy, optional container for home server / VPS
+#
+# Runs the ASGI reverse proxy only (not a multi-service SaaS stack).
+# Forwards LLM traffic, fingerprints on the side. API keys via env at runtime.
+#
+# Build:  docker build -t cngx-proxy .
+# Run:    docker run -p 8642:8642 -e OPENAI_API_KEY=sk-... cngx-proxy
+#
+# See README.md and SECURITY.md for key handling (memory only, never logged).
+
+FROM python:3.11-slim AS builder
+
+WORKDIR /build
+RUN pip install --no-cache-dir hatchling
+COPY pyproject.toml README.md LICENSE ./
+COPY cngx/ cngx/
+RUN pip wheel --no-deps --wheel-dir /wheels .
+
+FROM python:3.11-slim
+
+LABEL maintainer="cngx Contributors"
+LABEL description="cngx local LLM proxy with behavioral fingerprinting"
+LABEL version="0.1.0"
+
+RUN groupadd -r cngx && useradd -r -g cngx -d /app -s /sbin/nologin cngx
+
+WORKDIR /app
+COPY --from=builder /wheels /wheels
+RUN pip install --no-cache-dir /wheels/*.whl && rm -rf /wheels
+
+RUN mkdir -p /data/.cngx && chown -R cngx:cngx /data
+USER cngx
+
+ENV CNGX_STORAGE_DIR=/data/.cngx
+ENV CNGX_PROXY_HOST=0.0.0.0
+ENV CNGX_PROXY_PORT=8642
+ENV PYTHONUNBUFFERED=1
+
+EXPOSE 8642
+
+HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
+    CMD python -c "import httpx; httpx.get('http://127.0.0.1:8642/health').raise_for_status()" || exit 1
+
+CMD ["uvicorn", "cngx.proxy.app:app", "--host", "0.0.0.0", "--port", "8642"]

cngx-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 aadi-joshi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cngx-0.1.0/Makefile

@@ -0,0 +1,70 @@
+.PHONY: help install dev test lint format build publish clean docker docs demo
+
+help: ## Show this help
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | \
+		awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-20s\033[0m %s\n", $$1, $$2}'
+
+install: ## Install cngx (core only)
+	pip install -e .
+
+dev: ## Install cngx with all dev dependencies
+	pip install -e ".[all,dev,docs]"
+
+test: ## Run all tests (no API keys needed)
+	python -m pytest tests/ -v --noconftest -x
+
+test-unit: ## Run unit tests only
+	python -m pytest tests/unit/ -v --noconftest
+
+test-integration: ## Run integration tests
+	python tests/integration/test_e2e_pipeline.py
+
+test-coverage: ## Run tests with coverage report
+	python -m pytest tests/ --noconftest --cov=cngx --cov-report=html --cov-report=term
+
+lint: ## Run linters (ruff)
+	ruff check cngx/ tests/
+	ruff format --check cngx/ tests/
+
+format: ## Auto-format code
+	ruff format cngx/ tests/
+	ruff check --fix cngx/ tests/
+
+typecheck: ## Run type checker
+	mypy cngx/ --ignore-missing-imports
+
+build: ## Build package
+	python -m build
+
+publish: ## Publish to PyPI (requires credentials)
+	python -m build
+	twine upload dist/*
+
+clean: ## Remove build artifacts
+	rm -rf build/ dist/ *.egg-info .cngx/ htmlcov/ .coverage
+	find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true
+	find . -type f -name "*.pyc" -delete 2>/dev/null || true
+
+docker: ## Build Docker image
+	docker build -t cngx:latest .
+
+docs: ## Build documentation site
+	mkdocs build
+
+docs-serve: ## Serve docs locally
+	mkdocs serve
+
+demo: ## Run the full system demo (no API keys needed)
+	python examples/basic_usage.py
+
+demo-e2e: ## Run integration pipeline tests
+	python -m pytest tests/integration/test_full_pipeline.py -v
+
+gate-mock: ## Run a sample gate check with mock adapter
+	cngx gate check "Solve x^2 + 5x + 6 = 0" \
+		--contract contracts/math_correctness.yaml \
+		--adapter mock \
+		--model mock-model
+
+version: ## Show cngx version
+	cngx version