diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..721104a --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,34 @@ +name: Bug report +description: Something in cc-framework is not behaving as documented. +title: "[bug]: " +labels: ["bug"] +body: + - type: textarea + id: what-happened + attributes: + label: What happened? + description: Describe the observed behavior and what you expected instead. + validations: + required: true + - type: textarea + id: repro + attributes: + label: Minimal reproduction + description: Include the smallest script, command, or dataset slice that reproduces the issue. + render: python + validations: + required: true + - type: input + id: version + attributes: + label: cc-framework version / commit + placeholder: "0.3.0-rc1 or git SHA" + validations: + required: true + - type: textarea + id: env + attributes: + label: Environment + description: Python version, OS, install command, and relevant dependency versions. + validations: + required: false diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..3a770b2 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,35 @@ +name: Feature request +description: Propose a focused addition or improvement. +title: "[feature]: " +labels: ["enhancement"] +body: + - type: textarea + id: problem + attributes: + label: Problem or workflow + description: What are you trying to do that cc-framework does not support well today? + validations: + required: true + - type: textarea + id: proposal + attributes: + label: Proposed change + description: Describe the smallest useful change and where it might live. + validations: + required: true + - type: textarea + id: alternatives + attributes: + label: Alternatives considered + description: Existing APIs, workarounds, or designs you have tried. + validations: + required: false + - type: checkboxes + id: compatibility + attributes: + label: Compatibility checks + options: + - label: This does not require deployment approval claims. + required: true + - label: This does not collide with the `Claim` envelope schema or established module namespaces. + required: true diff --git a/.github/ISSUE_TEMPLATE/research_question.yml b/.github/ISSUE_TEMPLATE/research_question.yml new file mode 100644 index 0000000..814da59 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/research_question.yml @@ -0,0 +1,33 @@ +name: Research question +description: Ask about the methodology, assumptions, or interpretation. +title: "[research]: " +labels: ["research-question"] +body: + - type: textarea + id: question + attributes: + label: Question + description: What part of the methodology, assumption set, bound, or interpretation is unclear? + validations: + required: true + - type: textarea + id: context + attributes: + label: Context + description: Link to the theorem, README section, code path, paper note, or example you are reading. + validations: + required: true + - type: textarea + id: attempted + attributes: + label: What you have already checked + description: Mention related docs, examples, or commands you ran. + validations: + required: false + - type: checkboxes + id: claim-discipline + attributes: + label: Claim discipline + options: + - label: I understand cc-framework bounds what the available evidence supports under stated assumptions; it does not certify a system is safe. + required: true diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..a1064dc --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,18 @@ +## What changed + +## Why + +## Verification performed + +- [ ] `make test-kernel` passes +- [ ] `make test-release` passes +- [ ] New/changed public API has a docstring and a working example + +## Compatibility check + +- [ ] No naming collision with the existing `Claim` envelope schema or other module namespaces +- [ ] No breaking change to public API without a version-bump note + +## Definition of Done reference + +Which item(s) from the Launch-Hardening Plan does this satisfy? diff --git a/CITATION.cff b/CITATION.cff new file mode 100644 index 0000000..27d0c81 --- /dev/null +++ b/CITATION.cff @@ -0,0 +1,28 @@ +cff-version: 1.2.0 +message: "If you use this software, please cite it using the metadata below." +title: "cc-framework" +abstract: > + Dependence-aware composition of AI guardrails: statistical bounds + (Frechet-Hoeffding), two-world evaluation protocols, and tamper-evident + audit evidence for stacked guardrail systems. This metadata does not imply + that the software certifies a system as safe; it bounds what the available + evidence supports under stated assumptions. +type: software +version: "0.3.0-rc1" +# date-released must be set to the actual release publication date. +# date-released: "YYYY-MM-DD" +# Drafted from git history for human confirmation before release. +authors: + - family-names: "Bhave" + given-names: "Pranav" +license: "MIT" +repository-code: "https://github.com/Cubits11/cc-framework" +keywords: + - ai-safety + - guardrails + - dependence-modeling + - uncertainty-quantification + - model-evaluation +# identifiers: +# - type: doi +# value: "10.5281/zenodo.XXXXXXX" diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..a740636 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,125 @@ +# 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, caste, color, 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 through the +maintainer contact listed on the Cubits11 GitHub profile. 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, version 2.1, +available at https://www.contributor-covenant.org/version/2/1/code_of_conduct.html. + +Community Impact Guidelines were inspired by Mozilla's code of conduct +enforcement ladder. + +For answers to common questions about this code of conduct, see +https://www.contributor-covenant.org/faq. Translations are available at +https://www.contributor-covenant.org/translations. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..164a312 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,65 @@ +# Contributing to CC-Framework + +Thanks for helping make CC-Framework easier to inspect, reproduce, and use. +This repository is research software, so contributions should keep claims +narrow: the package bounds what available evidence supports under stated +assumptions; it does not certify that a stacked system is safe. + +## Development setup + +Use Python 3.10 or newer. Python 3.12 is the primary local development target +in the current Makefile. + +```bash +python -m venv .venv +source .venv/bin/activate +python -m pip install -e ".[dev]" +``` + +Before opening a pull request, run the release-facing checks: + +```bash +make test-kernel +make test-release +``` + +As verified on 2026-07-01, `make test-kernel` runs the kernel unit tests, +strict mypy on `src/cc/kernel`, and ruff checks for the kernel surface. +`make test-release` runs that same gate plus the minimal bounds example and +release artifact integration tests. + +## Coding standards + +- Prefer the existing public kernel surface in `cc.kernel.strict` for + documentation and examples. +- Keep statistical claims tied to assumptions, evidence, and tests that are + checked in this repository. +- Add or update tests for changes to bound computation, witness construction, + metrics, serialization, or adapter behavior. +- Keep generated artifacts out of commits unless the file is explicitly part of + a documented release, paper, or launch asset. +- Do not introduce public language that implies deployment approval. + +## Pull request process + +1. Keep the PR focused on one reviewable change. +2. Include the commands you ran and their actual outcome. +3. Link any related issue or design note. +4. Call out compatibility risks, especially public API, schema, or artifact + format changes. +5. Wait for maintainer review before merge. + +## Adding a guardrail adapter + +Adapters should live under `src/cc/adapters/` unless an established module gives +a more specific home. A new adapter should include: + +- a small, typed interface that records per-item pass/fail outcomes; +- tests covering success, failure, malformed input, and empty input; +- a README or example if the adapter depends on a third-party tool; +- clear mapping from the external tool's result model to the repository + convention that `Z_i = 1` means guardrail failure / unsafe pass. + +Do not choose adapter names that collide with the existing `Claim` envelope +schema or other established module namespaces. If a proposed name is close to a +core schema, open a design issue before implementing it. diff --git a/README.md b/README.md index 487290f..63a3334 100644 --- a/README.md +++ b/README.md @@ -1,16 +1,54 @@ # CC-Framework -**Sharp partial-identification bounds for composed AI guardrail failures under unknown dependence.** +**Dependence-aware composition of AI guardrails: Frechet-Hoeffding bounds on +stacked-system failure, not a safety certification.** [![CI](https://github.com/Cubits11/cc-framework/actions/workflows/ci.yml/badge.svg)](https://github.com/Cubits11/cc-framework/actions/workflows/ci.yml) [![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) -![Status](https://img.shields.io/badge/status-research%20prototype-orange) + + -CC-Framework is research software for dependence-aware partial identification -of composed AI guardrail failures. It asks what a composed guardrail evaluation -actually identifies when singleton failure rates are observed but the joint -dependence structure is unknown or only partially constrained. +CC-Framework computes what available guardrail evidence supports under stated +dependence assumptions. It does not certify that a stacked system is safe. + +## 60-second quickstart + +```bash +python -m venv .venv +source .venv/bin/activate +python -m pip install -e ".[stats]" +python - <<'PY' +from cc.kernel.strict import frechet_bounds + +failure_rates = { + "input_filter": 0.10, + "policy_judge": 0.10, +} +bounds = frechet_bounds(list(failure_rates.values()), event="and") +independent = failure_rates["input_filter"] * failure_rates["policy_judge"] + +print(f"Stacked failure is bounded by [{bounds.lower:.2%}, {bounds.upper:.2%}]") +print(f"Independence would estimate {independent:.2%}") +PY +``` + +Expected output: + +```text +Stacked failure is bounded by [0.00%, 10.00%] +Independence would estimate 1.00% +``` + +For deeper context, start with the +[validation matrix](docs/validation_matrix.md), the +[finite-sample identification note](docs/theory/finite_sample_identification.md), +and the runnable [minimal example](examples/minimal/run_bounds.py). + +If you use this software, cite it with the metadata in +[CITATION.cff](CITATION.cff). Contributions should follow +[CONTRIBUTING.md](CONTRIBUTING.md). GitHub Discussions can be enabled from the +repository settings before launch. ## Research Status diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..49f5ac6 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,33 @@ +# Security Policy + +## Reporting a vulnerability + +Please do not report security vulnerabilities through public GitHub issues. + +If GitHub private vulnerability reporting is enabled for this repository, use +the repository's **Security** tab to open a private report. If that option is +not available, contact the maintainer through the public contact method listed +on the Cubits11 GitHub profile and include: + +- the affected commit, release, or package version; +- a minimal reproduction or proof of concept; +- expected impact and affected workflows; +- whether the vulnerability is already public. + +You should receive an initial acknowledgement within 7 days. The maintainer +will coordinate next steps, remediation, and disclosure timing based on impact. + +## Scope + +Security reports are appropriate for vulnerabilities in repository code, +release artifacts, example workflows, or integrity/audit evidence handling. + +Methodology questions, statistical disagreements, documentation issues, and +general feature requests should use the normal issue templates instead. + +## Current automation status + +Private vulnerability reporting could not be verified or enabled from the +2026-07-01 Codex hardening session because the local environment did not have +an authenticated GitHub CLI or token. A repository admin should verify this in +GitHub settings before launch. diff --git a/docs/assets/social-preview.png b/docs/assets/social-preview.png new file mode 100644 index 0000000..b56e5d6 Binary files /dev/null and b/docs/assets/social-preview.png differ