crca 1.4.0__py3-none-any.whl → 1.5.0__py3-none-any.whl

schemas_export/crca_core/RefusalResult.schema.json

@@ -0,0 +1,90 @@
+{
+  "$defs": {
+    "RefusalChecklistItem": {
+      "description": "A single required input/action needed to proceed.",
+      "properties": {
+        "item": {
+          "minLength": 1,
+          "title": "Item",
+          "type": "string"
+        },
+        "rationale": {
+          "minLength": 1,
+          "title": "Rationale",
+          "type": "string"
+        }
+      },
+      "required": [
+        "item",
+        "rationale"
+      ],
+      "title": "RefusalChecklistItem",
+      "type": "object"
+    },
+    "RefusalReasonCode": {
+      "description": "Stable reason codes for refusal-first behavior.",
+      "enum": [
+        "SPEC_NOT_LOCKED",
+        "NO_SCM_FOR_COUNTERFACTUAL",
+        "NOT_IDENTIFIABLE",
+        "TIME_INDEX_INVALID",
+        "ASSUMPTIONS_UNDECLARED",
+        "INPUT_INVALID",
+        "UNSUPPORTED_OPERATION"
+      ],
+      "title": "RefusalReasonCode",
+      "type": "string"
+    }
+  },
+  "description": "Structured refusal (no numeric causal output).",
+  "properties": {
+    "result_type": {
+      "default": "Refusal",
+      "title": "Result Type",
+      "type": "string"
+    },
+    "reason_codes": {
+      "items": {
+        "$ref": "#/$defs/RefusalReasonCode"
+      },
+      "title": "Reason Codes",
+      "type": "array"
+    },
+    "message": {
+      "minLength": 1,
+      "title": "Message",
+      "type": "string"
+    },
+    "checklist": {
+      "items": {
+        "$ref": "#/$defs/RefusalChecklistItem"
+      },
+      "title": "Checklist",
+      "type": "array"
+    },
+    "suggested_next_steps": {
+      "items": {
+        "type": "string"
+      },
+      "title": "Suggested Next Steps",
+      "type": "array"
+    },
+    "details": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "default": null,
+      "title": "Details"
+    }
+  },
+  "required": [
+    "message"
+  ],
+  "title": "RefusalResult",
+  "type": "object"
+}

schemas_export/crca_core/ValidationReport.schema.json

@@ -0,0 +1,62 @@
+{
+  "$defs": {
+    "ValidationIssue": {
+      "properties": {
+        "code": {
+          "minLength": 1,
+          "title": "Code",
+          "type": "string"
+        },
+        "message": {
+          "minLength": 1,
+          "title": "Message",
+          "type": "string"
+        },
+        "path": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Path"
+        }
+      },
+      "required": [
+        "code",
+        "message"
+      ],
+      "title": "ValidationIssue",
+      "type": "object"
+    }
+  },
+  "description": "Returned by `validate_spec`.",
+  "properties": {
+    "ok": {
+      "title": "Ok",
+      "type": "boolean"
+    },
+    "errors": {
+      "items": {
+        "$ref": "#/$defs/ValidationIssue"
+      },
+      "title": "Errors",
+      "type": "array"
+    },
+    "warnings": {
+      "items": {
+        "$ref": "#/$defs/ValidationIssue"
+      },
+      "title": "Warnings",
+      "type": "array"
+    }
+  },
+  "required": [
+    "ok"
+  ],
+  "title": "ValidationReport",
+  "type": "object"
+}

scripts/build_lrm_dataset.py

@@ -0,0 +1,80 @@
+"""Build a hybrid LRM dataset from internal traces and public datasets."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import List
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+if str(REPO_ROOT) not in sys.path:
+    sys.path.insert(0, str(REPO_ROOT))
+
+from training.datasets import (
+    ReActExample,
+    examples_from_traces,
+    filter_examples,
+    merge_examples,
+    save_jsonl,
+)
+from training.public_datasets import PublicDatasetConfig, default_public_configs, load_public_examples
+
+
+def _load_public_config(path: Path) -> List[PublicDatasetConfig]:
+    payload = json.loads(path.read_text(encoding="utf-8"))
+    configs: List[PublicDatasetConfig] = []
+    for item in payload:
+        configs.append(PublicDatasetConfig(**item))
+    return configs
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Build hybrid LRM dataset JSONL.")
+    parser.add_argument("--trace-jsonl", action="append", default=[], help="Path to LRM plan trace JSONL.")
+    parser.add_argument("--public-config", type=str, default="", help="Path to public dataset config JSON.")
+    parser.add_argument("--output", type=str, required=True, help="Output JSONL path.")
+    parser.add_argument("--max-internal", type=int, default=None, help="Max internal examples to include.")
+    parser.add_argument("--max-public", type=int, default=None, help="Max public examples to include.")
+    parser.add_argument("--min-response-len", type=int, default=1)
+    parser.add_argument("--max-prompt-len", type=int, default=None)
+    parser.add_argument("--max-response-len", type=int, default=None)
+    args = parser.parse_args()
+
+    internal_examples: List[ReActExample] = []
+    if args.trace_jsonl:
+        trace_paths = [Path(p) for p in args.trace_jsonl]
+        internal_examples = examples_from_traces(trace_paths)
+
+    if args.public_config:
+        public_configs = _load_public_config(Path(args.public_config))
+    else:
+        public_configs = default_public_configs()
+    public_examples = load_public_examples(public_configs)
+
+    internal_examples = filter_examples(
+        internal_examples,
+        min_response_len=args.min_response_len,
+        max_prompt_len=args.max_prompt_len,
+        max_response_len=args.max_response_len,
+    )
+    public_examples = filter_examples(
+        public_examples,
+        min_response_len=args.min_response_len,
+        max_prompt_len=args.max_prompt_len,
+        max_response_len=args.max_response_len,
+    )
+
+    merged = merge_examples(
+        internal_examples=internal_examples,
+        public_examples=public_examples,
+        max_internal=args.max_internal,
+        max_public=args.max_public,
+    )
+
+    save_jsonl(merged, Path(args.output))
+
+
+if __name__ == "__main__":
+    main()

scripts/export_crca_core_schemas.py

@@ -0,0 +1,54 @@
+"""Export `crca_core` Pydantic JSON schemas for downstream tooling.
+
+This supports the "structured object only" requirement: downstream systems can
+validate inputs/outputs against stable schemas.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+if str(REPO_ROOT) not in sys.path:
+    sys.path.insert(0, str(REPO_ROOT))
+
+from crca_core.models.refusal import RefusalResult
+from crca_core.models.result import (
+    CounterfactualResult,
+    DiscoveryHypothesisResult,
+    EstimateResult,
+    IdentificationResult,
+    InterventionDesignResult,
+    ValidationReport,
+)
+from crca_core.models.spec import DraftSpec, LockedSpec
+
+
+def main() -> None:
+    out_dir = Path(__file__).resolve().parents[1] / "schemas_export" / "crca_core"
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    models = [
+        ("DraftSpec", DraftSpec),
+        ("LockedSpec", LockedSpec),
+        ("ValidationReport", ValidationReport),
+        ("RefusalResult", RefusalResult),
+        ("DiscoveryHypothesisResult", DiscoveryHypothesisResult),
+        ("InterventionDesignResult", InterventionDesignResult),
+        ("CounterfactualResult", CounterfactualResult),
+        ("IdentificationResult", IdentificationResult),
+        ("EstimateResult", EstimateResult),
+    ]
+
+    for name, model in models:
+        schema = model.model_json_schema()
+        (out_dir / f"{name}.schema.json").write_text(json.dumps(schema, indent=2), encoding="utf-8")
+
+    print(f"Wrote {len(models)} schemas to {out_dir}")
+
+
+if __name__ == "__main__":
+    main()
+

scripts/export_hf_lrm.py

@@ -0,0 +1,37 @@
+"""Export finetuned LRM model for HuggingFace."""
+
+from __future__ import annotations
+
+import argparse
+import shutil
+from pathlib import Path
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Export finetuned LRM model to HF format.")
+    parser.add_argument("--checkpoint-dir", type=str, required=True, help="Path to finetuned checkpoint.")
+    parser.add_argument("--output-dir", type=str, required=True, help="Output directory for HF upload.")
+    parser.add_argument("--model-card", type=str, default="MODEL_CARD.md", help="Model card path.")
+    args = parser.parse_args()
+
+    try:
+        from transformers import AutoModelForCausalLM, AutoTokenizer  # type: ignore
+    except Exception as exc:
+        raise RuntimeError("transformers is required to export model.") from exc
+
+    checkpoint_dir = Path(args.checkpoint_dir)
+    output_dir = Path(args.output_dir)
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    tokenizer = AutoTokenizer.from_pretrained(checkpoint_dir)
+    model = AutoModelForCausalLM.from_pretrained(checkpoint_dir)
+    tokenizer.save_pretrained(output_dir)
+    model.save_pretrained(output_dir, safe_serialization=True)
+
+    card_path = Path(args.model_card)
+    if card_path.exists():
+        shutil.copy(card_path, output_dir / "README.md")
+
+
+if __name__ == "__main__":
+    main()

scripts/export_ollama_gguf.py

@@ -0,0 +1,45 @@
+"""Export a finetuned HF model to GGUF for Ollama."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import subprocess
+from pathlib import Path
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Convert HF model to GGUF via llama.cpp.")
+    parser.add_argument("--checkpoint-dir", type=str, required=True, help="HF checkpoint directory.")
+    parser.add_argument("--output", type=str, required=True, help="Output GGUF path.")
+    parser.add_argument("--llama-cpp-dir", type=str, default="", help="Path to llama.cpp repo.")
+    args = parser.parse_args()
+
+    llama_cpp_dir = Path(args.llama_cpp_dir) if args.llama_cpp_dir else None
+    if llama_cpp_dir is None:
+        env_path = os.environ.get("LLAMA_CPP_DIR")
+        if env_path:
+            llama_cpp_dir = Path(env_path)
+    if llama_cpp_dir is None:
+        raise RuntimeError("Provide --llama-cpp-dir or set LLAMA_CPP_DIR.")
+
+    converter = llama_cpp_dir / "convert-hf-to-gguf.py"
+    if not converter.exists():
+        raise FileNotFoundError(f"Missing convert script: {converter}")
+
+    checkpoint_dir = Path(args.checkpoint_dir)
+    output_path = Path(args.output)
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+
+    cmd = [
+        "python",
+        str(converter),
+        str(checkpoint_dir),
+        "--outfile",
+        str(output_path),
+    ]
+    subprocess.check_call(cmd)
+
+
+if __name__ == "__main__":
+    main()

scripts/generate_changelog.py

@@ -0,0 +1,157 @@
+"""
+Generate changelog from git history and pyproject.toml.
+
+This script generates a changelog in Keep a Changelog format from:
+- Git tags (version numbers)
+- Conventional commit messages
+- README.md changelog section
+- pyproject.toml version information
+"""
+
+import re
+import subprocess
+from datetime import datetime
+from pathlib import Path
+from typing import Dict, List, Optional, Tuple
+import toml
+
+try:
+    import git
+    GITPYTHON_AVAILABLE = True
+except ImportError:
+    GITPYTHON_AVAILABLE = False
+
+
+def get_version_from_pyproject() -> Optional[str]:
+    """Get version from pyproject.toml."""
+    try:
+        pyproject_path = Path(__file__).parent.parent / "pyproject.toml"
+        if pyproject_path.exists():
+            data = toml.load(pyproject_path)
+            return data.get("project", {}).get("version")
+    except Exception:
+        pass
+    return None
+
+
+def get_git_tags() -> List[Tuple[str, str]]:
+    """Get git tags with dates."""
+    if not GITPYTHON_AVAILABLE:
+        return []
+    
+    try:
+        repo = git.Repo(Path(__file__).parent.parent)
+        tags = []
+        for tag in repo.tags:
+            try:
+                commit = repo.commit(tag)
+                date = datetime.fromtimestamp(commit.committed_date)
+                tags.append((tag.name, date.strftime("%Y-%m-%d")))
+            except Exception:
+                pass
+        return sorted(tags, key=lambda x: x[1], reverse=True)
+    except Exception:
+        return []
+
+
+def parse_conventional_commits(commits: List[str]) -> Dict[str, List[str]]:
+    """Parse conventional commits into categories."""
+    categories = {
+        "Added": [],
+        "Changed": [],
+        "Deprecated": [],
+        "Removed": [],
+        "Fixed": [],
+        "Security": []
+    }
+    
+    for commit in commits:
+        # Parse conventional commit format: type(scope): message
+        match = re.match(r'^(feat|fix|docs|style|refactor|perf|test|chore)(\(.+\))?:\s*(.+)$', commit)
+        if match:
+            commit_type = match.group(1)
+            message = match.group(3)
+            
+            if commit_type == "feat":
+                categories["Added"].append(message)
+            elif commit_type == "fix":
+                categories["Fixed"].append(message)
+            elif commit_type in ["refactor", "perf"]:
+                categories["Changed"].append(message)
+            elif commit_type == "docs":
+                categories["Changed"].append(f"Documentation: {message}")
+    
+    return categories
+
+
+def extract_changelog_from_readme() -> Dict[str, str]:
+    """Extract changelog section from README.md."""
+    readme_path = Path(__file__).parent.parent / "README.md"
+    if not readme_path.exists():
+        return {}
+    
+    try:
+        content = readme_path.read_text(encoding="utf-8")
+        # Extract changelog section (simplified)
+        # This would need more sophisticated parsing
+        return {}
+    except Exception:
+        return {}
+
+
+def generate_changelog() -> str:
+    """Generate changelog markdown."""
+    version = get_version_from_pyproject() or "Unknown"
+    tags = get_git_tags()
+    
+    changelog = f"""# Changelog
+
+All notable changes to CR-CA will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- New features in development
+
+### Changed
+- Changes in development
+
+## [{version}] - {datetime.now().strftime("%Y-%m-%d")}
+
+### Current Version
+
+Current version: {version}
+
+"""
+    
+    # Add entries from git tags
+    for tag_name, tag_date in tags[:10]:  # Last 10 versions
+        changelog += f"\n## [{tag_name}] - {tag_date}\n\n"
+        changelog += "### Changes\n\n"
+        changelog += "- See git history for details\n\n"
+    
+    return changelog
+
+
+def main():
+    """Generate and write changelog."""
+    changelog = generate_changelog()
+    
+    # Write to CHANGELOG.md
+    changelog_path = Path(__file__).parent.parent / "CHANGELOG.md"
+    changelog_path.write_text(changelog, encoding="utf-8")
+    
+    # Write to docs/changelog/index.md
+    docs_changelog_path = Path(__file__).parent.parent / "docs" / "changelog" / "index.md"
+    docs_changelog_path.parent.mkdir(parents=True, exist_ok=True)
+    docs_changelog_path.write_text(changelog, encoding="utf-8")
+    
+    print(f"Changelog generated: {changelog_path}")
+    print(f"Docs changelog updated: {docs_changelog_path}")
+
+
+if __name__ == "__main__":
+    main()

scripts/generate_crca_core_docs_from_schemas.py

@@ -0,0 +1,86 @@
+"""Generate lightweight Markdown docs from exported JSON schemas.
+
+This intentionally documents *structured contracts* (schemas), not narratives.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+from typing import Any, Dict, List, Tuple
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+
+
+def _load_schema(path: Path) -> Dict[str, Any]:
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def _schema_title(schema: Dict[str, Any], fallback: str) -> str:
+    return schema.get("title") or fallback
+
+
+def _collect_properties(schema: Dict[str, Any]) -> List[Tuple[str, str, str]]:
+    props = schema.get("properties") or {}
+    required = set(schema.get("required") or [])
+    rows: List[Tuple[str, str, str]] = []
+    for name, p in props.items():
+        typ = p.get("type") or p.get("$ref") or "unknown"
+        req = "required" if name in required else "optional"
+        desc = (p.get("description") or "").replace("\n", " ").strip()
+        rows.append((name, str(typ), f"{req}. {desc}".strip()))
+    return rows
+
+
+def _render_md(name: str, schema: Dict[str, Any]) -> str:
+    title = _schema_title(schema, name)
+    rows = _collect_properties(schema)
+
+    lines: List[str] = []
+    lines.append(f"## `{title}`")
+    lines.append("")
+    lines.append("This page is generated from the JSON schema (contract-first).")
+    lines.append("")
+    if not rows:
+        lines.append("_No top-level properties found in schema._")
+        lines.append("")
+        return "\n".join(lines)
+
+    lines.append("| Field | Type | Notes |")
+    lines.append("|---|---|---|")
+    for field, typ, notes in rows:
+        lines.append(f"| `{field}` | `{typ}` | {notes} |")
+    lines.append("")
+    return "\n".join(lines)
+
+
+def main() -> None:
+    schema_dir = REPO_ROOT / "schemas_export" / "crca_core"
+    if not schema_dir.exists():
+        raise SystemExit(f"Missing {schema_dir}. Run scripts/export_crca_core_schemas.py first.")
+
+    out_dir = REPO_ROOT / "docs_generated" / "crca_core"
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    index_lines = [
+        "# crca_core schema contracts (generated)",
+        "",
+        "These documents are generated from exported Pydantic JSON schemas.",
+        "",
+    ]
+
+    for schema_path in sorted(schema_dir.glob("*.schema.json")):
+        name = schema_path.name.replace(".schema.json", "")
+        schema = _load_schema(schema_path)
+        md = _render_md(name, schema)
+        (out_dir / f"{name}.md").write_text(md, encoding="utf-8")
+        index_lines.append(f"- `{name}`: `{name}.md`")
+
+    (out_dir / "index.md").write_text("\n".join(index_lines) + "\n", encoding="utf-8")
+    print(str(out_dir))
+
+
+if __name__ == "__main__":
+    main()
+