framework-py 0.1.0.dev3__py3-none-any.whl → 0.1.0.dev5__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- framework/__init__.py +7 -0
- framework/__main__.py +64 -5
- framework/_agents_md.py +210 -0
- framework/_artifacts.py +930 -0
- framework/_assets/adopt/rules.json +161 -0
- framework/_assets/features/jupyter.json +39 -0
- framework/_assets/features/quarto.json +18 -0
- framework/_assets/features/quarto_manuscript.json +35 -0
- framework/_assets/features/quarto_slides.json +29 -0
- framework/_assets/features/renv.json +20 -0
- framework/_assets/features/targets.json +34 -0
- framework/_assets/features/uv.json +17 -0
- framework/_assets/schema/layer.v1.json +104 -7
- framework/_assets/schema/layers.v1.json +108 -7
- framework/_assets/schema/spec.v1.json +97 -7
- framework/_assets/sets/packages/tidyverse-analysis.json +42 -0
- framework/_assets/sets/skills/framework.json +25 -0
- framework/_assets/sets/skills/ggplot2.json +26 -0
- framework/_assets/workflows/jupyter.json +14 -0
- framework/_assets/workflows/quarto.json +14 -0
- framework/_assets/workflows/scripts.json +18 -0
- framework/_defaults_cache.py +47 -0
- framework/_paths.py +19 -9
- framework/adopt.py +365 -0
- framework/ai.py +25 -24
- framework/cloud.py +209 -21
- framework/create.py +395 -18
- framework/features.py +195 -0
- framework/hooks.py +69 -7
- framework/notebooks.py +9 -1
- framework/outputs.py +6 -1
- framework/quarto.py +77 -25
- framework/scaffold.py +50 -3
- framework/skill_sync.py +469 -0
- framework/spec/check.py +32 -8
- framework/spec/merge.py +1 -0
- framework/spec/resolve.py +80 -6
- framework/storage.py +154 -11
- framework/templates/defaults.yml +0 -1
- framework/templates/skills/framework-data/.framework-skill.json +5 -0
- framework/templates/skills/framework-data/SKILL.md +3 -0
- framework/templates/skills/framework-outputs/.framework-skill.json +5 -0
- framework/templates/skills/framework-outputs/SKILL.md +3 -0
- framework/templates/skills/framework-packages/.framework-skill.json +5 -0
- framework/templates/skills/framework-packages/SKILL.md +3 -0
- framework/templates/skills/framework-sensitive-data/.framework-skill.json +5 -0
- framework/templates/skills/framework-sensitive-data/SKILL.md +3 -0
- framework/templates/skills/framework-workflow/.framework-skill.json +5 -0
- framework/templates/skills/framework-workflow/SKILL.md +3 -0
- {framework_py-0.1.0.dev3.dist-info → framework_py-0.1.0.dev5.dist-info}/METADATA +14 -1
- framework_py-0.1.0.dev5.dist-info/RECORD +91 -0
- framework_py-0.1.0.dev3.dist-info/RECORD +0 -66
- {framework_py-0.1.0.dev3.dist-info → framework_py-0.1.0.dev5.dist-info}/WHEEL +0 -0
- {framework_py-0.1.0.dev3.dist-info → framework_py-0.1.0.dev5.dist-info}/licenses/LICENSE +0 -0
framework/__init__.py
CHANGED
|
@@ -10,6 +10,7 @@ from __future__ import annotations
|
|
|
10
10
|
from importlib.metadata import PackageNotFoundError, version
|
|
11
11
|
|
|
12
12
|
from framework._time import now
|
|
13
|
+
from framework.adopt import adopt, structure_import
|
|
13
14
|
from framework.ai import ai_skills_update
|
|
14
15
|
from framework.bootstrap import BootstrapResult, bootstrap
|
|
15
16
|
from framework.cache import (
|
|
@@ -69,6 +70,7 @@ from framework.errors import (
|
|
|
69
70
|
SettingsError,
|
|
70
71
|
UnsupportedFormatError,
|
|
71
72
|
)
|
|
73
|
+
from framework.features import tools_available
|
|
72
74
|
from framework.global_config import (
|
|
73
75
|
configure_global,
|
|
74
76
|
framework_template_path,
|
|
@@ -118,6 +120,7 @@ from framework.scaffold import project_info, scaffold, status
|
|
|
118
120
|
from framework.scratch import scratch_capture, scratch_clean
|
|
119
121
|
from framework.security import AuditResult, git_security_audit
|
|
120
122
|
from framework.settings import settings, settings_read, settings_write
|
|
123
|
+
from framework.skill_sync import skills_sync
|
|
121
124
|
from framework.spec.check import spec_check
|
|
122
125
|
from framework.spec.merge import SpecError
|
|
123
126
|
from framework.spec.resolve import ResolvedSpec, spec_resolve
|
|
@@ -155,6 +158,7 @@ __all__ = [
|
|
|
155
158
|
"SpecError",
|
|
156
159
|
"UnsupportedFormatError",
|
|
157
160
|
"__version__",
|
|
161
|
+
"adopt",
|
|
158
162
|
"ai_skills_update",
|
|
159
163
|
"bootstrap",
|
|
160
164
|
"cache",
|
|
@@ -239,12 +243,15 @@ __all__ = [
|
|
|
239
243
|
"settings",
|
|
240
244
|
"settings_read",
|
|
241
245
|
"settings_write",
|
|
246
|
+
"skills_sync",
|
|
242
247
|
"spec_check",
|
|
243
248
|
"spec_resolve",
|
|
244
249
|
"status",
|
|
245
250
|
"storage_test",
|
|
251
|
+
"structure_import",
|
|
246
252
|
"stubs_list",
|
|
247
253
|
"stubs_path",
|
|
248
254
|
"stubs_publish",
|
|
255
|
+
"tools_available",
|
|
249
256
|
"write_framework_template",
|
|
250
257
|
]
|
framework/__main__.py
CHANGED
|
@@ -1,7 +1,10 @@
|
|
|
1
1
|
"""Command-line entry points: ``python -m framework``.
|
|
2
2
|
|
|
3
3
|
python -m framework create --from-layers FILE --path DIR [--interactive]
|
|
4
|
-
python -m framework create --name NAME --path DIR [--type TYPE] [--
|
|
4
|
+
python -m framework create --name NAME --path DIR [--type TYPE] [--workflow ID]
|
|
5
|
+
[--tool ID[=false]]... [--skill-set ID]... [--package-set ID]... [--interactive]
|
|
6
|
+
[--offline]
|
|
7
|
+
python -m framework adopt [--path DIR] [--yes]
|
|
5
8
|
python -m framework bootstrap [--path DIR] [--interactive] [--no-packages]
|
|
6
9
|
python -m framework hook pre-commit
|
|
7
10
|
|
|
@@ -34,6 +37,24 @@ def _parser() -> argparse.ArgumentParser:
|
|
|
34
37
|
choices=["project", "project_sensitive", "course", "presentation", "bare"],
|
|
35
38
|
help="project type, with --name (default: bare, or asked with --interactive)",
|
|
36
39
|
)
|
|
40
|
+
create.add_argument(
|
|
41
|
+
"--workflow",
|
|
42
|
+
choices=["jupyter", "quarto", "scripts"],
|
|
43
|
+
help="with --name, how notebooks are written (default: jupyter for project types)",
|
|
44
|
+
)
|
|
45
|
+
create.add_argument(
|
|
46
|
+
"--tool",
|
|
47
|
+
action="append",
|
|
48
|
+
default=[],
|
|
49
|
+
metavar="ID[=false]",
|
|
50
|
+
help="with --name, turn a tool on, or off with =false (repeatable)",
|
|
51
|
+
)
|
|
52
|
+
create.add_argument(
|
|
53
|
+
"--skill-set", action="append", default=[], metavar="ID", help="add a skill set"
|
|
54
|
+
)
|
|
55
|
+
create.add_argument(
|
|
56
|
+
"--package-set", action="append", default=[], metavar="ID", help="add a package set"
|
|
57
|
+
)
|
|
37
58
|
create.add_argument(
|
|
38
59
|
"--interactive",
|
|
39
60
|
action="store_true",
|
|
@@ -45,6 +66,16 @@ def _parser() -> argparse.ArgumentParser:
|
|
|
45
66
|
),
|
|
46
67
|
)
|
|
47
68
|
|
|
69
|
+
create.add_argument(
|
|
70
|
+
"--offline",
|
|
71
|
+
action="store_true",
|
|
72
|
+
help="with --name, build from Framework's built-in defaults without Framework Cloud",
|
|
73
|
+
)
|
|
74
|
+
|
|
75
|
+
adopt = commands.add_parser("adopt", help="make an existing folder a Framework project")
|
|
76
|
+
adopt.add_argument("--path", default=".", help="the project folder (default: .)")
|
|
77
|
+
adopt.add_argument("--yes", action="store_true", help="accept the proposed folders")
|
|
78
|
+
|
|
48
79
|
bootstrap = commands.add_parser("bootstrap", help="prepare a cloned project")
|
|
49
80
|
bootstrap.add_argument("--path", default=".", help="the project folder (default: .)")
|
|
50
81
|
bootstrap.add_argument("--interactive", action="store_true", help="ask for empty .env values")
|
|
@@ -64,10 +95,24 @@ def main(argv: Sequence[str] | None = None) -> int:
|
|
|
64
95
|
from framework.hooks import hook_run
|
|
65
96
|
|
|
66
97
|
return hook_run(args.name)
|
|
67
|
-
|
|
68
|
-
|
|
98
|
+
name_only = args.command == "create" and (
|
|
99
|
+
args.type
|
|
100
|
+
or args.workflow
|
|
101
|
+
or args.tool
|
|
102
|
+
or args.skill_set
|
|
103
|
+
or args.package_set
|
|
104
|
+
or args.offline
|
|
105
|
+
)
|
|
106
|
+
if name_only and args.from_layers:
|
|
107
|
+
parser.error(
|
|
108
|
+
"--type, --workflow, --tool, --skill-set, --package-set, and --offline need --name"
|
|
109
|
+
)
|
|
69
110
|
try:
|
|
70
|
-
if args.command == "
|
|
111
|
+
if args.command == "adopt":
|
|
112
|
+
from framework.adopt import adopt
|
|
113
|
+
|
|
114
|
+
path = adopt(args.path, yes=args.yes)
|
|
115
|
+
elif args.command == "bootstrap":
|
|
71
116
|
from framework.bootstrap import bootstrap
|
|
72
117
|
|
|
73
118
|
path = bootstrap(
|
|
@@ -82,7 +127,21 @@ def main(argv: Sequence[str] | None = None) -> int:
|
|
|
82
127
|
else:
|
|
83
128
|
from framework.create import new
|
|
84
129
|
|
|
85
|
-
|
|
130
|
+
tools = {}
|
|
131
|
+
for tool in args.tool:
|
|
132
|
+
name, _, value = tool.partition("=")
|
|
133
|
+
tools[name] = value.lower() not in ("false", "no", "0", "off")
|
|
134
|
+
path = new(
|
|
135
|
+
args.name,
|
|
136
|
+
args.path,
|
|
137
|
+
args.type,
|
|
138
|
+
workflow=args.workflow,
|
|
139
|
+
tools=tools,
|
|
140
|
+
package_sets=args.package_set,
|
|
141
|
+
skill_sets=args.skill_set,
|
|
142
|
+
interactive=args.interactive,
|
|
143
|
+
offline=args.offline,
|
|
144
|
+
)
|
|
86
145
|
except FrameworkError as error:
|
|
87
146
|
print(f"Error: {error}", file=sys.stderr)
|
|
88
147
|
return 1
|
framework/_agents_md.py
ADDED
|
@@ -0,0 +1,210 @@
|
|
|
1
|
+
"""The AGENTS.md guide a new project gets, generated from its spec.
|
|
2
|
+
|
|
3
|
+
The sections follow R's AGENTS.md, with Python's functions. Headings marked
|
|
4
|
+
``<!-- @framework:regenerate -->`` describe the settings. The others are the
|
|
5
|
+
user's to edit.
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
from __future__ import annotations
|
|
9
|
+
|
|
10
|
+
from typing import Any
|
|
11
|
+
|
|
12
|
+
REGENERATE = "<!-- @framework:regenerate -->"
|
|
13
|
+
|
|
14
|
+
SKILL_DESCRIPTIONS = {
|
|
15
|
+
"framework-workflow": "scaffold() initialization, critical rules, creating notebooks/scripts",
|
|
16
|
+
"framework-data": "reading and saving data (data_read/data_save are mandatory)",
|
|
17
|
+
"framework-packages": "adding and managing Python packages (package_add, never pip install)",
|
|
18
|
+
"framework-outputs": "results, caching, database queries, publishing",
|
|
19
|
+
"framework-sensitive-data": "PII/PHI handling and private/public directory rules",
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
_PURPOSES = {
|
|
23
|
+
"inputs_raw": "Raw data (immutable)",
|
|
24
|
+
"inputs_intermediate": "Intermediate/cleaned data",
|
|
25
|
+
"inputs_final": "Analysis-ready data",
|
|
26
|
+
"outputs_tables": "Output tables",
|
|
27
|
+
"outputs_figures": "Output figures",
|
|
28
|
+
"outputs_models": "Saved models",
|
|
29
|
+
"outputs_reports": "Reports",
|
|
30
|
+
"inputs_private_raw": "Private raw data (PII/PHI)",
|
|
31
|
+
"inputs_public_raw": "Public raw data",
|
|
32
|
+
"inputs_private_intermediate": "Private intermediate",
|
|
33
|
+
"inputs_public_intermediate": "Public intermediate",
|
|
34
|
+
"inputs_private_final": "Private analysis-ready",
|
|
35
|
+
"inputs_public_final": "Public analysis-ready",
|
|
36
|
+
"outputs_private_tables": "Private tables",
|
|
37
|
+
"outputs_public_tables": "Public tables",
|
|
38
|
+
"outputs_private_figures": "Private figures",
|
|
39
|
+
"outputs_public_figures": "Public figures",
|
|
40
|
+
"data": "Data files",
|
|
41
|
+
"outputs": "Output files",
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
def _header(name: str) -> str:
|
|
46
|
+
return (
|
|
47
|
+
f"# {name}\n\n"
|
|
48
|
+
"This file provides guidance to AI assistants working with this Framework project.\n"
|
|
49
|
+
"It is the canonical context file; detailed workflow instructions live in the\n"
|
|
50
|
+
"skills listed below. Edit the sections without regeneration markers freely -\n"
|
|
51
|
+
"they won't be overwritten.\n"
|
|
52
|
+
)
|
|
53
|
+
|
|
54
|
+
|
|
55
|
+
def _skills(skills: list[str], skills_dir: str) -> str:
|
|
56
|
+
rows = [
|
|
57
|
+
f"| `{skill}` | {SKILL_DESCRIPTIONS.get(skill, '')} | `{skills_dir}/{skill}/SKILL.md` |"
|
|
58
|
+
for skill in skills
|
|
59
|
+
]
|
|
60
|
+
return "\n".join(
|
|
61
|
+
[
|
|
62
|
+
"## Skills",
|
|
63
|
+
"",
|
|
64
|
+
"Detailed instructions live in skill files, loaded on demand. Claude Code discovers",
|
|
65
|
+
"them automatically; other agents should read the relevant SKILL.md before working",
|
|
66
|
+
"on a matching task.",
|
|
67
|
+
"",
|
|
68
|
+
"| Skill | Covers | Path |",
|
|
69
|
+
"|-------|--------|------|",
|
|
70
|
+
*rows,
|
|
71
|
+
]
|
|
72
|
+
)
|
|
73
|
+
|
|
74
|
+
|
|
75
|
+
def _environment(spec: dict[str, Any]) -> str:
|
|
76
|
+
scaffold = spec.get("scaffold") or {}
|
|
77
|
+
functions = (spec.get("directories") or {}).get("functions") or "functions"
|
|
78
|
+
steps = [
|
|
79
|
+
"1. **Finds the project root** and loads `.env` and the settings (it does not change "
|
|
80
|
+
"the working directory)",
|
|
81
|
+
"2. **Creates framework.db** if needed and records the scaffold time",
|
|
82
|
+
f"3. **Puts `{functions}/` on the import path**, so its modules import directly",
|
|
83
|
+
"4. **Runs `scaffold.py`** from the project root, if there is one",
|
|
84
|
+
]
|
|
85
|
+
rules = [
|
|
86
|
+
"**DO NOT** run `pip install` or `uv add` yourself. Add packages with "
|
|
87
|
+
'`fw.package_add("name")`, which records them in pyproject.toml.',
|
|
88
|
+
"",
|
|
89
|
+
f"**DO NOT** copy helpers between notebooks. Put them in `{functions}/` and import them.",
|
|
90
|
+
]
|
|
91
|
+
seed = scaffold.get("seed")
|
|
92
|
+
if scaffold.get("seed_on_scaffold"):
|
|
93
|
+
steps.append(f"5. **Sets the random seed to {seed}** for reproducibility")
|
|
94
|
+
rules += [
|
|
95
|
+
"",
|
|
96
|
+
f"**DO NOT** reseed after scaffold(). The seed is already set to {seed}.",
|
|
97
|
+
"If you need a different seed for a specific operation, document why.",
|
|
98
|
+
]
|
|
99
|
+
return "\n".join(
|
|
100
|
+
[
|
|
101
|
+
f"## Framework Environment {REGENERATE}",
|
|
102
|
+
"",
|
|
103
|
+
"This project uses Framework for reproducible data analysis. **Every notebook and "
|
|
104
|
+
"script",
|
|
105
|
+
"MUST begin with `import framework as fw` and `fw.scaffold()`**, which initializes "
|
|
106
|
+
"the environment.",
|
|
107
|
+
"",
|
|
108
|
+
"### What scaffold() Does",
|
|
109
|
+
"",
|
|
110
|
+
*steps,
|
|
111
|
+
"",
|
|
112
|
+
"### CRITICAL RULES",
|
|
113
|
+
"",
|
|
114
|
+
*rules,
|
|
115
|
+
]
|
|
116
|
+
)
|
|
117
|
+
|
|
118
|
+
|
|
119
|
+
def _packages(spec: dict[str, Any]) -> str:
|
|
120
|
+
names = list((spec.get("packages") or {}).get("default_packages") or {})
|
|
121
|
+
lines = [f"## Installed Packages {REGENERATE}", ""]
|
|
122
|
+
if names:
|
|
123
|
+
lines += [f"**Dependencies** (in pyproject.toml): framework-py, {', '.join(names)}", ""]
|
|
124
|
+
else:
|
|
125
|
+
lines += ["**Dependencies** (in pyproject.toml): framework-py", ""]
|
|
126
|
+
lines.append('Add packages with `fw.package_add("name")`.')
|
|
127
|
+
return "\n".join(lines)
|
|
128
|
+
|
|
129
|
+
|
|
130
|
+
def _data(spec: dict[str, Any]) -> str:
|
|
131
|
+
directories = spec.get("directories") or {}
|
|
132
|
+
rows = [
|
|
133
|
+
f"| {purpose} | `{directories[key]}/` |"
|
|
134
|
+
for key, purpose in (
|
|
135
|
+
(key, _PURPOSES[key]) for key in directories if key in _PURPOSES and directories[key]
|
|
136
|
+
)
|
|
137
|
+
]
|
|
138
|
+
table = (
|
|
139
|
+
["| Purpose | Directory |", "|---------|-----------|", *rows]
|
|
140
|
+
if rows
|
|
141
|
+
else ["This project has no data folders configured yet."]
|
|
142
|
+
)
|
|
143
|
+
return "\n".join(
|
|
144
|
+
[
|
|
145
|
+
f"## Data Management {REGENERATE}",
|
|
146
|
+
"",
|
|
147
|
+
"**All data I/O MUST use `fw.data_read()` and `fw.data_save()`** - see the",
|
|
148
|
+
"`framework-data` skill for the full rules. This project's data directories:",
|
|
149
|
+
"",
|
|
150
|
+
*table,
|
|
151
|
+
]
|
|
152
|
+
)
|
|
153
|
+
|
|
154
|
+
|
|
155
|
+
def _type_section(spec: dict[str, Any]) -> str:
|
|
156
|
+
# Sensitive data is a setting, whatever structure the project uses
|
|
157
|
+
if (spec.get("security") or {}).get("sensitive"):
|
|
158
|
+
return (
|
|
159
|
+
"## Privacy Requirements\n\n"
|
|
160
|
+
"**This is a privacy-sensitive project.** Before ANY data operation, output, or\n"
|
|
161
|
+
"commit, follow the `framework-sensitive-data` skill. Never commit or publish\n"
|
|
162
|
+
"anything under a `private/` directory."
|
|
163
|
+
)
|
|
164
|
+
if spec.get("type") == "course":
|
|
165
|
+
return (
|
|
166
|
+
"## Course Structure\n\n"
|
|
167
|
+
"This is a teaching/course project. Lecture slides, assignments, modules, course\n"
|
|
168
|
+
"documents, data, and readings each have their own folder (see settings.yml).\n\n"
|
|
169
|
+
"### Creating Course Materials\n\n"
|
|
170
|
+
"```python\n"
|
|
171
|
+
'fw.make_revealjs("lecture-01-intro", dir="slides")\n'
|
|
172
|
+
'fw.make_notebook("hw-01-basics", dir="assignments")\n'
|
|
173
|
+
"```"
|
|
174
|
+
)
|
|
175
|
+
if spec.get("type") == "presentation":
|
|
176
|
+
return (
|
|
177
|
+
"## Presentation Workflow\n\n"
|
|
178
|
+
"This is a presentation project with minimal structure. Edit `presentation.qmd`\n"
|
|
179
|
+
"for your slides and render it with `quarto render presentation.qmd`.\n\n"
|
|
180
|
+
"```python\n"
|
|
181
|
+
'fw.make_revealjs("backup-slides")\n'
|
|
182
|
+
"```"
|
|
183
|
+
)
|
|
184
|
+
return (
|
|
185
|
+
"## Workflow Guidelines\n\n"
|
|
186
|
+
"Follow the standard Framework workflow (see the `framework-workflow` skill):\n"
|
|
187
|
+
"import with `fw.data_read()`, clean and save with `fw.data_save()`, analyze from\n"
|
|
188
|
+
"final datasets, export with `fw.save_table()`, `fw.save_figure()`, or `fw.save_model()`."
|
|
189
|
+
)
|
|
190
|
+
|
|
191
|
+
|
|
192
|
+
def agents_md(spec: dict[str, Any], skills_dir: str, restricted_notice: str | None) -> str:
|
|
193
|
+
"""The full AGENTS.md for a new project.
|
|
194
|
+
|
|
195
|
+
``restricted_notice`` names the folders agents must stay out of. It goes
|
|
196
|
+
right after the header in sensitive projects.
|
|
197
|
+
"""
|
|
198
|
+
sections = [_header(spec["name"])]
|
|
199
|
+
if restricted_notice:
|
|
200
|
+
sections.append(restricted_notice)
|
|
201
|
+
sections += [
|
|
202
|
+
_skills(list(spec.get("skills") or {}), skills_dir),
|
|
203
|
+
_environment(spec),
|
|
204
|
+
_packages(spec),
|
|
205
|
+
_data(spec),
|
|
206
|
+
_type_section(spec),
|
|
207
|
+
"## Project Notes\n\n*Add your project-specific notes, conventions, and documentation "
|
|
208
|
+
"here.*",
|
|
209
|
+
]
|
|
210
|
+
return "\n\n".join(section.rstrip("\n") for section in sections) + "\n"
|