graphcore-studio 0.2.0__tar.gz → 0.2.3__tar.gz

{graphcore_studio-0.2.0 → graphcore_studio-0.2.3}/.github/workflows/ci.yml

@@ -31,7 +31,7 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest, macos-latest, windows-latest]
-        python: ['3.9', '3.12']
+        python: ['3.9', '3.12', '3.14']
     runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@v4

{graphcore_studio-0.2.0 → graphcore_studio-0.2.3}/.github/workflows/wheels.yml

@@ -30,7 +30,7 @@ jobs:
       - name: Build wheels for supported CPython versions
         run: python -m pip install cibuildwheel && python -m cibuildwheel --output-dir wheelhouse
         env:
-          CIBW_BUILD: 'cp39-* cp310-* cp311-* cp312-* cp313-*'
+          CIBW_BUILD: 'cp39-* cp310-* cp311-* cp312-* cp313-* cp314-*'
           CIBW_SKIP: '*-musllinux_*'
           CIBW_TEST_COMMAND: >-
             python -c "from graphcore import END, Graph; g=Graph(); g.add_node('probe', lambda s,c: {'ok': True}); g.set_entry('probe').add_edge('probe', END); assert g.invoke().state['ok']; g.close()"

{graphcore_studio-0.2.0 → graphcore_studio-0.2.3}/CMakeLists.txt

@@ -1,5 +1,5 @@
 cmake_minimum_required(VERSION 3.16)
-project(GraphCore VERSION 0.2.0 LANGUAGES CXX)
+project(GraphCore VERSION 0.2.2 LANGUAGES CXX)
 option(GRAPHCORE_BUILD_TESTS "Build tests" ON)
 option(GRAPHCORE_BUILD_EXAMPLES "Build examples" ON)
 option(GRAPHCORE_BUILD_PYTHON "Build C ABI shared library for Python" ON)

{graphcore_studio-0.2.0 → graphcore_studio-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: graphcore-studio
-Version: 0.2.0
+Version: 0.2.3
 Summary: A local-first visual agent workflow studio powered by a native C++ graph runtime
 Keywords: agents,agentic-workflows,graph,C++,visual-workflow-builder
 License-Expression: MIT
@@ -15,11 +15,16 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Requires-Python: >=3.9
+Requires-Python: >=3.9.2
+Requires-Dist: openrouter<1,>=0.10.8
+Requires-Dist: pydantic<3,>=2
+Requires-Dist: openpyxl<4,>=3.1.5
+Requires-Dist: defusedxml<1,>=0.7.1
 Provides-Extra: models
-Requires-Dist: openrouter<1,>=0.10; extra == "models"
+Requires-Dist: openrouter<1,>=0.10.8; extra == "models"
 Provides-Extra: pydantic
 Requires-Dist: pydantic<3,>=2; extra == "pydantic"
 Description-Content-Type: text/markdown
@@ -32,7 +37,7 @@ GraphCore Studio is an interactive, local-first visual agent framework. Drag nod
 
 ## Start Studio
 
-Requirements: Python 3.9+ and a C++17 compiler. You do not need CMake, Node.js, Docker, API keys, an internet connection, or a model to try the included workflows.
+Requirements: Python 3.9.2+ and a C++17 compiler. You do not need CMake, Node.js, Docker, API keys, an internet connection, or a model to try the included workflows.
 
 From the project folder, run one command:
 
@@ -48,25 +53,25 @@ py run_studio.py
 
 If Python was installed through the Windows Store and `py` is unavailable, run `python run_studio.py` from the Visual Studio Developer Terminal.
 
-Stop the server with Ctrl+C. Workflows and run history live in `studio/data/`; drafts are saved in this browser. Run `python3 run_studio.py --help` to configure the port, data directory, or Python tool plugins.
+Stop the server with Ctrl+C. Workflows and run history live in `studio/data/`; drafts are saved in this browser. Studio starts on port 8787 when available and automatically chooses a free local port if it is occupied. The actual URL is printed in the terminal. Run `python3 run_studio.py --help` to configure a specific port, data directory, or Python tool plugins.
 
 ### Install the PyPI package
 
-After the first release is published, install the prebuilt package with:
+Install the prebuilt package and its OpenRouter/Pydantic runtime dependencies with:
 
 ```bash
-python -m pip install "graphcore-studio[models,pydantic]"
+python -m pip install graphcore-studio
 graphcore-studio
 ```
 
-The wheel bundles the C++ runtime and Studio UI. Source installs build the native runtime and therefore require a C++17 compiler and CMake. The distribution is named `graphcore-studio`; its Python API imports as `graphcore`.
+The wheel bundles the C++ runtime and Studio UI. Source installs build the native runtime and therefore require a C++17 compiler and CMake. The distribution is named `graphcore-studio`; its Python API imports as `graphcore`. Windows, macOS, and Linux wheels are provided for supported architectures.
 
 ### Use Pydantic
 
-The built-in structured-output validator works offline with no extra packages. To enable optional Pydantic v2 validation:
+The built-in structured-output validator works offline. Pydantic v2 is installed by the standard PyPI command above and can be selected as the validation engine. When running directly from a source checkout, install the runtime dependencies with:
 
 ```bash
-python3 -m pip install -r requirements-pydantic.txt
+python3 -m pip install -r requirements-models.txt -r requirements-pydantic.txt
 python3 run_studio.py
 ```
 
@@ -74,18 +79,16 @@ On Windows, replace `python3` with `py -3`. Restart Studio after installing pack
 
 ### Use OpenRouter models
 
-The **Chat Model** and **Agent** nodes use GraphCore's model adapter with the official OpenRouter Python SDK. C++ owns graph scheduling, state commits, conditions, and checkpoints; the Python wrapper calls the SDK. The OpenRouter request runs through the project-owned adapter rather than a chain framework.
+The **Chat Model** and **Agent** nodes use GraphCore's model adapter with the official OpenRouter Python SDK, installed automatically by the standard PyPI command. C++ owns graph scheduling, state commits, conditions, and checkpoints; the Python wrapper calls the SDK. The OpenRouter request runs through the project-owned adapter rather than a chain framework.
 
-Install the SDK into the Python environment used to run Studio:
+When running directly from a source checkout, install the runtime dependencies into the Python environment used to run Studio:
 
 ```bash
 python3 -m pip install -r requirements-models.txt
 python3 run_studio.py
 ```
 
-For a PyPI installation, use the `models` extra instead: `python -m pip install "graphcore-studio[models]"`.
-
-In Studio, open **Model integrations**, add `OPENROUTER_API_KEY`, and save. Select **OpenRouter** on a Chat Model node and enter a model ID from the [OpenRouter model catalog](https://openrouter.ai/models). Compose system/user/assistant messages and use **Insert variable** to reference workflow inputs and prior node outputs. Studio loads the local `.env` file automatically; secret values are not included in workflow files. The offline fixture needs no SDK, key, or network call.
+In Studio, open **Model integrations**, add `OPENROUTER_API_KEY`, and save. Add as many named models as you need, such as `model1 → deepseek/deepseek-v4-pro-0813` and `model2 → openai/gpt-4o-mini`, using IDs from the [OpenRouter model catalog](https://openrouter.ai/models). Choose a saved model on each Chat Model or Agent node. In workflow JSON, set `"model": "$model1"` or `"model": "$model2"` to select the model for that node. Literal model IDs still work. Compose system/user/assistant messages and use **Insert variable** to reference workflow inputs and prior node outputs. Studio loads the local `.env` file automatically; secret values are not included in workflow files. Named model IDs are stored in the local Studio data directory. The offline fixture needs no SDK, key, or network call.
 
 ## Build a workflow
 
@@ -98,6 +101,10 @@ In Studio, open **Model integrations**, add `OPENROUTER_API_KEY`, and save. Sele
 
 The starter templates cover research and review, structured output, Python tools, a supervisor delegating work to specialist agents, and a chat-model playground. The canvas also supports node search, keyboard undo/redo, zoom, pan, layout changes, validation, and run history.
 
+## Add document retrieval
+
+Open **Knowledge library** in the left sidebar and add `.txt`, `.md`, `.csv`, or `.json` files. The files stay in the local Studio data folder (up to 100 documents, 1 MiB per document, 10 MiB total). Add a **Document retrieval** node after Input, set its query field (for example `input`) and result count, then connect it to a Chat Model. Reference `{{context.results}}` in the model prompt, replacing `context` with the retrieval node's output key. Returned passages include source filenames and chunk numbers. Retrieval uses local BM25 keyword matching; it does not call an embedding service, and PDF extraction is not included yet.
+
 Prompt templates reference state with `{{input}}`, `{{research}}`, or nested fields such as `{{record.summary}}`. Structured Output defines required fields and types. Python plugins extend the node's registered-tool list without placing executable source code in the workflow document.
 
 ## Register a Python library or tool
@@ -169,3 +176,7 @@ Parallel fan-out and joins, database-backed persistence, distributed worker coor
 - [Local verification record](docs/VALIDATION.md)
 - [PyPI release checklist](docs/PYPI_RELEASE.md)
 - [Example plugin](studio/example_plugin.py)
+
+### Local table data workflows
+
+The development checkout now includes **Data workspace**: import typed CSV and XLSX files, preview local tables, and build an offline summary workflow with exact decimal calculations. Workflow state carries immutable table references rather than full datasets. See [the data workspace guide](docs/DATA_WORKSPACE.md) for usage, limits and the next delivery steps. Available in version 0.2.3.

{graphcore_studio-0.2.0 → graphcore_studio-0.2.3}/README.md

@@ -6,7 +6,7 @@ GraphCore Studio is an interactive, local-first visual agent framework. Drag nod
 
 ## Start Studio
 
-Requirements: Python 3.9+ and a C++17 compiler. You do not need CMake, Node.js, Docker, API keys, an internet connection, or a model to try the included workflows.
+Requirements: Python 3.9.2+ and a C++17 compiler. You do not need CMake, Node.js, Docker, API keys, an internet connection, or a model to try the included workflows.
 
 From the project folder, run one command:
 
@@ -22,25 +22,25 @@ py run_studio.py
 
 If Python was installed through the Windows Store and `py` is unavailable, run `python run_studio.py` from the Visual Studio Developer Terminal.
 
-Stop the server with Ctrl+C. Workflows and run history live in `studio/data/`; drafts are saved in this browser. Run `python3 run_studio.py --help` to configure the port, data directory, or Python tool plugins.
+Stop the server with Ctrl+C. Workflows and run history live in `studio/data/`; drafts are saved in this browser. Studio starts on port 8787 when available and automatically chooses a free local port if it is occupied. The actual URL is printed in the terminal. Run `python3 run_studio.py --help` to configure a specific port, data directory, or Python tool plugins.
 
 ### Install the PyPI package
 
-After the first release is published, install the prebuilt package with:
+Install the prebuilt package and its OpenRouter/Pydantic runtime dependencies with:
 
 ```bash
-python -m pip install "graphcore-studio[models,pydantic]"
+python -m pip install graphcore-studio
 graphcore-studio
 ```
 
-The wheel bundles the C++ runtime and Studio UI. Source installs build the native runtime and therefore require a C++17 compiler and CMake. The distribution is named `graphcore-studio`; its Python API imports as `graphcore`.
+The wheel bundles the C++ runtime and Studio UI. Source installs build the native runtime and therefore require a C++17 compiler and CMake. The distribution is named `graphcore-studio`; its Python API imports as `graphcore`. Windows, macOS, and Linux wheels are provided for supported architectures.
 
 ### Use Pydantic
 
-The built-in structured-output validator works offline with no extra packages. To enable optional Pydantic v2 validation:
+The built-in structured-output validator works offline. Pydantic v2 is installed by the standard PyPI command above and can be selected as the validation engine. When running directly from a source checkout, install the runtime dependencies with:
 
 ```bash
-python3 -m pip install -r requirements-pydantic.txt
+python3 -m pip install -r requirements-models.txt -r requirements-pydantic.txt
 python3 run_studio.py
 ```
 
@@ -48,18 +48,16 @@ On Windows, replace `python3` with `py -3`. Restart Studio after installing pack
 
 ### Use OpenRouter models
 
-The **Chat Model** and **Agent** nodes use GraphCore's model adapter with the official OpenRouter Python SDK. C++ owns graph scheduling, state commits, conditions, and checkpoints; the Python wrapper calls the SDK. The OpenRouter request runs through the project-owned adapter rather than a chain framework.
+The **Chat Model** and **Agent** nodes use GraphCore's model adapter with the official OpenRouter Python SDK, installed automatically by the standard PyPI command. C++ owns graph scheduling, state commits, conditions, and checkpoints; the Python wrapper calls the SDK. The OpenRouter request runs through the project-owned adapter rather than a chain framework.
 
-Install the SDK into the Python environment used to run Studio:
+When running directly from a source checkout, install the runtime dependencies into the Python environment used to run Studio:
 
 ```bash
 python3 -m pip install -r requirements-models.txt
 python3 run_studio.py
 ```
 
-For a PyPI installation, use the `models` extra instead: `python -m pip install "graphcore-studio[models]"`.
-
-In Studio, open **Model integrations**, add `OPENROUTER_API_KEY`, and save. Select **OpenRouter** on a Chat Model node and enter a model ID from the [OpenRouter model catalog](https://openrouter.ai/models). Compose system/user/assistant messages and use **Insert variable** to reference workflow inputs and prior node outputs. Studio loads the local `.env` file automatically; secret values are not included in workflow files. The offline fixture needs no SDK, key, or network call.
+In Studio, open **Model integrations**, add `OPENROUTER_API_KEY`, and save. Add as many named models as you need, such as `model1 → deepseek/deepseek-v4-pro-0813` and `model2 → openai/gpt-4o-mini`, using IDs from the [OpenRouter model catalog](https://openrouter.ai/models). Choose a saved model on each Chat Model or Agent node. In workflow JSON, set `"model": "$model1"` or `"model": "$model2"` to select the model for that node. Literal model IDs still work. Compose system/user/assistant messages and use **Insert variable** to reference workflow inputs and prior node outputs. Studio loads the local `.env` file automatically; secret values are not included in workflow files. Named model IDs are stored in the local Studio data directory. The offline fixture needs no SDK, key, or network call.
 
 ## Build a workflow
 
@@ -72,6 +70,10 @@ In Studio, open **Model integrations**, add `OPENROUTER_API_KEY`, and save. Sele
 
 The starter templates cover research and review, structured output, Python tools, a supervisor delegating work to specialist agents, and a chat-model playground. The canvas also supports node search, keyboard undo/redo, zoom, pan, layout changes, validation, and run history.
 
+## Add document retrieval
+
+Open **Knowledge library** in the left sidebar and add `.txt`, `.md`, `.csv`, or `.json` files. The files stay in the local Studio data folder (up to 100 documents, 1 MiB per document, 10 MiB total). Add a **Document retrieval** node after Input, set its query field (for example `input`) and result count, then connect it to a Chat Model. Reference `{{context.results}}` in the model prompt, replacing `context` with the retrieval node's output key. Returned passages include source filenames and chunk numbers. Retrieval uses local BM25 keyword matching; it does not call an embedding service, and PDF extraction is not included yet.
+
 Prompt templates reference state with `{{input}}`, `{{research}}`, or nested fields such as `{{record.summary}}`. Structured Output defines required fields and types. Python plugins extend the node's registered-tool list without placing executable source code in the workflow document.
 
 ## Register a Python library or tool
@@ -143,3 +145,7 @@ Parallel fan-out and joins, database-backed persistence, distributed worker coor
 - [Local verification record](docs/VALIDATION.md)
 - [PyPI release checklist](docs/PYPI_RELEASE.md)
 - [Example plugin](studio/example_plugin.py)
+
+### Local table data workflows
+
+The development checkout now includes **Data workspace**: import typed CSV and XLSX files, preview local tables, and build an offline summary workflow with exact decimal calculations. Workflow state carries immutable table references rather than full datasets. See [the data workspace guide](docs/DATA_WORKSPACE.md) for usage, limits and the next delivery steps. Available in version 0.2.3.

{graphcore_studio-0.2.0 → graphcore_studio-0.2.3}/docs/ARCHITECTURE.md

@@ -4,7 +4,7 @@
 Browser visual canvas (plain HTML/CSS/JS)
              │ local JSON API with per-launch token
 Python standard-library HTTP server and run manager
-      ├── registered Python / optional Pydantic nodes
+      ├── registered Python / Pydantic nodes
       ├── official OpenRouter Python SDK adapter
       └── ctypes C ABI bridge
                   │
@@ -25,7 +25,7 @@ C++17 GraphCore runtime
 - `python/graphcore/`: Python SDK and asyncio callback bridge.
 - `run_studio.py`: one-command native compilation and local startup.
 
-No Node.js, frontend bundler, database, C++ package manager or Python web framework is required. The OpenRouter Python SDK is optional and required only for live model calls; the offline fixture works with the base install. Pydantic remains optional. The canvas is served as local files and does not send workflow data to a remote service.
+No Node.js, frontend bundler, database, C++ package manager or Python web framework is required. The standard PyPI install includes the OpenRouter Python SDK and Pydantic so model and validation nodes are ready to use. Live model calls still require an OpenRouter API key; the offline fixture needs no key or network call. The canvas is served as local files and does not send workflow data to a remote service.
 
 ## Extending nodes
 

graphcore_studio-0.2.3/docs/DATA_WORKSPACE.md

@@ -0,0 +1,132 @@
+# Local data workspace: first implementation
+
+This increment implements the CSV portion of DATA-01/XLS-01 and the first guided data workflow. It is local development work and is not yet published to PyPI.
+
+## Use it
+
+1. Start Studio from the updated checkout and open the HTTP URL it prints.
+2. Open **Data workspace** in the sidebar.
+3. Click **Choose CSV** and select a UTF-8 comma-separated file with a header row.
+4. Review the sample values and select a type for each column: Text, Whole number, Decimal (exact), or True / false. Columns start as Text. Click **Import table**, then choose **Preview / use**. Import errors identify the row and column; correct the type and retry without reselecting the file.
+5. Click **Build summary workflow** to create Input → Data summary → Output. This replaces the canvas through its existing replacement flow. The first numeric column is selected; change it in the node inspector if needed.
+6. Click **Run workflow**. No API key or model is needed. The result contains count, null count, exact decimal sum, minimum, maximum, and source metadata.
+
+Alternatively use **Use as workflow input “table”** in an existing workflow, add a Data summary node, set its input field to `table`, set the numeric column name, and connect its next output. Refer to `{{summary.sum}}` or `{{summary}}` from a later model or output node, using your configured output field name.
+
+Example file:
+
+```csv
+customer,amount,quantity,active
+Acme,0.10,2,true
+Beta,0.20,3,false
+Gamma,,1,true
+```
+
+With `amount` selected as Decimal (exact), `amount` produces sum `0.30`, count 2 and null count 1. Decimal values are JSON strings to avoid binary floating-point rounding; the numeric schema identifies their meaning.
+
+## Data contract and implementation
+
+`studio/tables.py` owns the immutable local artifact store. CSV imports parse into bounded typed records and persist under `<Studio data directory>/tables/<sha256>.json`. The artifact ID hashes the complete stored content. Reads verify that content still matches its ID. Re-importing identical content and filename reuses the artifact. Importing different content creates a different ID, preserving existing workflow references.
+
+Workflow state contains a `table_ref` with ID, filename, row count, column schema and original UTF-8 source hash. Full rows stay in the artifact file. Previews return at most 20 rows. Summary results carry the resolved source metadata. C++ schedules graph transitions; Python parses CSV and computes with `Decimal` at sufficient precision for the accepted bounds.
+
+Inputs accept string, integer, decimal and boolean declarations. Empty cells become null. Booleans accept `true`/`false` without regard to case. Headers must be unique and nonempty. Incorrect row widths, incompatible values, unknown declared columns and nonfinite decimals fail with actionable errors. Import supports a UTF-8 BOM. It does not infer dates, currencies or locale-specific separators.
+
+Limits: 2 MiB per source, 20,000 rows, 100 columns, 100 artifacts per workspace. Integers accept at most 100 digits; decimal inputs accept at most 100 characters with adjusted exponent within ±100 and stored exponent within ±200. Summation precision adapts to the accepted values. Artifacts intentionally have no delete operation in this increment, so existing checkpoint references remain valid. These are bounded local files rather than a database for large-scale analytics.
+
+HTTP APIs use the existing local Host checks and write token:
+
+- `POST /api/tables/inspect`: `{name, text}` → headers, up to five sample rows and row count; validates without persisting an artifact.
+- `POST /api/tables`: `{name, text, types}` → `{table: table_ref}`.
+- `GET /api/tables`: `{tables: [table_ref, ...]}`.
+- `GET /api/tables/<id>`: metadata plus bounded `rows` and `truncated`.
+
+## Validation and remaining delivery work
+
+Automated coverage checks exact decimal results, nulls, invalid headers/types/rows, path rejection, tamper detection, deduplicated imports, preview caps, native node execution and actual HTTP import → run → result. JavaScript syntax is checked. Browser import → preview → generated workflow → run was verified locally on October 3. Cross-platform release builds are still required before publication.
+
+Next increments:
+
+1. XLSX sheet selection and new-workbook export, formula-cache warnings.
+2. Deterministic filter, grouping, joins and reconciliation with explicit key and duplicate policies.
+3. Versioned connector contract and a read-only parameterized SQL Server connector with bounded queries.
+4. SQLite run/step/artifact metadata and immutable per-run configuration snapshots.
+5. Bounded model/tool agent execution, budgets and meaningful usage/timing telemetry.
+6. External action preparation, exact-payload approvals, durable action ledger and recovery tests before Outlook send.
+
+This first increment does not implement the full enterprise specification, external connectors, workbook editing, team identity or remote deployment.
+
+## Filter a table before calculating
+
+Add a **Table filter** node between Input and Data summary. Choose the table reference field (`table`), an exact column name (`amount`), a comparison (`At least`), and a value (`0.2`). Set its output field to `filtered`; configure Data summary to read `filtered`. For values 0.1, 0.2 and 0.3 this produces an exact sum of `0.5`.
+
+Supported comparisons: equals / does not equal for all types, greater / at least / less / at most for numeric columns, contains for text, and explicit Is null / Is not null. Text comparisons are case-sensitive. Enter comparison values as text; conversion follows the declared column type. Decimal comparisons are exact. Empty comparison values are rejected; use a null operator for empty CSV cells. Null cells never match ordinary comparisons, including Does not equal.
+
+Filtering writes a new immutable artifact with the original column schema and row order, leaving the source unchanged. Its reference includes provenance (parent artifact ID, operation, column, operator, comparison value, source row count and matched count). Identical operations on the same artifact reuse the same ID. Zero matches return an empty table with its schema; a later summary reports sum `0`, count 0 and null min/max. The existing 100-artifact workspace cap also applies to derived tables. Chain filter nodes for multiple required predicates; OR groups and expressions are not implemented in this increment.
+
+JSON node configuration:
+
+```json
+{"id":"filter","type":"data_filter","config":{"input_field":"table","column":"amount","operator":"gte","value":"0.2","output_key":"filtered"}}
+```
+
+Operator IDs are `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `contains`, `is_null`, `not_null`. Null operators do not require `value`.
+
+## Grouped aggregation
+
+Add **Grouped summary** after Input or Table filter. Set the table reference field, group column, numeric column, null-key policy and maximum groups (default 100, maximum 500). The output is another immutable `table_ref`, not a list of records in workflow state. Preview it in Data workspace, filter it, or pass it to Data summary using numeric column `sum` to calculate the grand total.
+
+Each group produces:
+
+| Column | Meaning |
+|---|---|
+| `group_key` | First encountered representation of the source key, retaining its declared type |
+| `row_count` | All rows in the group |
+| `count` | Non-null numeric values |
+| `null_count` | Null numeric values |
+| `sum` | Exact decimal total as a string |
+| `min`, `max` | Exact decimal values, or null when no numeric values exist |
+
+Groups retain their first-seen order. Text keys are case-sensitive. Decimal keys group by numeric equality, so 0.10 and 0.1 belong together. Include null keys as a separate group or exclude those rows; provenance records the excluded count. All-null numeric groups have sum `0` and null min/max. Empty input produces an empty grouped table with the complete schema. If the configured group limit is exceeded, execution fails without persisting a partial grouped result.
+
+Example: team A has 0.1 and 0.2, team B has 0.4. Grouping produces sums `0.3` and `0.4`; summarizing the grouped `sum` column returns `0.7`. Only one group column and one numeric column are supported in this increment; multi-key grouping, averages and custom aggregate expressions remain future work.
+
+```json
+{"id":"group","type":"data_group","config":{"input_field":"table","group_column":"team","column":"amount","null_keys":"include","max_groups":100,"output_key":"grouped"}}
+```
+
+## Reconcile two tables
+
+Import both CSVs with explicit column types. For each source, open **Preview / use**, set **Workflow input name** to `left` or `right`, and click **Use as workflow input**. Named references let you keep multiple tables in one workflow. Reusing an input name replaces that reference.
+
+Add a **Table reconciliation** node. Map the two state fields, key columns and value columns explicitly (column names may differ). Connect to Output and render `{{comparison.summary}}`, using the configured output field name. The result contains `table` (an immutable reference) and `summary` (bounded status counts); full comparison rows remain in the artifact store. A Table filter can read `comparison.table`, filter `status` equals `changed`, and pass the result to a review/model node later.
+
+| Output column | Meaning |
+|---|---|
+| `key` | Compared key; numeric keys use an exact decimal representation |
+| `left_value`, `right_value` | Mapped values, with numeric values represented as exact decimal strings |
+| `left_present`, `right_present` | Whether a source row exists, independently of null values |
+| `status` | `matched`, `changed`, `left_only`, or `right_only` |
+| `delta` | Exact left minus right for two non-null numeric values; otherwise null |
+
+Rows follow left-key first appearance, then right-only key first appearance. Text equality is case-sensitive; numeric columns compare by exact value. Mapped types must match or both be numeric (integer/decimal). Both-null mapped values count as matched; one-null versus non-null is changed. Missing rows remain distinct from present rows containing null.
+
+Duplicate policy defaults to **Fail on duplicates**. Explicit alternatives select the first or last source row for each key; summary/provenance records duplicate counts. Null keys default to failure, with explicit exclusion available and excluded-row counts recorded. The maximum result size defaults to 10,000 rows and can be set up to 20,000. Limit, duplicate, type and null-key failures do not persist a partial reconciliation artifact. Provenance records both parent IDs and mappings. Repeating the same operation reuses its artifact.
+
+```json
+{"id":"compare","type":"data_reconcile","config":{"left_field":"left","right_field":"right","left_key":"id","right_key":"code","left_column":"amount","right_column":"total","duplicates":"reject","null_keys":"reject","max_rows":10000,"output_key":"comparison"}}
+```
+
+This increment supports a single key and single compared value per side. Composite keys, multi-column comparisons, tolerances, fuzzy matching and writing changes back to either source are not implemented.
+
+## Import an XLSX worksheet
+
+In **Data workspace**, choose **Choose CSV / XLSX**, select a `.xlsx` file, choose a visible worksheet and its header row (1–100), then review columns. Assign text, integer, decimal or boolean types before importing. Imported tables can use the same summary, filter, grouped summary and reconciliation nodes as CSV tables.
+
+Formula cells use workbook caches; GraphCore does not calculate formulas. Acknowledge the cache warning before importing. Missing cached results block import: recalculate and save in Excel, then choose the file again. Cache freshness cannot be verified. Dates become ISO text; cell display formatting is omitted and numeric values retain the workbook's stored precision. The original workbook remains unchanged.
+
+Imports allow 2 MiB files, 100 columns and 20,000 data rows; ZIP expansion is bounded to 16 MiB total and 8 MiB per entry, with at most 1,000 entries. Hidden sheets, macro projects, encrypted files and legacy `.xls` files are unsupported. Headers must be unique and nonempty; Excel error cells and data beyond the header width are rejected. Trailing empty rows are omitted, while internal empty rows remain null records.
+
+The artifact records the original workbook hash, sheet, header row, formula count and warnings. Preview does not persist a table. HTTP endpoints are `POST /api/xlsx/sheets`, `/api/xlsx/inspect` and `/api/xlsx`, using base64 `content`, `name`, `sheet`, `header_row`, `types` and `acknowledge_formulas` as applicable.
+
+`openpyxl` and `defusedxml` are base installation requirements in this development checkout; a future release is needed for PyPI users. Cached-value behavior follows the [openpyxl loading documentation](https://openpyxl.readthedocs.io/en/stable/tutorial.html#loading-from-a-file).

graphcore_studio-0.2.3/docs/HOURLY_DEVELOPMENT_LOG.md

@@ -0,0 +1,66 @@
+# GraphCore development session log
+
+## October 3, 2026 — CSV foundation verification
+
+- Completed the first planned increment: verified browser import → preview → Build summary workflow → native execution. Synthetic fixture returned sum `0.3`, count 2 and null count 1.
+- Fixed decimal rounding for wide exponent ranges by deriving aggregation precision from accepted values. Added numeric length/exponent bounds, including extreme zero-exponent rejection.
+- Validation: 36 unit/compiler/Python tests and 8 loopback HTTP tests passed; JavaScript syntax check passed; fresh macOS 11 ARM64 wheel and source builds passed; archive inclusion and Twine checks passed.
+- Browser evidence: `/tmp/graphcore-csv-browser-check.jpg`; test data isolated under `/tmp/graphcore-ui-check-oct3`.
+- Delivery branch: `codex/local-data-foundation`. Implementation commit `ff19d06` was pushed successfully to origin. Repository-local Git identity now uses the existing GitHub no-reply identity for future commits; the implementation commit used the machine default identity.
+- Existing implementation files for retrieval, onboarding and CSV were included as dependencies of this coherent increment. The user-authored product specification was left outside the commit.
+- Artifacts still report already-released version 0.2.2 and must not be uploaded. Cross-platform CI and a release version bump remain pending.
+- Usage checks: start 3% five-hour / 0% weekly; pre-implementation 5% / 1%, both below 60% consumed.
+- Next step: replace JSON-only column declarations with guided column type controls and actionable import feedback. Retain the existing typed artifact contract and targeted tests.
+
+## October 3, 2026 — Guided CSV column mapping
+
+- Replaced JSON-only column declarations with Choose CSV → sample review → per-column type dropdowns → explicit Import table.
+- Added a nonpersisting inspection endpoint with up to five sample rows; shared parsing keeps validation consistent with import.
+- Added inline row/column errors, preserved choices after failed import, cleared outdated errors on type changes and strict browser UTF-8 decoding.
+- Browser verified: select Whole number for fractional values → actionable error → change to Decimal → successful import. Final importer screenshot: `/tmp/graphcore-guided-import.jpg`.
+- Validation: 37 unit/compiler/Python tests, 9 HTTP tests, JavaScript syntax and diff checks passed. No package dependencies or native core changes; no live model calls or PyPI release.
+- Delivery: continuing on `codex/local-data-foundation`; corresponding feature commit is recorded in Git history.
+- Usage: start 8% five-hour / 1% weekly; final check 12% / 2%, below the 60% threshold.
+- Next step: bounded deterministic table filtering, with explicit null/type semantics, a canvas node and focused tests.
+
+## October 3, 2026 — Deterministic table filtering
+
+- User explicitly requested continuation after the below-50% stop rule; this interactive session resumed while the hourly automation rule remains unchanged.
+- Added Table filter canvas node with typed comparison forms, explicit null controls and immutable derived artifacts carrying immediate parent provenance.
+- Filtering preserves source rows/schema and order, supports exact decimal comparisons, rejects incompatible operators/types and reuses identical derived artifacts.
+- Validation: 39 unit/compiler/Python tests and 9 HTTP tests passed (48 total), including null semantics, numeric ordering, boolean/text matching, invalid configs, empty results and native filter → summary execution. JavaScript syntax and diff checks passed.
+- Actual browser verified inspector null/value controls and full workflow result `Filtered total: 0.5`; screenshot `/tmp/graphcore-filter-result.jpg`.
+- Delivery continues on `codex/local-data-foundation`; no default-branch merge or PyPI publication.
+- Usage at start: 13% five-hour / 2% weekly. User's explicit continuation authorized this session at that usage.
+- Next step: grouping and exact decimal aggregation with bounded output and clear null/group-key semantics.
+
+## October 3, 2026 — Grouped exact aggregation
+
+- Continued under the user's explicit interactive resume; hourly scheduling retains its separate below-50% stop rule.
+- Added Grouped summary canvas node, per-group exact statistics and immutable typed grouped table references with parent provenance.
+- Defined first-seen order, case-sensitive text keys, decimal key numeric equality, include/exclude null-key policy and all-null/empty-input behavior.
+- Default group cap 100, configurable up to 500; overflow fails before persisting partial results. Derived previews retain provenance when reused as workflow inputs.
+- Validation: 43 unit/compiler/Python tests and 10 HTTP tests passed (53 total), covering exact totals, null statistics, order, decimal keys, limits/no partial artifacts and native/HTTP execution. Browser verified inspector and `Groups: 2. Total: 0.7`; evidence `/tmp/graphcore-group-result.jpg`.
+- No native runtime changes, dependencies or live model calls. Delivery remains `codex/local-data-foundation`; no PyPI release.
+- Usage at start 18% five-hour / 3% weekly.
+- Next step: table reconciliation with explicit key mapping and duplicate policies, then XLSX support.
+
+## October 3, 2026 — Explicit table reconciliation
+
+- Resumed under the user's interactive continuation. Implemented one-key/one-value full outer reconciliation with explicit mappings, typed equality and exact left-minus-right decimal deltas.
+- Added duplicate reject/first/last policies, null-key reject/exclude policies, status counts and row bounds. Missing rows are distinguished from present rows with null values. Results retain both source artifact IDs and mappings.
+- Added named table-reference inputs in Data workspace; browser verified adding `source_left` preserved other references.
+- Validation: 46 unit/compiler/Python tests plus 11 HTTP tests passed (57 total), including numeric cross-type keys, mapped column names, duplicate/null policies, no partial writes, native delta summary and HTTP preview. JavaScript syntax and diff checks passed.
+- Browser verified inspector controls and `Changed: 1. Left only: 1. Right only: 1.`; evidence `/tmp/graphcore-reconciliation-result.jpg`.
+- Delivery remains the existing development branch, with no live provider calls or PyPI publication.
+- Start usage: 22% five-hour / 3% weekly. Interactive resume does not change the scheduled below-50% stop rule.
+- Next step: XLSX support with sheet selection, typed import and formula-cache warnings; research the implementation dependency before adding it.
+
+## October 3, 2026 — Guided XLSX import
+
+- Continued under explicit interactive resume. Added worksheet/header selection, column types and shared immutable table artifacts with source workbook hash and import provenance.
+- Cached formulas require acknowledgment; missing cached results block import. Formula-containing rows remain visible in previews even without cached values. No formula calculation or source workbook changes occur. Added bounded ZIP parsing and unsupported-format rejection.
+- Added openpyxl and defusedxml to base package dependencies. Dependencies ship on the next release; published 0.2.2 remains unchanged.
+- Validation: 51 unit/compiler/Python tests and 12 HTTP tests passed (63 total); browser verified typed import, `0.3` summary and missing-cache rejection. JavaScript syntax, macOS ARM64 wheel/sdist builds, Twine and packaged dependency/module checks passed. Evidence `/tmp/graphcore-xlsx-result.jpg`.
+- Delivery remains codex/local-data-foundation; no live model calls or release publication. Usage at completion: 37% five-hour / 6% weekly. Scheduled below-50% stop rule remains unchanged.
+- Next step: export workflow result tables into a new workbook with provenance, without modifying source files.

graphcore_studio-0.2.3/docs/HOURLY_DEVELOPMENT_PLAN.md

@@ -0,0 +1,39 @@
+# Hourly development sessions
+
+Requested October 3, 2026. Execution environment is pending: the scheduling tool in this chat supports desktop/local execution, not provisioning a persistent cloud worker.
+
+## Session contract
+
+Run once per hour, with one focused feature increment or bug fix per session. Aim for 20–30 minutes of work; leave remaining time for validation and a durable handoff. Do not overlap active development sessions.
+
+At the start, inspect the repository status, previous session notes, current product specification and account usage. Never discard existing work. If account usage cannot be read, ordinary usage is disallowed, or either applicable reported usage window is at least 60% consumed, defer development until a later scheduled session. Check again before implementation and before costly verification. If the threshold is reached, save progress and stop development for that session. Scheduled checks and work already in flight can themselves consume usage; this is a best-effort development threshold, not an enforceable account-wide quota cap. Other chats share account usage.
+
+Use a configured economical model for routine sessions when supported by the chosen environment. Do not promise automatic model switching or a new quota by switching models. A separately billed API runner needs its own monetary budget; its API usage is not measured by the desktop account percentages.
+
+## Initial sequence
+
+1. Verify the current CSV data workspace in a browser and fix observed defects. Recheck packaging inclusion for new modules.
+2. Replace JSON-only column declarations with guided type controls and actionable import feedback.
+3. Add bounded deterministic filtering, with null/type semantics and targeted tests.
+4. Add grouping and exact decimal aggregation, with provenance and limits.
+5. Add table reconciliation with explicit key mappings and duplicate policies.
+6. Add XLSX import with sheet/header selection and cached-formula warnings.
+7. Add export to a new workbook, with deterministic contents and tests.
+8. Introduce versioned connector contracts and read-only connector fixtures.
+
+Treat this as an ordered queue of small deliverables, not a guarantee that each feature finishes in one hour. Split work when necessary and finish the current item before starting another.
+
+## Validation and Git delivery
+
+Run focused tests that establish the changed behavior, followed by the required regression checks. For UI changes, verify the actual browser interaction when available. Record skipped checks and reasons. Never claim a feature is complete when required validation failed.
+
+Commit only relevant reviewed changes and push passing increments to a `codex/` development branch on the configured GraphCore repository. Preserve user changes and inspect staged content for credentials and generated data. Do not force-push, merge into the default branch, publish to PyPI or create cloud resources as an incidental part of a session. Save incomplete work and failures without presenting them as verified increments.
+
+## Durable handoff
+
+Maintain a session log containing: backlog item, outcome, changed files, validation results, branch/commit where applicable, unresolved issues, next concrete step and latest available usage percentages. Notify the user only for meaningful completion, failure or required input. Stay quiet for unchanged or deferred sessions.
+
+## Environment choices
+
+- Desktop heartbeat: available here; requires the computer and app to remain running. Uses the current chat context.
+- Cloud worker: requires an accessible cloud execution environment and an authenticated runner. API-backed execution needs a separately approved spend budget. Cloud scheduling has not been configured by this plan.