nouc-studio 0.1.0rc1__tar.gz
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.
- nouc_studio-0.1.0rc1/.github/agents/nouc-studio.agent.md +63 -0
- nouc_studio-0.1.0rc1/.github/copilot-instructions.md +144 -0
- nouc_studio-0.1.0rc1/.gitignore +38 -0
- nouc_studio-0.1.0rc1/AGENTS.md +77 -0
- nouc_studio-0.1.0rc1/CONTRIBUTING.md +44 -0
- nouc_studio-0.1.0rc1/LICENSE +202 -0
- nouc_studio-0.1.0rc1/NOTICE +4 -0
- nouc_studio-0.1.0rc1/PKG-INFO +381 -0
- nouc_studio-0.1.0rc1/README.md +338 -0
- nouc_studio-0.1.0rc1/docs/new-project.md +108 -0
- nouc_studio-0.1.0rc1/docs/publishing.md +153 -0
- nouc_studio-0.1.0rc1/examples/demo_2_clinical_biotech/phase2_patient_cohorts.xlsx +0 -0
- nouc_studio-0.1.0rc1/examples/demo_3_ai_infra_finops/frontier_llm_routing_2026.xlsx +0 -0
- nouc_studio-0.1.0rc1/examples/sample_bundle/methodology_notes.md +10 -0
- nouc_studio-0.1.0rc1/examples/sample_bundle/pricing_model.py +15 -0
- nouc_studio-0.1.0rc1/pyproject.toml +134 -0
- nouc_studio-0.1.0rc1/scripts/check_bootstrap_install.py +148 -0
- nouc_studio-0.1.0rc1/scripts/release.py +223 -0
- nouc_studio-0.1.0rc1/skills/adaptive-failure-memory/SKILL.md +63 -0
- nouc_studio-0.1.0rc1/skills/deepwiki-live-grounding/SKILL.md +53 -0
- nouc_studio-0.1.0rc1/skills/epistemic-lineage-studio/SKILL.md +77 -0
- nouc_studio-0.1.0rc1/skills/marimo-pair-sandbox/SKILL.md +67 -0
- nouc_studio-0.1.0rc1/skills/studio-experience-design/SKILL.md +121 -0
- nouc_studio-0.1.0rc1/src/nouc_studio/__init__.py +6 -0
- nouc_studio-0.1.0rc1/src/nouc_studio/agents/__init__.py +25 -0
- nouc_studio-0.1.0rc1/src/nouc_studio/agents/orchestrator.py +217 -0
- nouc_studio-0.1.0rc1/src/nouc_studio/agents/specialists.py +536 -0
- nouc_studio-0.1.0rc1/src/nouc_studio/bootstrap.py +244 -0
- nouc_studio-0.1.0rc1/src/nouc_studio/cli.py +437 -0
- nouc_studio-0.1.0rc1/src/nouc_studio/config.py +123 -0
- nouc_studio-0.1.0rc1/src/nouc_studio/demos.py +469 -0
- nouc_studio-0.1.0rc1/src/nouc_studio/graph/__init__.py +28 -0
- nouc_studio-0.1.0rc1/src/nouc_studio/graph/engine.py +288 -0
- nouc_studio-0.1.0rc1/src/nouc_studio/graph/models.py +173 -0
- nouc_studio-0.1.0rc1/src/nouc_studio/graph/uncertainty.py +129 -0
- nouc_studio-0.1.0rc1/src/nouc_studio/ingestion/__init__.py +22 -0
- nouc_studio-0.1.0rc1/src/nouc_studio/ingestion/code_ast.py +224 -0
- nouc_studio-0.1.0rc1/src/nouc_studio/ingestion/documents.py +386 -0
- nouc_studio-0.1.0rc1/src/nouc_studio/ingestion/pipeline.py +101 -0
- nouc_studio-0.1.0rc1/src/nouc_studio/ingestion/tabular.py +307 -0
- nouc_studio-0.1.0rc1/src/nouc_studio/memory/__init__.py +17 -0
- nouc_studio-0.1.0rc1/src/nouc_studio/memory/models.py +68 -0
- nouc_studio-0.1.0rc1/src/nouc_studio/memory/store.py +519 -0
- nouc_studio-0.1.0rc1/src/nouc_studio/studio/__init__.py +21 -0
- nouc_studio-0.1.0rc1/src/nouc_studio/studio/generator.py +1432 -0
- nouc_studio-0.1.0rc1/src/nouc_studio/studio/querychat_engine.py +184 -0
- nouc_studio-0.1.0rc1/src/nouc_studio/studio/workbench.py +182 -0
- nouc_studio-0.1.0rc1/src/nouc_studio/verification/__init__.py +43 -0
- nouc_studio-0.1.0rc1/src/nouc_studio/verification/deepeval_auditor.py +111 -0
- nouc_studio-0.1.0rc1/src/nouc_studio/verification/doc_verifier.py +138 -0
- nouc_studio-0.1.0rc1/src/nouc_studio/verification/gate.py +547 -0
- nouc_studio-0.1.0rc1/src/nouc_studio/verification/monty_sandbox.py +101 -0
- nouc_studio-0.1.0rc1/src/nouc_studio/verification/pointblank_qa.py +130 -0
- nouc_studio-0.1.0rc1/tests/test_adaptive_memory.py +73 -0
- nouc_studio-0.1.0rc1/tests/test_bootstrap.py +312 -0
- nouc_studio-0.1.0rc1/tests/test_end_to_end_studio.py +81 -0
- nouc_studio-0.1.0rc1/tests/test_graph_lineage.py +108 -0
- nouc_studio-0.1.0rc1/tests/test_metric_planning.py +112 -0
- nouc_studio-0.1.0rc1/tests/test_multimodal_ingestion.py +93 -0
- nouc_studio-0.1.0rc1/tests/test_release_workflow.py +454 -0
- nouc_studio-0.1.0rc1/tests/test_studio_generator.py +426 -0
- nouc_studio-0.1.0rc1/tests/test_studio_shell.py +305 -0
- nouc_studio-0.1.0rc1/tests/test_verification_gate.py +99 -0
- nouc_studio-0.1.0rc1/tests/test_visual_gate.py +129 -0
- nouc_studio-0.1.0rc1/uv.lock +4014 -0
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: Nouc Studio
|
|
3
|
+
description: Clarify a business need, then build and verify a Nouc Studio application.
|
|
4
|
+
argument-hint: Describe your business need and where your input files are.
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
You are the Nouc Studio application builder. Speak the user's language. Follow
|
|
8
|
+
[repository rules](../../AGENTS.md) and the [engineering and intake instructions](../copilot-instructions.md).
|
|
9
|
+
|
|
10
|
+
For a NEW business request, your first phase is requirements clarification:
|
|
11
|
+
|
|
12
|
+
1. Inspect only the designated business inputs with read-only tools. Identify
|
|
13
|
+
consequential missing decisions; do not read historical tester briefs, answer
|
|
14
|
+
guides, expected results, or completed apps to infer the user's answers.
|
|
15
|
+
2. Ask **1–3 contextual questions, each with 2–4 concrete choices AND a writable
|
|
16
|
+
alternative**. Use the native questions tool when available; otherwise use
|
|
17
|
+
numbered choices in chat with "Other — describe your preference". Wait for
|
|
18
|
+
answers before implementation or builds. A recommended or preselected choice
|
|
19
|
+
is not an answer.
|
|
20
|
+
3. Before calling a questions tool, validate the payload: EVERY question must
|
|
21
|
+
have choices. For `requestedSchema`, use one string property with `enum` per
|
|
22
|
+
question, checking that the host provides its native custom-answer field;
|
|
23
|
+
otherwise offer the choices and writable alternative in chat. Do not add
|
|
24
|
+
free-text-only properties or companion "If other, specify" questions. For `vscode/askQuestions`,
|
|
25
|
+
provide options and enable `allowFreeformInput` for each question.
|
|
26
|
+
4. Questions about missing numbers or dates still need useful choices. For
|
|
27
|
+
example, offer entering a known balance/date in the custom field, making them
|
|
28
|
+
explicit editable scenario inputs, or limiting the first version to receivables
|
|
29
|
+
until cash data is available. Do not invent balances or silently infer policies.
|
|
30
|
+
Adapt questions to the actual request rather than copying this example.
|
|
31
|
+
5. After answers, check that dates, units and scope agree across inputs and
|
|
32
|
+
decisions. A supplied cash/snapshot date and a newer transaction are different
|
|
33
|
+
facts: ask which cutoff governs the analysis if unresolved. Never label an
|
|
34
|
+
unasked material decision a "delegated assumption". Ask a further small batch
|
|
35
|
+
for such gaps, with the same choices and writable alternative.
|
|
36
|
+
Summarize the agreed brief in chat and save it alongside the app BEFORE
|
|
37
|
+
writing implementation files.
|
|
38
|
+
|
|
39
|
+
Before UI implementation, load
|
|
40
|
+
[`studio-experience-design`](../../skills/studio-experience-design/SKILL.md).
|
|
41
|
+
Add its compact desktop screen plan to the working brief, without a cosmetic
|
|
42
|
+
questionnaire. Delegate the UI/UX specialist role when the host provides real
|
|
43
|
+
subagent support; otherwise perform its explicit self-review. Group related
|
|
44
|
+
cells into cohesive task panels with useful first-screen content, compact
|
|
45
|
+
readable tables and discoverable audit detail. Do not stack every output or
|
|
46
|
+
create a tab for each paragraph. Desktop is the default target, with minimal
|
|
47
|
+
justified scrolling; mobile does not determine the desktop layout.
|
|
48
|
+
|
|
49
|
+
Then implement, run `uv run nouc verify <app.py> --ty` and the relevant tests,
|
|
50
|
+
launch the actual Studio and complete the skill's browser gate at the target
|
|
51
|
+
and a smaller desktop viewport. Exercise the real task flows and relevant
|
|
52
|
+
empty/error states; fix material UX issues. A static check or `app.run()` alone
|
|
53
|
+
does not establish usable UI. If browser access is unavailable, report that gate
|
|
54
|
+
as unverified with the precise remaining check.
|
|
55
|
+
|
|
56
|
+
Reuse answers for follow-ups; honor an explicit request to skip clarification and
|
|
57
|
+
record delegated assumptions. Another agent may answer on the user's behalf only
|
|
58
|
+
when this conversation explicitly authorizes it; do not infer that authority
|
|
59
|
+
from a recommended option. Repository code and documentation stay in English.
|
|
60
|
+
Deliver the repository's multi-view Studio with lineage and QA; clearly label any
|
|
61
|
+
standalone Marimo prototype and its missing integration instead of claiming the
|
|
62
|
+
full workflow is complete. Never ask the user to act as a tester or supply CLI
|
|
63
|
+
recipes: take responsibility for the implementation and verification.
|
|
@@ -0,0 +1,144 @@
|
|
|
1
|
+
# GitHub Copilot Instructions for Nouc Studio
|
|
2
|
+
|
|
3
|
+
You are working inside **Nouc Studio** (`nouc-studio`), a self-evolving multi-agent system that uses **Marimo** and **Pydantic Monty** as verified sandboxes to build multi-view **`marimo-studio`** applications with full calculation lineage and epistemic uncertainty propagation.
|
|
4
|
+
|
|
5
|
+
## Required First Step: Clarify the User's Need
|
|
6
|
+
|
|
7
|
+
For every new request to create a studio, analysis, dashboard, or business workflow,
|
|
8
|
+
start a requirements conversation **before implementing or running a build**. The
|
|
9
|
+
user should express the business need in ordinary language; they do not need to
|
|
10
|
+
know Nouc Studio commands, choose libraries, or act as a tester.
|
|
11
|
+
|
|
12
|
+
1. Read the request and relevant input schemas/rules using read-only tools. Identify
|
|
13
|
+
what the user already specified and what would change the resulting decision,
|
|
14
|
+
calculation, or interface. Never treat a file's existence as the user's choice
|
|
15
|
+
to adopt all of its rules.
|
|
16
|
+
For a new business need, inspect the designated input files rather than test
|
|
17
|
+
harness artifacts. Do not read `tester-brief.txt`, `tester-answer-script.md`,
|
|
18
|
+
fixture oracles, expected-result tables, prior test reports or completed demo
|
|
19
|
+
implementations to supply the user's missing answers. Those are evaluation
|
|
20
|
+
evidence, not requirements. Discuss a discovered rules file as a proposed policy
|
|
21
|
+
to confirm, unless the user already explicitly adopted it. Consult implementation
|
|
22
|
+
patterns only after the business brief is agreed.
|
|
23
|
+
2. Ask a short first batch of **1–3 contextual questions**, each with **2–4 concrete
|
|
24
|
+
options**, a concise tradeoff, and a recommended option where justified. Always
|
|
25
|
+
let the user write a different answer. Prefer the available native questions
|
|
26
|
+
tool (for example `vscode/askQuestions`) with free-text input enabled. If that
|
|
27
|
+
tool is absent or fails, present numbered choices in chat and explicitly add
|
|
28
|
+
**"Other — describe your preference"** in the user's language. Tool availability
|
|
29
|
+
must not remove the clarification step.
|
|
30
|
+
Check the question payload before sending: every question needs suggested
|
|
31
|
+
choices and a writable alternative. Do not append a free-text-only catch-all
|
|
32
|
+
such as "Anything else?"; ask another contextual choice question when needed.
|
|
33
|
+
Keep each batch to three questions at most, then adapt to the answers.
|
|
34
|
+
Do not create companion questions such as "If other, specify" or "Which rules
|
|
35
|
+
would you change?" just to collect custom text. The native UI already provides
|
|
36
|
+
a writable alternative under each choice question. For a schema-based tool
|
|
37
|
+
exposing `requestedSchema`, use one string property with `enum` choices per
|
|
38
|
+
question, without extra `*_details` or `other_notes` properties. For
|
|
39
|
+
`vscode/askQuestions`, enable `allowFreeformInput` on each question. Ask a
|
|
40
|
+
substantive follow-up only after the user actually chooses to change a policy.
|
|
41
|
+
3. Prioritize the intended decision/audience, input scope, date/snapshot, units,
|
|
42
|
+
business definitions, missing/duplicate data policy, and success criteria only
|
|
43
|
+
where unresolved. Do not use a fixed questionnaire or ask the user to repeat
|
|
44
|
+
details already provided. A detailed initial request still gets a short check
|
|
45
|
+
on remaining scope, priorities, or acceptance ambiguities.
|
|
46
|
+
Resolve consequential business policies before cosmetic preferences. For example,
|
|
47
|
+
do not spend the whole first batch on language/layout while silently adopting
|
|
48
|
+
the cutoff date, cancelled/future payment handling, or missing-cost assumptions.
|
|
49
|
+
4. **Wait for the user's answers.** A recommendation, preselected option, skipped
|
|
50
|
+
question, tool timeout, or silence is not an answer. Continue only independent
|
|
51
|
+
read-only discovery while waiting. Ask a targeted follow-up if a consequential
|
|
52
|
+
ambiguity remains; support "I don't know" by explaining safe choices without
|
|
53
|
+
silently choosing a business rule.
|
|
54
|
+
5. Summarize the resulting working brief: objective and audience, source files,
|
|
55
|
+
snapshot/units, agreed formulas and exclusions, remaining explicit assumptions,
|
|
56
|
+
acceptance examples, and first deliverable. Publish that summary in chat and
|
|
57
|
+
save it alongside the app **before writing implementation files**. Then
|
|
58
|
+
implement using the agreed answers without an extra generic approval round.
|
|
59
|
+
Ask again only for a new consequential ambiguity or a material scope change.
|
|
60
|
+
Keep the saved brief current so decisions remain inspectable.
|
|
61
|
+
|
|
62
|
+
For follow-ups on the same agreed brief, reuse the answers; do not restart intake.
|
|
63
|
+
If the user explicitly asks to skip questions or delegates a choice, honor that
|
|
64
|
+
instruction and record the assumptions. This protocol applies to new product
|
|
65
|
+
needs, not to unrelated factual questions or an already specified bug fix.
|
|
66
|
+
|
|
67
|
+
Answer in the user's language. Keep repository code and documentation in English;
|
|
68
|
+
the requested application may use the user's chosen language. Do not promise that
|
|
69
|
+
`nouc build --need` automatically derives domain logic: the current generic
|
|
70
|
+
planner creates exploratory summaries. Build the required rules explicitly and
|
|
71
|
+
validate them against the agreed brief when generic output is insufficient.
|
|
72
|
+
The default studio deliverable still uses this repository's multi-view Studio,
|
|
73
|
+
lineage and QA architecture. Do not silently substitute a plain single-view
|
|
74
|
+
notebook and declare the Nouc Studio workflow complete. If only a standalone
|
|
75
|
+
prototype works, identify it as such and report the missing Studio integration.
|
|
76
|
+
|
|
77
|
+
## Desktop UI/UX Design and Acceptance
|
|
78
|
+
|
|
79
|
+
Apply [`studio-experience-design`](../skills/studio-experience-design/SKILL.md)
|
|
80
|
+
to every Studio UI. After the business brief is agreed and before UI code, add
|
|
81
|
+
a short desktop screen plan to that brief: primary task path, target viewport,
|
|
82
|
+
first-screen content, navigation, useful table columns/controls, and where detail
|
|
83
|
+
or justified scrolling belongs. Do not add cosmetic questions to intake.
|
|
84
|
+
|
|
85
|
+
Use an actual UI/UX specialist subagent if the host exposes delegation; otherwise
|
|
86
|
+
perform an explicit design and usability self-review. The role reviews hierarchy,
|
|
87
|
+
density, widget choice, progressive disclosure and the rendered workflows. It
|
|
88
|
+
does not invent business policy, assume a named VS Code tool exists, or acquire
|
|
89
|
+
authority to answer for the user without explicit delegation in this conversation.
|
|
90
|
+
|
|
91
|
+
Desktop takes priority unless the user specifies otherwise: use the available
|
|
92
|
+
screen width, compact readable tables, controls close to their content and a few
|
|
93
|
+
cohesive work panels. Group related notebook cells into real task flows; do not
|
|
94
|
+
create a separate tab for every paragraph or dump all outputs down one page.
|
|
95
|
+
Keep detailed provenance, SQL, QA and logs in discoverable audit/detail views,
|
|
96
|
+
while retaining visible summaries of warnings and exclusions beside the figures.
|
|
97
|
+
|
|
98
|
+
After implementation, launch the actual Studio in a browser at the target and a
|
|
99
|
+
smaller desktop viewport. Check useful first-screen content, clipping, table
|
|
100
|
+
readability and justified scroll. Exercise real navigation, filtering, selection,
|
|
101
|
+
detail and editing/saving flows where applicable, including relevant empty/error
|
|
102
|
+
states. Resolve material UX findings before completion and briefly record the
|
|
103
|
+
viewport and flows checked. Static/runtime checks do not replace this browser
|
|
104
|
+
gate. If browser access is unavailable, mark the UI gate unverified and identify
|
|
105
|
+
the remaining check; do not claim visual acceptance or ask the user to act as
|
|
106
|
+
the routine tester. Mobile checks are optional unless requested.
|
|
107
|
+
|
|
108
|
+
## Mandatory Engineering Rules
|
|
109
|
+
|
|
110
|
+
1. **Zero `pip` Policy**:
|
|
111
|
+
- Never suggest or execute `pip install`.
|
|
112
|
+
- Always use **`uv`** (`uv sync`, `uv add`, `uv run`) or **`pixi`** (`pixi run`).
|
|
113
|
+
- All standalone Marimo notebooks must declare dependencies in a PEP 723 `# /// script` header.
|
|
114
|
+
|
|
115
|
+
2. **Zero Blind Trust in LLM Parametric Knowledge**:
|
|
116
|
+
- Before writing code against `marimo`, `marimo-studio`, `polars`, `pointblank`, `pydantic-monty`, `google-genai`, or `wigglystuff`, verify symbols in the live environment:
|
|
117
|
+
```bash
|
|
118
|
+
uv run nouc ground --module <module_name> --symbol <SymbolName>
|
|
119
|
+
```
|
|
120
|
+
- Read the relevant specialized skills under `skills/*/SKILL.md` (`marimo-pair-sandbox`, `deepwiki-live-grounding`, `adaptive-failure-memory`, `epistemic-lineage-studio`, `studio-experience-design`).
|
|
121
|
+
|
|
122
|
+
3. **Consult & Update Dual-Tier Adaptive Memory**:
|
|
123
|
+
- Before generating or debugging code, inspect active prevention rules:
|
|
124
|
+
```bash
|
|
125
|
+
uv run nouc memory rules
|
|
126
|
+
```
|
|
127
|
+
- Whenever you encounter an error (`ruff`, `ty`, `marimo` reactive DAG, `pydantic-monty`, `pointblank`, `marimo-studio`) and verify a fix, record it in local (`.insights/memory/`) and global (`~/.nouc-studio/memory/`) memory:
|
|
128
|
+
```bash
|
|
129
|
+
uv run nouc memory record --library "<lib>" --error "<err>" --fix "<fix>" --rule "<rule>"
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
4. **Graph-First Lineage & Epistemic Humility**:
|
|
133
|
+
- Every ingested source, transformation, Pointblank validation check, and KPI must be registered in `LineageGraphEngine` (`rustworkx.PyDiGraph`).
|
|
134
|
+
- Every output number must carry an `UncertaintyProfile` (uncertainty or sensitivity bounds where supported, `±%` epistemic uncertainty, `TrustGrade` A–F, and explicit assumptions/caveats). Do not label heuristic sensitivity ranges as statistical 95% confidence intervals.
|
|
135
|
+
|
|
136
|
+
5. **Verification Gate Before Completion**:
|
|
137
|
+
- Run the applicable static, type, sandbox and domain checks before completion:
|
|
138
|
+
```bash
|
|
139
|
+
uv run nouc verify <app.py> --ty
|
|
140
|
+
uv run ruff check src tests
|
|
141
|
+
uv run ty check src tests
|
|
142
|
+
uv run pytest -v
|
|
143
|
+
```
|
|
144
|
+
- For UI deliverables, also pass the desktop browser acceptance gate above.
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
# Virtual environments & package managers
|
|
2
|
+
.venv/
|
|
3
|
+
venv/
|
|
4
|
+
.pixi/
|
|
5
|
+
.cache/
|
|
6
|
+
.uv-cache/
|
|
7
|
+
|
|
8
|
+
# Python bytecode & caches
|
|
9
|
+
__pycache__/
|
|
10
|
+
*.py[cod]
|
|
11
|
+
*$py.class
|
|
12
|
+
.pytest_cache/
|
|
13
|
+
.ruff_cache/
|
|
14
|
+
.mypy_cache/
|
|
15
|
+
|
|
16
|
+
# Build & distribution outputs
|
|
17
|
+
build/
|
|
18
|
+
dist/
|
|
19
|
+
*.egg-info/
|
|
20
|
+
.eggs/
|
|
21
|
+
|
|
22
|
+
# Marimo runtime & studio staging artifacts (in root workspace)
|
|
23
|
+
__marimo__/
|
|
24
|
+
|
|
25
|
+
# Local failure memory may contain input data, paths, prompts and diagnostics.
|
|
26
|
+
# Share reviewed, anonymized prevention rules in documentation instead.
|
|
27
|
+
.insights/memory/
|
|
28
|
+
|
|
29
|
+
# Environment secrets
|
|
30
|
+
.env
|
|
31
|
+
.env.*
|
|
32
|
+
!.env.example
|
|
33
|
+
|
|
34
|
+
# OS & IDE files
|
|
35
|
+
.DS_Store
|
|
36
|
+
Thumbs.db
|
|
37
|
+
.vscode/
|
|
38
|
+
.idea/
|
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
# AGENTS.md — Universal Coding Agent Instructions for Nouc Studio
|
|
2
|
+
|
|
3
|
+
This repository (`nouc-studio`) is equipped for autonomous and interactive Coding Agents (**GitHub Copilot**, **Claude Code**, **Cursor**, **Windsurf**, **Google Antigravity**, and **Marimo Pair**).
|
|
4
|
+
|
|
5
|
+
## 0. User Need Intake Before Implementation
|
|
6
|
+
|
|
7
|
+
For each new studio, analysis, dashboard, or business workflow, clarify the need
|
|
8
|
+
before implementing or running a build. Ask 1–3 questions tailored to consequential
|
|
9
|
+
gaps in the user's prompt, with 2–4 concrete choices per question and a free-text
|
|
10
|
+
alternative. Use the host's questions tool when available; otherwise offer the
|
|
11
|
+
same choices and "Other — describe your preference" in chat. Wait for answers;
|
|
12
|
+
silence, a skipped question, and a suggested default are not decisions. Read-only
|
|
13
|
+
discovery may continue while waiting. Reuse answers on subsequent turns.
|
|
14
|
+
Check that every question has choices and a writable alternative before sending;
|
|
15
|
+
do not append a free-text-only catch-all or exceed three questions in a batch.
|
|
16
|
+
Use the native custom-answer field, not separate "If other, specify" questions.
|
|
17
|
+
Inspect the designated business inputs, not historical tester briefs, answer
|
|
18
|
+
scripts, expected-result files or completed demos, to fill requirement gaps.
|
|
19
|
+
Present a discovered rules file for confirmation unless the user adopted it;
|
|
20
|
+
clarify consequential business policy before cosmetic preferences.
|
|
21
|
+
|
|
22
|
+
Summarize the agreed objective, inputs, snapshot/units, business rules, assumptions
|
|
23
|
+
and acceptance criteria in chat, and save that working brief alongside the app
|
|
24
|
+
before writing implementation files. Keep it current as decisions change.
|
|
25
|
+
Do not require the user to know CLI commands or pretend to be a tester. Honor an
|
|
26
|
+
explicit request to skip questions, with assumptions recorded. See the detailed
|
|
27
|
+
intake protocol in [`.github/copilot-instructions.md`](.github/copilot-instructions.md).
|
|
28
|
+
|
|
29
|
+
## 1. Specialized Agent Skills (`skills/`)
|
|
30
|
+
|
|
31
|
+
Before modifying or generating studio pipelines, load the relevant skill instructions:
|
|
32
|
+
- [`skills/marimo-pair-sandbox/SKILL.md`](skills/marimo-pair-sandbox/SKILL.md): PEP 723 reactive Marimo notebooks, `pydantic-monty` microsecond sandbox evaluation, and `marimo-studio` multi-view authoring.
|
|
33
|
+
- [`skills/deepwiki-live-grounding/SKILL.md`](skills/deepwiki-live-grounding/SKILL.md): Zero-Blind-Trust live symbol introspection (`uv run nouc ground`) and DeepWiki MCP (`https://mcp.deepwiki.com/mcp`) repository documentation queries.
|
|
34
|
+
- [`skills/adaptive-failure-memory/SKILL.md`](skills/adaptive-failure-memory/SKILL.md): Querying and recording failure-to-fix episodes in `.insights/memory/` (local) and `~/.nouc-studio/memory/` (global cross-project).
|
|
35
|
+
- [`skills/epistemic-lineage-studio/SKILL.md`](skills/epistemic-lineage-studio/SKILL.md): `rustworkx.PyDiGraph` calculation lineage, Posit `pointblank` QA, transparent `QueryChat` SQL, and epistemic uncertainty propagation.
|
|
36
|
+
- [`skills/studio-experience-design/SKILL.md`](skills/studio-experience-design/SKILL.md): Desktop screen planning, UI/UX specialist review, compact readable tables, progressive disclosure, and real browser acceptance.
|
|
37
|
+
|
|
38
|
+
## 2. Desktop Experience Before and After Implementation
|
|
39
|
+
|
|
40
|
+
For every Studio UI, apply `studio-experience-design`: add a compact desktop
|
|
41
|
+
screen plan to the agreed brief before coding, then use a UI/UX specialist
|
|
42
|
+
subagent when the host supports delegation, or an explicit self-review otherwise.
|
|
43
|
+
Design for the desktop viewport, short task paths, readable table density and
|
|
44
|
+
minimal justified scrolling. Keep detailed evidence in discoverable audit/detail
|
|
45
|
+
views rather than stacking every output. This does not add cosmetic intake
|
|
46
|
+
questions or delegate unresolved business decisions.
|
|
47
|
+
|
|
48
|
+
Before declaring the app complete, run it in a real browser at the target and a
|
|
49
|
+
smaller desktop viewport, exercise its actual primary workflows, and resolve
|
|
50
|
+
material layout or interaction problems. Static checks alone do not pass this
|
|
51
|
+
gate; report it as unverified if browser access is unavailable. Mobile is not the
|
|
52
|
+
default priority unless the user requests it.
|
|
53
|
+
|
|
54
|
+
## 3. Core CLI Workflow for Agents
|
|
55
|
+
|
|
56
|
+
```bash
|
|
57
|
+
# 1. Inspect active model, local/self-hosted AI endpoints, and agent config
|
|
58
|
+
uv run nouc models
|
|
59
|
+
|
|
60
|
+
# 2. Check cross-project failure prevention rules before writing code
|
|
61
|
+
uv run nouc memory rules
|
|
62
|
+
|
|
63
|
+
# 3. Verify live Python signatures (Zero Blind Trust)
|
|
64
|
+
uv run nouc ground --module google.genai --symbol Client
|
|
65
|
+
uv run nouc ground --module marimo_studio.authoring --symbol open_workspace
|
|
66
|
+
|
|
67
|
+
# 4. Build & verify a multi-view Marimo Studio app
|
|
68
|
+
uv run nouc build --need "<objective>" --input <path> --output dist/studio_app
|
|
69
|
+
uv run nouc verify dist/studio_app/app.py --ty
|
|
70
|
+
|
|
71
|
+
# 5. Run full static, type, and test suite
|
|
72
|
+
uv run ruff check src tests
|
|
73
|
+
uv run ty check src tests
|
|
74
|
+
uv run pytest -v
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
The CLI checks complement the desktop browser gate; they do not replace it.
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
# Contributing to Nouc Studio
|
|
2
|
+
|
|
3
|
+
Thank you for contributing to **Nouc Studio**! Please follow these engineering principles when submitting changes:
|
|
4
|
+
|
|
5
|
+
Versions come from Git commits and release tags, never from a manually edited
|
|
6
|
+
package constant. See [Git versioning and tag-triggered publication](docs/publishing.md)
|
|
7
|
+
for development builds, the PyPI Trusted Publisher setup and release checks.
|
|
8
|
+
|
|
9
|
+
## 1. Zero `pip` Policy
|
|
10
|
+
- **Never** use `pip install` in scripts, documentation, or agent prompts.
|
|
11
|
+
- Exclusively use **`uv`** (`uv sync`, `uv add`, `uv run`) or **`pixi`** (`pixi run`).
|
|
12
|
+
- Standalone Marimo notebooks must declare dependencies using **PEP 723** inline `# /// script` headers.
|
|
13
|
+
|
|
14
|
+
## 2. Zero Blind Trust in Parametric Knowledge
|
|
15
|
+
- Before integrating or modifying calls to rapidly evolving libraries (`marimo`, `marimo-studio`, `polars`, `pointblank`, `pydantic-monty`, `google-genai`, `wigglystuff`), verify symbols empirically:
|
|
16
|
+
```bash
|
|
17
|
+
uv run nouc ground --module <module_name> --symbol <SymbolName>
|
|
18
|
+
```
|
|
19
|
+
- When needed, query upstream repository documentation via the DeepWiki MCP integration (`--repo owner/repo --question "..."`).
|
|
20
|
+
|
|
21
|
+
## 3. Graph-First Lineage & Epistemic Humility
|
|
22
|
+
- All data sources, transformations, validations, and KPIs must be registered as typed nodes and edges in `LineageGraphEngine` (`rustworkx.PyDiGraph`).
|
|
23
|
+
- Every output metric must propagate quantitative and epistemic uncertainty (`UncertaintyProfile`, 95% confidence interval, `TrustGrade` A–F, and explicit assumptions/caveats).
|
|
24
|
+
|
|
25
|
+
## 4. Dual-Tier Self-Healing Memory
|
|
26
|
+
- Keep the entire `.insights/memory/` directory and the global store untracked.
|
|
27
|
+
Raw episodes may contain business data, local paths or diagnostic snippets.
|
|
28
|
+
Share reviewed, anonymized rules in documentation rather than raw JSONL.
|
|
29
|
+
- Whenever you encounter a non-trivial failure (`ruff`, `ty`, `marimo` reactive DAG, `pydantic-monty`, `pointblank`, or `marimo-studio` build/validation) and verify a fix, record it so both the project-local (`.insights/memory/`) and global (`~/.nouc-studio/memory/`) stores learn from it:
|
|
30
|
+
```bash
|
|
31
|
+
uv run nouc memory record \
|
|
32
|
+
--library "<library>" \
|
|
33
|
+
--error "<error signature>" \
|
|
34
|
+
--fix "<verified fix>" \
|
|
35
|
+
--rule "<actionable prevention rule>"
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
## 5. Pre-Commit Verification Gate
|
|
39
|
+
Before opening a Pull Request, ensure all checks pass with zero warnings/errors:
|
|
40
|
+
```bash
|
|
41
|
+
uv run ruff check src tests
|
|
42
|
+
uv run ty check src tests
|
|
43
|
+
uv run pytest -v
|
|
44
|
+
```
|
|
@@ -0,0 +1,202 @@
|
|
|
1
|
+
|
|
2
|
+
Apache License
|
|
3
|
+
Version 2.0, January 2004
|
|
4
|
+
http://www.apache.org/licenses/
|
|
5
|
+
|
|
6
|
+
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
|
|
7
|
+
|
|
8
|
+
1. Definitions.
|
|
9
|
+
|
|
10
|
+
"License" shall mean the terms and conditions for use, reproduction,
|
|
11
|
+
and distribution as defined by Sections 1 through 9 of this document.
|
|
12
|
+
|
|
13
|
+
"Licensor" shall mean the copyright owner or entity authorized by
|
|
14
|
+
the copyright owner that is granting the License.
|
|
15
|
+
|
|
16
|
+
"Legal Entity" shall mean the union of the acting entity and all
|
|
17
|
+
other entities that control, are controlled by, or are under common
|
|
18
|
+
control with that entity. For the purposes of this definition,
|
|
19
|
+
"control" means (i) the power, direct or indirect, to cause the
|
|
20
|
+
direction or management of such entity, whether by contract or
|
|
21
|
+
otherwise, or (ii) ownership of fifty percent (50%) or more of the
|
|
22
|
+
outstanding shares, or (iii) beneficial ownership of such entity.
|
|
23
|
+
|
|
24
|
+
"You" (or "Your") shall mean an individual or Legal Entity
|
|
25
|
+
exercising permissions granted by this License.
|
|
26
|
+
|
|
27
|
+
"Source" form shall mean the preferred form for making modifications,
|
|
28
|
+
including but not limited to software source code, documentation
|
|
29
|
+
source, and configuration files.
|
|
30
|
+
|
|
31
|
+
"Object" form shall mean any form resulting from mechanical
|
|
32
|
+
transformation or translation of a Source form, including but
|
|
33
|
+
not limited to compiled object code, generated documentation,
|
|
34
|
+
and conversions to other media types.
|
|
35
|
+
|
|
36
|
+
"Work" shall mean the work of authorship, whether in Source or
|
|
37
|
+
Object form, made available under the License, as indicated by a
|
|
38
|
+
copyright notice that is included in or attached to the work
|
|
39
|
+
(an example is provided in the Appendix below).
|
|
40
|
+
|
|
41
|
+
"Derivative Works" shall mean any work, whether in Source or Object
|
|
42
|
+
form, that is based on (or derived from) the Work and for which the
|
|
43
|
+
editorial revisions, annotations, elaborations, or other modifications
|
|
44
|
+
represent, as a whole, an original work of authorship. For the purposes
|
|
45
|
+
of this License, Derivative Works shall not include works that remain
|
|
46
|
+
separable from, or merely link (or bind by name) to the interfaces of,
|
|
47
|
+
the Work and Derivative Works thereof.
|
|
48
|
+
|
|
49
|
+
"Contribution" shall mean any work of authorship, including
|
|
50
|
+
the original version of the Work and any modifications or additions
|
|
51
|
+
to that Work or Derivative Works thereof, that is intentionally
|
|
52
|
+
submitted to Licensor for inclusion in the Work by the copyright owner
|
|
53
|
+
or by an individual or Legal Entity authorized to submit on behalf of
|
|
54
|
+
the copyright owner. For the purposes of this definition, "submitted"
|
|
55
|
+
means any form of electronic, verbal, or written communication sent
|
|
56
|
+
to the Licensor or its representatives, including but not limited to
|
|
57
|
+
communication on electronic mailing lists, source code control systems,
|
|
58
|
+
and issue tracking systems that are managed by, or on behalf of, the
|
|
59
|
+
Licensor for the purpose of discussing and improving the Work, but
|
|
60
|
+
excluding communication that is conspicuously marked or otherwise
|
|
61
|
+
designated in writing by the copyright owner as "Not a Contribution."
|
|
62
|
+
|
|
63
|
+
"Contributor" shall mean Licensor and any individual or Legal Entity
|
|
64
|
+
on behalf of whom a Contribution has been received by Licensor and
|
|
65
|
+
subsequently incorporated within the Work.
|
|
66
|
+
|
|
67
|
+
2. Grant of Copyright License. Subject to the terms and conditions of
|
|
68
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
69
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
70
|
+
copyright license to reproduce, prepare Derivative Works of,
|
|
71
|
+
publicly display, publicly perform, sublicense, and distribute the
|
|
72
|
+
Work and such Derivative Works in Source or Object form.
|
|
73
|
+
|
|
74
|
+
3. Grant of Patent License. Subject to the terms and conditions of
|
|
75
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
76
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
77
|
+
(except as stated in this section) patent license to make, have made,
|
|
78
|
+
use, offer to sell, sell, import, and otherwise transfer the Work,
|
|
79
|
+
where such license applies only to those patent claims licensable
|
|
80
|
+
by such Contributor that are necessarily infringed by their
|
|
81
|
+
Contribution(s) alone or by combination of their Contribution(s)
|
|
82
|
+
with the Work to which such Contribution(s) was submitted. If You
|
|
83
|
+
institute patent litigation against any entity (including a
|
|
84
|
+
cross-claim or counterclaim in a lawsuit) alleging that the Work
|
|
85
|
+
or a Contribution incorporated within the Work constitutes direct
|
|
86
|
+
or contributory patent infringement, then any patent licenses
|
|
87
|
+
granted to You under this License for that Work shall terminate
|
|
88
|
+
as of the date such litigation is filed.
|
|
89
|
+
|
|
90
|
+
4. Redistribution. You may reproduce and distribute copies of the
|
|
91
|
+
Work or Derivative Works thereof in any medium, with or without
|
|
92
|
+
modifications, and in Source or Object form, provided that You
|
|
93
|
+
meet the following conditions:
|
|
94
|
+
|
|
95
|
+
(a) You must give any other recipients of the Work or
|
|
96
|
+
Derivative Works a copy of this License; and
|
|
97
|
+
|
|
98
|
+
(b) You must cause any modified files to carry prominent notices
|
|
99
|
+
stating that You changed the files; and
|
|
100
|
+
|
|
101
|
+
(c) You must retain, in the Source form of any Derivative Works
|
|
102
|
+
that You distribute, all copyright, patent, trademark, and
|
|
103
|
+
attribution notices from the Source form of the Work,
|
|
104
|
+
excluding those notices that do not pertain to any part of
|
|
105
|
+
the Derivative Works; and
|
|
106
|
+
|
|
107
|
+
(d) If the Work includes a "NOTICE" text file as part of its
|
|
108
|
+
distribution, then any Derivative Works that You distribute must
|
|
109
|
+
include a readable copy of the attribution notices contained
|
|
110
|
+
within such NOTICE file, excluding those notices that do not
|
|
111
|
+
pertain to any part of the Derivative Works, in at least one
|
|
112
|
+
of the following places: within a NOTICE text file distributed
|
|
113
|
+
as part of the Derivative Works; within the Source form or
|
|
114
|
+
documentation, if provided along with the Derivative Works; or,
|
|
115
|
+
within a display generated by the Derivative Works, if and
|
|
116
|
+
wherever such third-party notices normally appear. The contents
|
|
117
|
+
of the NOTICE file are for informational purposes only and
|
|
118
|
+
do not modify the License. You may add Your own attribution
|
|
119
|
+
notices within Derivative Works that You distribute, alongside
|
|
120
|
+
or as an addendum to the NOTICE text from the Work, provided
|
|
121
|
+
that such additional attribution notices cannot be construed
|
|
122
|
+
as modifying the License.
|
|
123
|
+
|
|
124
|
+
You may add Your own copyright statement to Your modifications and
|
|
125
|
+
may provide additional or different license terms and conditions
|
|
126
|
+
for use, reproduction, or distribution of Your modifications, or
|
|
127
|
+
for any such Derivative Works as a whole, provided Your use,
|
|
128
|
+
reproduction, and distribution of the Work otherwise complies with
|
|
129
|
+
the conditions stated in this License.
|
|
130
|
+
|
|
131
|
+
5. Submission of Contributions. Unless You explicitly state otherwise,
|
|
132
|
+
any Contribution intentionally submitted for inclusion in the Work
|
|
133
|
+
by You to the Licensor shall be under the terms and conditions of
|
|
134
|
+
this License, without any additional terms or conditions.
|
|
135
|
+
Notwithstanding the above, nothing herein shall supersede or modify
|
|
136
|
+
the terms of any separate license agreement you may have executed
|
|
137
|
+
with Licensor regarding such Contributions.
|
|
138
|
+
|
|
139
|
+
6. Trademarks. This License does not grant permission to use the trade
|
|
140
|
+
names, trademarks, service marks, or product names of the Licensor,
|
|
141
|
+
except as required for reasonable and customary use in describing the
|
|
142
|
+
origin of the Work and reproducing the content of the NOTICE file.
|
|
143
|
+
|
|
144
|
+
7. Disclaimer of Warranty. Unless required by applicable law or
|
|
145
|
+
agreed to in writing, Licensor provides the Work (and each
|
|
146
|
+
Contributor provides its Contributions) on an "AS IS" BASIS,
|
|
147
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
|
|
148
|
+
implied, including, without limitation, any warranties or conditions
|
|
149
|
+
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
|
|
150
|
+
PARTICULAR PURPOSE. You are solely responsible for determining the
|
|
151
|
+
appropriateness of using or redistributing the Work and assume any
|
|
152
|
+
risks associated with Your exercise of permissions under this License.
|
|
153
|
+
|
|
154
|
+
8. Limitation of Liability. In no event and under no legal theory,
|
|
155
|
+
whether in tort (including negligence), contract, or otherwise,
|
|
156
|
+
unless required by applicable law (such as deliberate and grossly
|
|
157
|
+
negligent acts) or agreed to in writing, shall any Contributor be
|
|
158
|
+
liable to You for damages, including any direct, indirect, special,
|
|
159
|
+
incidental, or consequential damages of any character arising as a
|
|
160
|
+
result of this License or out of the use or inability to use the
|
|
161
|
+
Work (including but not limited to damages for loss of goodwill,
|
|
162
|
+
work stoppage, computer failure or malfunction, or any and all
|
|
163
|
+
other commercial damages or losses), even if such Contributor
|
|
164
|
+
has been advised of the possibility of such damages.
|
|
165
|
+
|
|
166
|
+
9. Accepting Warranty or Additional Liability. While redistributing
|
|
167
|
+
the Work or Derivative Works thereof, You may choose to offer,
|
|
168
|
+
and charge a fee for, acceptance of support, warranty, indemnity,
|
|
169
|
+
or other liability obligations and/or rights consistent with this
|
|
170
|
+
License. However, in accepting such obligations, You may act only
|
|
171
|
+
on Your own behalf and on Your sole responsibility, not on behalf
|
|
172
|
+
of any other Contributor, and only if You agree to indemnify,
|
|
173
|
+
defend, and hold each Contributor harmless for any liability
|
|
174
|
+
incurred by, or claims asserted against, such Contributor by reason
|
|
175
|
+
of your accepting any such warranty or additional liability.
|
|
176
|
+
|
|
177
|
+
END OF TERMS AND CONDITIONS
|
|
178
|
+
|
|
179
|
+
APPENDIX: How to apply the Apache License to your work.
|
|
180
|
+
|
|
181
|
+
To apply the Apache License to your work, attach the following
|
|
182
|
+
boilerplate notice, with the fields enclosed by brackets "[]"
|
|
183
|
+
replaced with your own identifying information. (Don't include
|
|
184
|
+
the brackets!) The text should be enclosed in the appropriate
|
|
185
|
+
comment syntax for the file format. We also recommend that a
|
|
186
|
+
file or class name and description of purpose be included on the
|
|
187
|
+
same "printed page" as the copyright notice for easier
|
|
188
|
+
identification within third-party archives.
|
|
189
|
+
|
|
190
|
+
Copyright [yyyy] [name of copyright owner]
|
|
191
|
+
|
|
192
|
+
Licensed under the Apache License, Version 2.0 (the "License");
|
|
193
|
+
you may not use this file except in compliance with the License.
|
|
194
|
+
You may obtain a copy of the License at
|
|
195
|
+
|
|
196
|
+
http://www.apache.org/licenses/LICENSE-2.0
|
|
197
|
+
|
|
198
|
+
Unless required by applicable law or agreed to in writing, software
|
|
199
|
+
distributed under the License is distributed on an "AS IS" BASIS,
|
|
200
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
201
|
+
See the License for the specific language governing permissions and
|
|
202
|
+
limitations under the License.
|