nirizan 0.1.0__tar.gz

nirizan-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,76 @@
+name: Bug Report
+description: Something isn't working the way docs/contracts.md or docs/architecture.md says it should.
+title: "[Bug]: "
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for reporting a bug. Phases 1-5 are implemented and CI-tested; if you're on a later phase, check CONTRIBUTING.md first since that component may be early or not-yet-built work.
+
+  - type: dropdown
+    id: phase
+    attributes:
+      label: Which phase does this affect?
+      description: See CONTRIBUTING.md if you're unsure which phase a component belongs to.
+      options:
+        - "Phase 1: Instrumentation & Trace Storage"
+        - "Phase 2: RAG Triad Metrics"
+        - "Phase 3: Experiment Tracking & Baselines"
+        - "Phase 4: Regression Detection & CI Gate"
+        - "Phase 5: Drift & Judge-Reliability Layer"
+        - "Phase 6: Evaluation Ablation & Benchmarking"
+        - Not sure / spans multiple phases
+    validations:
+      required: true
+
+  - type: input
+    id: component
+    attributes:
+      label: Component or file
+      description: e.g. instrumentation/tracer.py, metrics/rag_triad.py
+      placeholder: src/nirizan/...
+    validations:
+      required: false
+
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened?
+      description: What did you expect instead? Include the exact error message if there is one.
+    validations:
+      required: true
+
+  - type: textarea
+    id: repro
+    attributes:
+      label: Steps to reproduce
+      description: Minimal steps, or a minimal code snippet, that reproduces the issue.
+      render: python
+    validations:
+      required: false
+
+  - type: input
+    id: version
+    attributes:
+      label: NiriZan version or commit
+      placeholder: e.g. 0.1.0, or a git commit hash
+    validations:
+      required: false
+
+  - type: input
+    id: python-version
+    attributes:
+      label: Python version
+      placeholder: "3.11 or later (per pyproject.toml)"
+    validations:
+      required: false
+
+  - type: checkboxes
+    id: terms
+    attributes:
+      label: Code of Conduct
+      description: By submitting this issue, you agree to follow this project's [Code of Conduct](../../CODE_OF_CONDUCT.md).
+      options:
+        - label: I agree to follow this project's Code of Conduct.
+          required: true

nirizan-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Security Vulnerability Report
+    url: https://github.com/Red1-Rahman/NiriZan/security/advisories/new
+    about: Do not open a public issue for security vulnerabilities. See SECURITY.md and report privately instead.
+  - name: General Question
+    url: https://github.com/Red1-Rahman/NiriZan/discussions
+    about: Ask a usage or design question that isn't a bug, feature request, or contract change.

nirizan-0.1.0/.github/ISSUE_TEMPLATE/contract_change.yml

@@ -0,0 +1,89 @@
+name: Contract Change
+description: Propose adding to or modifying a data model or interface defined in docs/contracts.md.
+title: "[Contract]: "
+labels: ["contract-change"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        `docs/contracts.md` is the single source of truth for every pydantic model and plugin interface NiriZan's components agree on. Per CONTRIBUTING.md, a contract change is discussed and merged on its own, before any implementation PR that depends on it. This form is for proposing that discussion, not for shipping an implementation directly.
+
+        Note: `JudgeReliabilityMetrics` and `DashboardSnapshot` (Phase 5, `reporting/`) currently ship without a corresponding entry here, a known, tracked documentation gap, not an example to follow. A Contract Change issue backfilling those two is itself a welcome first contribution.
+
+  - type: input
+    id: contract-name
+    attributes:
+      label: Which contract does this affect?
+      description: Name the exact model, protocol, or interface (e.g. Span, MetricResult, RegressionVerdict).
+      placeholder: e.g. Span, Trace, Metric, RegressionVerdict, AttributionVerdict, JudgeReliabilityMetrics, DashboardSnapshot
+    validations:
+      required: true
+
+  - type: dropdown
+    id: phase
+    attributes:
+      label: Which phase's contracts does this belong to?
+      options:
+        - "Phase 1: Instrumentation & Trace Storage"
+        - "Phase 2: RAG Triad Metrics"
+        - "Phase 3: Experiment Tracking & Baselines"
+        - "Phase 4: Regression Detection & CI Gate"
+        - "Phase 5: Drift & Judge-Reliability Layer"
+        - "Phase 6: Evaluation Ablation & Benchmarking"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: change-type
+    attributes:
+      label: Is this additive or breaking?
+      description: Per the Versioning Rule at the end of docs/contracts.md. Additive means a new optional field with a default. Breaking means anything else (removed field, changed meaning, narrowed type).
+      options:
+        - Additive (new optional field with a default value)
+        - Breaking (removed field, changed meaning, or narrowed type)
+        - Not sure
+    validations:
+      required: true
+
+  - type: textarea
+    id: current-shape
+    attributes:
+      label: Current contract (if modifying an existing one)
+      description: Paste the relevant model or protocol as it exists today in docs/contracts.md. If it's implemented in src/ but not yet documented here (see the note above), paste the real src/ definition instead and say so.
+      render: python
+    validations:
+      required: false
+
+  - type: textarea
+    id: proposed-shape
+    attributes:
+      label: Proposed contract
+      description: The new or changed model/protocol definition, in the same style as docs/contracts.md.
+      render: python
+    validations:
+      required: true
+
+  - type: textarea
+    id: rationale
+    attributes:
+      label: Why is this needed?
+      description: What does the current contract get wrong or fail to support?
+    validations:
+      required: true
+
+  - type: textarea
+    id: migration
+    attributes:
+      label: Migration path (required if breaking)
+      description: If this is a breaking change, describe how any already-persisted data using the old shape would be migrated.
+    validations:
+      required: false
+
+  - type: checkboxes
+    id: terms
+    attributes:
+      label: Code of Conduct
+      description: By submitting this issue, you agree to follow this project's [Code of Conduct](../../CODE_OF_CONDUCT.md).
+      options:
+        - label: I agree to follow this project's Code of Conduct.
+          required: true

nirizan-0.1.0/.github/ISSUE_TEMPLATE/documentation.yml

@@ -0,0 +1,50 @@
+name: Documentation
+description: Report an issue with, or propose an improvement to, NiriZan's documentation.
+title: "[Docs]: "
+labels: ["documentation"]
+body:
+  - type: dropdown
+    id: doc-area
+    attributes:
+      label: Which document does this concern?
+      options:
+        - README.md
+        - CONTRIBUTING.md
+        - SECURITY.md
+        - CODE_OF_CONDUCT.md
+        - CODE_OF_ETHICS.md
+        - docs/architecture.md
+        - docs/contracts.md
+        - docs/literature-review.md
+        - docs/modules/ (per-package reference docs)
+        - docs/governance/DATA_POLICY.md
+        - docs/governance/KPI-Definitions.md
+        - docs/standards/ (ISO-IEC-IEEE, Washington-Accord, EUR-ACE, UN-SDG)
+        - Something else / not listed
+    validations:
+      required: true
+
+  - type: textarea
+    id: issue
+    attributes:
+      label: What's wrong, missing, or unclear?
+      description: Quote the specific section if possible.
+    validations:
+      required: true
+
+  - type: textarea
+    id: suggestion
+    attributes:
+      label: Suggested fix
+      description: If you have a specific rewording or addition in mind, share it here.
+    validations:
+      required: false
+
+  - type: checkboxes
+    id: terms
+    attributes:
+      label: Code of Conduct
+      description: By submitting this issue, you agree to follow this project's [Code of Conduct](../../CODE_OF_CONDUCT.md).
+      options:
+        - label: I agree to follow this project's Code of Conduct.
+          required: true

nirizan-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,67 @@
+name: Feature Request
+description: Propose a new capability, metric, or improvement for NiriZan.
+title: "[Feature]: "
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Before proposing new work, check `docs/architecture.md` and `docs/contracts.md`: if what you're proposing isn't reflected in either, that's worth flagging explicitly rather than assuming it fits.
+
+  - type: dropdown
+    id: phase
+    attributes:
+      label: Which phase does this belong to?
+      description: Prefer proposing work for the current phase (6) or closing a known gap in Phases 1-5 over jumping ahead. If this is a later-phase idea (Phase 7+), say so explicitly.
+      options:
+        - "Phase 1: Instrumentation & Trace Storage"
+        - "Phase 2: RAG Triad Metrics"
+        - "Phase 3: Experiment Tracking & Baselines"
+        - "Phase 4: Regression Detection & CI Gate"
+        - "Phase 5: Drift & Judge-Reliability Layer"
+        - "Phase 6: Evaluation Ablation & Benchmarking"
+        - Beyond the current roadmap / future work
+    validations:
+      required: true
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: What problem does this solve?
+      description: Describe the gap or limitation this addresses. Reference a specific section of docs/architecture.md or docs/literature-review.md if relevant.
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+      description: What would you build? If this touches a data model or interface, name it explicitly.
+    validations:
+      required: true
+
+  - type: checkboxes
+    id: contract-impact
+    attributes:
+      label: Contract impact
+      description: Does this require changing anything in docs/contracts.md?
+      options:
+        - label: This requires a new or changed contract in docs/contracts.md (consider using the Contract Change template instead).
+          required: false
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Any other approaches you considered and why you didn't propose them instead.
+    validations:
+      required: false
+
+  - type: checkboxes
+    id: terms
+    attributes:
+      label: Code of Conduct
+      description: By submitting this issue, you agree to follow this project's [Code of Conduct](../../CODE_OF_CONDUCT.md).
+      options:
+        - label: I agree to follow this project's Code of Conduct.
+          required: true

nirizan-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,78 @@
+<!--
+Thanks for opening a PR. Phases 1-5 are implemented and CI-enforced;
+Phase 6 (evaluation & benchmarking) is in progress. Please fill in every
+section below rather than deleting what doesn't seem to apply; "N/A" is a
+valid answer.
+-->
+
+## Summary
+
+<!-- What does this PR do, in a sentence or two? -->
+
+## Which phase does this belong to?
+
+<!-- Match the issue templates' phase options. Pick one. -->
+
+- [ ] Phase 1: Instrumentation & Trace Storage
+- [ ] Phase 2: RAG Triad Metrics
+- [ ] Phase 3: Experiment Tracking & Baselines
+- [ ] Phase 4: Regression Detection & CI Gate
+- [ ] Phase 5: Drift & Judge-Reliability Layer
+- [ ] Phase 6: Evaluation Ablation & Benchmarking
+- [ ] Not phase-specific (docs, tooling, dependency update, etc.)
+
+## Related issue(s)
+
+<!-- Link the issue(s) this PR closes or addresses, e.g. "Closes #12". -->
+
+## Contract impact
+
+<!--
+Per docs/contracts.md and CONTRIBUTING.md: a change to any pydantic model
+or plugin interface in docs/contracts.md is discussed and approved via a
+Contract Change issue BEFORE the implementation PR, not alongside it. Note:
+JudgeReliabilityMetrics and DashboardSnapshot currently ship without a
+docs/contracts.md entry, a known, tracked gap; don't treat their existing
+shape as precedent for skipping this process on new work.
+-->
+
+- [ ] This PR does **not** touch `docs/contracts.md`.
+- [ ] This PR **does** touch `docs/contracts.md`, and the change was discussed and approved in Contract Change issue: #____
+
+<!--
+If this PR touches docs/contracts.md and there is no linked, approved
+Contract Change issue, expect this PR to be asked to split into a
+contract-change discussion first, per the process in CONTRIBUTING.md.
+-->
+
+## Import direction
+
+<!-- Per docs/import-boundaries.md. -->
+
+- [ ] I did not add any new cross-module imports.
+- [ ] I added new cross-module import(s), and they follow the layer direction in `docs/import-boundaries.md` (`instrumentation → orchestrator → metrics → trust → storage → regression → gate → reporting`).
+
+## Local checks
+
+<!--
+CI enforcement for human-authored PRs is not wired up yet. Until it is,
+please confirm you've run these locally.
+-->
+
+- [ ] `pytest` passes
+- [ ] `mypy --strict` passes
+- [ ] `lint-imports` passes
+
+## Contact (optional)
+
+<!--
+Optional. Leave blank if you'd rather not share it. If provided, this may
+be used to reach out about this PR specifically (e.g. follow-up questions,
+or potential paid/contract work related to this contribution).
+-->
+
+Email: ____
+
+## Anything reviewers should look at closely?
+
+<!-- Optional: tricky edge cases, deliberate tradeoffs, things you're unsure about. -->

nirizan-0.1.0/.github/dependabot.yml

@@ -0,0 +1,34 @@
+version: 2
+
+updates:
+  # Python dependencies declared in pyproject.toml.
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    open-pull-requests-limit: 10
+    groups:
+      python-patch-and-minor:
+        update-types:
+          - "patch"
+          - "minor"
+    labels:
+      - "dependencies"
+      - "python"
+
+  # GitHub Actions used in .github/workflows/
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    open-pull-requests-limit: 10
+    groups:
+      actions-patch-and-minor:
+        update-types:
+          - "patch"
+          - "minor"
+    labels:
+      - "dependencies"
+      - "github-actions"

nirizan-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,34 @@
+name: CI
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+    branches: ["main"]
+
+permissions:
+  contents: read
+
+jobs:
+  checks:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+
+      - name: Install project with dev dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Run pytest
+        run: pytest
+
+      - name: Run mypy --strict
+        run: mypy
+
+      - name: Run import-linter (layer contract)
+        run: lint-imports

nirizan-0.1.0/.github/workflows/cross-platform.yml

@@ -0,0 +1,54 @@
+name: Cross-platform
+
+on:
+  push:
+    branches: ["main"]
+    tags: ["v*"]
+
+  pull_request:
+    branches: ["main"]
+
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  smoke-test:
+    name: ${{ matrix.os }} • Python ${{ matrix.python-version }}
+    runs-on: ${{ matrix.os }}
+
+    strategy:
+      fail-fast: false
+      matrix:
+        os:
+          - ubuntu-latest
+          - windows-latest
+          - macos-latest
+        python-version:
+          - "3.11"
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v5
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Upgrade packaging tools
+        run: |
+          python -m pip install --upgrade pip
+
+      - name: Install NiriZan
+        run: |
+          pip install -e .
+
+      - name: Verify package import
+        run: |
+          python -c "import nirizan; print('Imported NiriZan successfully.')"
+
+      - name: Verify package metadata
+        run: |
+          python -c "import importlib.metadata as md; print(md.version('nirizan'))"

nirizan-0.1.0/.github/workflows/dependabot-auto-merge.yml

@@ -0,0 +1,128 @@
+name: Dependabot auto-merge
+
+# Runs only on pull requests opened by Dependabot. Every dependency bump,
+# regardless of semver level, must pass the full check suite here before
+# anything is auto-merged. Patch and minor updates that pass are merged
+# automatically. Major updates are never auto-merged, even if every check
+# is green, since a passing test suite does not prove a major bump (e.g.
+# pydantic v2 -> v3) is safe. It only proves the tests we happened to
+# write still pass against the new version.
+on:
+  pull_request:
+    branches: ["main"]
+
+permissions:
+  contents: write
+  pull-requests: write
+  checks: read
+
+jobs:
+  # Guard: only ever run the rest of this workflow for Dependabot PRs.
+  # A human PR that happens to touch pyproject.toml must never be
+  # auto-merged by this workflow.
+  guard:
+    if: github.actor == 'dependabot[bot]'
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo "Dependabot PR confirmed, proceeding to checks."
+
+  # Full check suite: pytest, mypy --strict, and the import-linter layer
+  # contract from docs/import-boundaries.md. All three must pass. This is
+  # the step that catches the failure modes a version bump can quietly
+  # introduce: a behavioral regression (pytest), a type-contract violation
+  # from an upstream API change (mypy --strict), or a new import that
+  # breaks the layer direction because a dependency changed how a module
+  # re-exports something (import-linter). None of the three subsumes the
+  # others, so all three run every time, not just on suspicion.
+  checks:
+    needs: guard
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Set up Python
+        uses: actions/setup-python@v7
+        with:
+          python-version: "3.11"
+
+      - name: Install project with dev dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Run pytest
+        run: pytest
+
+      - name: Run mypy --strict
+        run: mypy
+
+      - name: Run import-linter (layer contract)
+        run: lint-imports
+
+  # Determine the semver level of the bump using dependabot's own
+  # metadata action, rather than parsing the PR title or branch name.
+  # This is the source of truth fetch-metadata is built for.
+  metadata:
+    needs: guard
+    runs-on: ubuntu-latest
+    outputs:
+      update-type: ${{ steps.metadata.outputs.update-type }}
+      dependency-names: ${{ steps.metadata.outputs.dependency-names }}
+    steps:
+      - name: Fetch Dependabot metadata
+        id: metadata
+        uses: dependabot/fetch-metadata@v3
+        with:
+          github-token: "${{ secrets.GITHUB_TOKEN }}"
+
+  # Patch and minor bumps: if checks passed, enable GitHub's native
+  # auto-merge. This does not force-merge immediately; it tells GitHub to
+  # merge once all required status checks (including the `checks` job
+  # above) report green, so this step is safe to run even if some other
+  # required check outside this workflow is still pending.
+  auto-merge-patch-minor:
+    needs: [checks, metadata]
+    if: |
+      needs.metadata.outputs.update-type == 'version-update:semver-patch' ||
+      needs.metadata.outputs.update-type == 'version-update:semver-minor'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Enable auto-merge for patch/minor update
+        run: gh pr merge --auto --squash "$PR_URL"
+        env:
+          PR_URL: ${{ github.event.pull_request.html_url }}
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  # Major bumps: never auto-merged, regardless of check outcome. Leave the
+  # PR open, label it, and post a comment explaining why, so it's obvious
+  # at a glance this needs a human rather than looking stalled or ignored.
+  flag-major-for-review:
+    needs: [checks, metadata]
+    if: needs.metadata.outputs.update-type == 'version-update:semver-major'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Label PR for manual review
+        run: gh pr edit "$PR_URL" --add-label "needs-manual-review,major-update"
+        env:
+          PR_URL: ${{ github.event.pull_request.html_url }}
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Comment explaining why this was not auto-merged
+        run: |
+          gh pr comment "$PR_URL" --body "$(cat <<'EOF'
+          This is a **major** semver update (${{ needs.metadata.outputs.dependency-names }}).
+
+          Major updates are never auto-merged by this workflow, even when
+          pytest, mypy --strict, and import-linter all pass. A green check
+          suite here only proves the existing tests still pass against the
+          new version, not that the new version is safe: major bumps are
+          exactly where ABI mismatches, changed default behavior, or
+          removed APIs tend to surface outside what the test suite covers.
+
+          This PR needs manual review before merging. See
+          docs/import-boundaries.md and docs/contracts.md if the update
+          touches a dependency those documents assume a specific version
+          or behavior of.
+          EOF
+          )"
+        env:
+          PR_URL: ${{ github.event.pull_request.html_url }}
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}