framework-py 0.1.0.dev0__py3-none-any.whl

framework/templates/gitignore/course

@@ -0,0 +1,120 @@
+# Framework - Course Project
+# ================================================================================
+# Gitignore for course/educational materials with slides, assignments, and modules.
+# ================================================================================
+
+# ============================================================================
+# PRIVATE DATA - NEVER COMMIT
+# ============================================================================
+
+# Private directories (anywhere in project tree)
+**/private/**
+**/*_private/**
+
+# ============================================================================
+# SECRETS AND CREDENTIALS - NEVER COMMIT
+# ============================================================================
+
+.env
+.env.local
+.env.*.local
+.Renviron
+.httr-oauth
+**/credentials/**
+**/secrets/**
+*.key
+*.pem
+
+# ============================================================================
+# UTILITY & CACHE - SAFE TO IGNORE
+# ============================================================================
+
+# Temporary processing directories
+**/cache/**
+**/scratch/**
+**/tmp/**
+**/temp/**
+
+# Logs (run logs, cluster job output)
+**/logs/**
+slurm-*.out
+
+# Rendered slide artifacts
+/slides/_rendered/
+
+# Allow structure documentation
+!/slides/_rendered/**/README.md
+
+# ============================================================================
+# FRAMEWORK INTERNALS
+# ============================================================================
+
+framework.db
+framework.db-wal
+framework.db-shm
+.initiated
+.framework_scaffolded
+
+# ============================================================================
+# QUARTO ARTIFACTS
+# ============================================================================
+
+.quarto/
+_freeze/
+*_cache/
+*_files/
+
+# ============================================================================
+# PYTHON ENVIRONMENT
+# ============================================================================
+
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+.ipynb_checkpoints/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+*.egg-info/
+build/
+dist/
+
+# ============================================================================
+# IDE & SYSTEM FILES
+# ============================================================================
+
+# IDE - personal settings only (commit workspace settings if desired)
+.idea/
+.vscode/.history/
+.positron/.history/
+.history/
+
+# macOS
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# Windows
+Thumbs.db
+ehthumbs.db
+
+# Linux
+*~
+
+# ============================================================================
+# CLOUD/AWS CONFIG
+# ============================================================================
+
+.aws/
+.config/
+
+# ============================================================================
+# TEMPORARY FILES
+# ============================================================================
+
+*.tmp
+*.log
+*.bak
+*.swp
+*~

framework/templates/gitignore/presentation

@@ -0,0 +1,114 @@
+# Framework - Presentation Project
+# ================================================================================
+# Gitignore for single presentation projects (Quarto revealjs).
+# ================================================================================
+
+# ============================================================================
+# PRIVATE DATA - NEVER COMMIT
+# ============================================================================
+
+# Private directories (anywhere in project tree)
+**/private/**
+**/*_private/**
+
+# ============================================================================
+# SECRETS AND CREDENTIALS - NEVER COMMIT
+# ============================================================================
+
+.env
+.env.local
+.env.*.local
+.Renviron
+.httr-oauth
+**/credentials/**
+**/secrets/**
+*.key
+*.pem
+
+# ============================================================================
+# UTILITY & CACHE - SAFE TO IGNORE
+# ============================================================================
+
+# Temporary processing directories
+**/cache/**
+**/scratch/**
+**/tmp/**
+**/temp/**
+
+# Logs (run logs, cluster job output)
+**/logs/**
+slurm-*.out
+
+# ============================================================================
+# FRAMEWORK INTERNALS
+# ============================================================================
+
+framework.db
+framework.db-wal
+framework.db-shm
+.initiated
+.framework_scaffolded
+
+# ============================================================================
+# QUARTO ARTIFACTS
+# ============================================================================
+
+.quarto/
+_freeze/
+*_cache/
+*_files/
+
+# ============================================================================
+# PYTHON ENVIRONMENT
+# ============================================================================
+
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+.ipynb_checkpoints/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+*.egg-info/
+build/
+dist/
+
+# ============================================================================
+# IDE & SYSTEM FILES
+# ============================================================================
+
+# IDE - personal settings only (commit workspace settings if desired)
+.idea/
+.vscode/.history/
+.positron/.history/
+.history/
+
+# macOS
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# Windows
+Thumbs.db
+ehthumbs.db
+
+# Linux
+*~
+
+# ============================================================================
+# CLOUD/AWS CONFIG
+# ============================================================================
+
+.aws/
+.config/
+
+# ============================================================================
+# TEMPORARY FILES
+# ============================================================================
+
+*.tmp
+*.log
+*.bak
+*.swp
+*~

framework/templates/gitignore/project

@@ -0,0 +1,108 @@
+# Framework Research Project
+# ================================================================================
+# Pattern-based gitignore - works regardless of directory structure customization.
+# This is the standard template for non-sensitive projects.
+# ================================================================================
+
+# ============================================================================
+# PRIVATE DATA - NEVER COMMIT
+# ============================================================================
+
+# Private directories (anywhere in project tree)
+**/private/**
+**/*_private/**
+
+# ============================================================================
+# SECRETS AND CREDENTIALS - NEVER COMMIT
+# ============================================================================
+
+.env
+.env.local
+.env.*.local
+.Renviron
+.httr-oauth
+**/credentials/**
+**/secrets/**
+*.key
+*.pem
+
+# ============================================================================
+# UTILITY & CACHE - SAFE TO IGNORE
+# ============================================================================
+
+# Temporary processing directories
+**/cache/**
+**/scratch/**
+**/tmp/**
+**/temp/**
+
+# Logs (run logs, cluster job output)
+**/logs/**
+slurm-*.out
+
+# ============================================================================
+# FRAMEWORK INTERNALS
+# ============================================================================
+
+framework.db
+framework.db-wal
+framework.db-shm
+.initiated
+.framework_scaffolded
+
+# ============================================================================
+# QUARTO ARTIFACTS
+# ============================================================================
+
+.quarto/
+_freeze/
+*_cache/
+*_files/
+
+# ============================================================================
+# PYTHON ENVIRONMENT
+# ============================================================================
+
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+.ipynb_checkpoints/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+*.egg-info/
+build/
+dist/
+
+# ============================================================================
+# IDE & SYSTEM FILES
+# ============================================================================
+
+# IDE - personal settings only (commit workspace settings if desired)
+.idea/
+.vscode/.history/
+.positron/.history/
+.history/
+
+# macOS
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# Windows
+Thumbs.db
+ehthumbs.db
+
+# Linux
+*~
+
+# ============================================================================
+# TEMPORARY FILES
+# ============================================================================
+
+*.tmp
+*.log
+*.bak
+*.swp
+*~

framework/templates/gitignore/sensitive

@@ -0,0 +1,139 @@
+# Framework (Privacy-First Mode)
+# ================================================================================
+# This project uses Framework's privacy-first structure.
+# All */private/ directories are gitignored by default.
+# Only */public/ directories can be committed after explicit review.
+#
+# WORKFLOW:
+#   1. Sensitive/raw data goes in */private/ directories (NEVER committed)
+#   2. De-identified/aggregated data goes in */public/ directories (safe to commit)
+#   3. Analysis scripts are committed, but outputs are carefully controlled
+#
+# CRITICAL: Private directories are NEVER committed to version control.
+# ================================================================================
+
+# ============================================================================
+# SENSITIVE DATA - NEVER COMMIT
+# ============================================================================
+
+# Private directories - explicit paths for this project type
+/inputs/private/
+/reference/private/
+/outputs/private/
+
+# Generic private directory patterns (defense-in-depth)
+**/private/**
+**/*_private/**
+**/sensitive/**
+
+# Allow structure documentation (README and .gitkeep files in private dirs)
+!/inputs/**/README.md
+!/inputs/**/.gitkeep
+!/reference/**/README.md
+!/reference/**/.gitkeep
+!/outputs/**/README.md
+!/outputs/**/.gitkeep
+
+# ============================================================================
+# SECRETS AND CREDENTIALS - NEVER COMMIT
+# ============================================================================
+
+.env
+.env.local
+.env.*.local
+.Renviron
+.httr-oauth
+**/credentials/**
+**/secrets/**
+*.key
+*.pem
+*.p12
+*.pfx
+
+# ============================================================================
+# UTILITY & CACHE - SAFE TO IGNORE
+# ============================================================================
+
+# Temporary processing directories
+**/cache/**
+**/scratch/**
+**/tmp/**
+**/temp/**
+
+# Logs (run logs, cluster job output)
+**/logs/**
+slurm-*.out
+
+# ============================================================================
+# FRAMEWORK INTERNALS
+# ============================================================================
+
+framework.db
+framework.db-wal
+framework.db-shm
+.initiated
+.framework_scaffolded
+
+# ============================================================================
+# QUARTO ARTIFACTS
+# ============================================================================
+
+.quarto/
+_freeze/
+*_cache/
+*_files/
+
+# ============================================================================
+# PYTHON ENVIRONMENT
+# ============================================================================
+
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+.ipynb_checkpoints/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+*.egg-info/
+build/
+dist/
+
+# ============================================================================
+# IDE & SYSTEM FILES
+# ============================================================================
+
+# IDE - personal settings only (commit workspace settings if desired)
+.idea/
+.vscode/.history/
+.positron/.history/
+.history/
+
+# macOS
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# Windows
+Thumbs.db
+ehthumbs.db
+
+# Linux
+*~
+
+# ============================================================================
+# CLOUD/AWS CONFIG
+# ============================================================================
+
+.aws/
+.config/
+
+# ============================================================================
+# TEMPORARY FILES
+# ============================================================================
+
+*.tmp
+*.log
+*.bak
+*.swp
+*~

framework/templates/skills/framework-data/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: framework-data
+description: Use whenever reading or writing data files (CSV, Parquet, Excel, Stata, SPSS, SAS) in this Framework project. Read with fw.data_read() and write with fw.data_save(), which record a hash of each file in framework.db.
+---
+
+# Framework Data
+
+`fw.data_read()` and `fw.data_save()` record a SHA-256 hash of each data file
+in the project's `framework.db`. Reading the file directly with pandas skips
+that record, so a changed or replaced file would go unnoticed.
+
+## Reading
+
+```python
+survey = fw.data_read("inputs.raw.survey")  # by catalog name (preferred)
+customers = fw.data_read("inputs/raw/customers.csv")  # by path
+```
+
+`data_read()` reads CSV, TSV, Parquet, Excel, Stata, SPSS, and SAS files.
+Catalog files are checked against their recorded hash: a locked file that
+changed raises an error, and an unlocked one warns. Use it instead of
+`pd.read_csv()`, `pd.read_parquet()`, `pd.read_excel()`, `pd.read_stata()`,
+or `pyreadstat`.
+
+`.rds` files can only be read by R. Ask for a Parquet or CSV copy instead.
+
+## Saving
+
+```python
+fw.data_save(clean, "inputs.intermediate.survey_clean")  # Parquet, added to the catalog
+fw.data_save(final, "inputs/final/analysis_ready.csv", locked=True)
+```
+
+`data_save()` writes Parquet or CSV, which R can read too. Use it instead of
+`DataFrame.to_csv()` or `DataFrame.to_parquet()` for project data.
+
+## The data catalog
+
+Datasets are listed under `data` in the settings (often `settings/data.yml`)
+and read by dot-notation name. Use the catalog name when an entry exists.
+`fw.data_list()` shows the catalog.
+
+## Folders
+
+Data moves from raw to intermediate to final. The folders are listed under
+`directories` in the settings. Raw inputs are never changed, and only
+Framework writes go to the intermediate and final folders.

framework/templates/skills/framework-outputs/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: framework-outputs
+description: Use when saving analysis outputs, caching expensive computations, running database queries, or publishing files in this Framework project. Covers save_table(), save_figure(), save_model(), cache_remember(), db_query(), and publish().
+---
+
+# Framework Outputs, Caching, Queries, and Publishing
+
+## Saving outputs
+
+Each `save_*()` function writes to the project's output folder for that kind
+of result (created on first use) and records the file, so `result_list()`
+finds it later.
+
+```python
+fw.save_table(summary, "quarterly_summary")  # outputs/tables/ (csv)
+fw.save_table(report, "annual_report", format="xlsx")
+fw.save_figure(fig, "enrollment_trend")  # outputs/figures/ (png)
+fw.save_model(model, "regression_model")  # outputs/models/ (pickle)
+fw.save_notebook("notebooks/analysis.qmd")  # render with Quarto and save
+
+fw.result_list()  # everything saved so far
+fw.result_list(type="model")  # models only
+```
+
+In a sensitive project, outputs are private by default. Pass `public=True`
+only for outputs that are safe to share.
+
+## Caching
+
+```python
+model = fw.cache_remember("fitted_model", lambda: fit(training), expire_after="7 days")
+
+fw.cache("processed", frame)  # write
+frame = fw.cache_get("processed")  # read (None if missing)
+fw.cache_forget("processed")  # remove
+```
+
+Cache entries are tracked in `framework.db` with a hash and an expiry. Use
+names that say what the value is.
+
+## Database queries
+
+Connections are defined in the settings (often `settings/connections.yml`).
+Use Framework's helpers so credentials come from `.env`:
+
+```python
+users = fw.db_query("SELECT * FROM users WHERE active = 1", "main_db")
+fw.db_execute("UPDATE runs SET done = 1 WHERE id = ?", "main_db", params=(42,))
+
+with fw.db_connect("main_db") as conn:
+    ...
+```
+
+## Publishing
+
+`fw.publish()` and `fw.publish_notebook()` upload to the project's storage
+bucket, or to Framework Cloud when the project was set up from it:
+
+```python
+fw.publish("outputs/report.html")
+fw.publish_notebook("notebooks/analysis.qmd")
+```
+
+The publish functions refuse files inside a `private` folder, because those
+folders hold restricted data. They take `allow_private=True` to override
+this. Never pass `allow_private=True` on your own: only the person who has
+reviewed the file can decide that it is safe to publish. See the
+`framework-sensitive-data` skill if this project has one.

framework/templates/skills/framework-packages/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: framework-packages
+description: Use when adding, installing, or managing Python packages in this Framework project. Dependencies are recorded in pyproject.toml; add them with fw.package_add() or uv add instead of a bare pip install.
+---
+
+# Framework Packages
+
+The project's Python dependencies are listed in `pyproject.toml`, and
+`uv.lock` records the exact versions when the project uses uv. A package
+installed with a bare `pip install` is not recorded, so the next person (or
+the next machine) will not have it.
+
+## Adding packages
+
+```python
+fw.package_add("statsmodels")  # records it in pyproject.toml and installs it
+fw.package_add("polars>=1.0")  # with a version requirement
+```
+
+From a terminal, `uv add statsmodels` does the same.
+
+## Checking and restoring
+
+```python
+fw.packages_list()  # what pyproject.toml declares
+fw.packages_status()  # missing or out-of-date packages
+fw.packages_install()  # install everything (for example after cloning)
+fw.packages_snapshot()  # update uv.lock
+fw.packages_restore()  # install exactly what uv.lock records
+```
+
+Import packages normally in each notebook or script. Framework does not
+import them for you.

framework/templates/skills/framework-sensitive-data/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: framework-sensitive-data
+description: Use before any data operation, commit, output, or publish step in this privacy-sensitive Framework project. Covers private and public folders and the handling of identifiable data.
+---
+
+# Sensitive Data
+
+This project holds identifiable or restricted data. When it is unclear
+whether something is safe, treat it as private.
+
+## Rules
+
+1. Files in `inputs/private/` and `outputs/private/` are never committed. They
+   can identify people, and the `.gitignore` keeps them out of git.
+2. Raw data with identifiers goes in a `private/` folder.
+3. Only de-identified, aggregated data goes in a `public/` folder.
+4. Review every output before saving it to a public folder.
+5. Never publish anything from a private folder, and never pass
+   `allow_private=True` to a publish function on your own.
+6. Do not read or print restricted files. Values you print are sent to the
+   model provider. Work from the data dictionary and simulated data instead.
+
+## Data flow
+
+```
+Raw identifiable data  -> inputs/private/raw/
+    | clean, de-identify
+Intermediate           -> inputs/private/intermediate/
+    | aggregate, anonymize
+Public-safe data       -> inputs/public/final/
+```
+
+## Writing code
+
+- Do not print rows with identifiers in notebook output that will be rendered.
+- Do not put identifiers, names, or record-level values in code or comments.
+- Public tables follow small-cell suppression rules where they apply.
+- Save outputs with `public=False` (the default) until they have been reviewed.