# Artiflex

**Artiflex — Browser-Based BYOK AI Workflow Demo**

Artiflex is a general-purpose browser application for configuring a project, managing structured data and source artifacts, defining reusable skills, running AI-assisted workflows, and reviewing their outputs. Its public code is domain-agnostic. Project owners can customize supported labels, fields, tabs, skills, appearance, and project content without embedding a particular private scenario in the application code.

> **Demo only. Do not use real student, identifying, regulated, or otherwise sensitive data.** Artiflex is not a production system, a security or compliance certification, or a substitute for professional review.

## Current implementation

- In-browser project state, with explicit local project save and open.
- Versioned project validation, credential checks, and migrations for supported earlier project formats. The current project format is version 9.
- Full-project replacement and selective project-section restore, with validation of the complete merged result before state changes.
- Dataset creation and CSV import, editable fields and records, filtering, selected subjects, collection notes, and synthetic sample data.
- Pasted-text and local `.txt`, `.md`, `.csv`, and `.json` artifact intake. URL references can be saved as metadata but are not fetched. PDF and DOCX extraction are not implemented.
- User-managed skills, skill import/export, skill input bindings, ordered compositions, and structured-output validation.
- A separate editable Prompt Baseline and a Caching workflow with project-local snapshots. Caching can capture the Prompt Baseline, Dataset, Subjects, Artifacts, or Skills; included snapshots are ordered in skill-run prompts, and provider cache-usage diagnostics are shown where returned.
- OpenAI model listing, key testing, AI skill runs, observation-type assistance, and project style assistance through separate Artiflex BYOK API routes.
- Project-specific appearance themes with primary, secondary, and tertiary palette roles; AI-suggested background recipes; live browser preview; and per-project accept, retry, and reset behavior.
- Application-authored background effects including aurora, drifting gradients, particles, falling stars, rain, snow, and image layers. Recipes can select supported background, floating-icon, and tile layouts and bounded effect settings.
- AI response records and separate human review decisions.
- Bar-chart rendering, chart category selection, and explicit dataset joins with diagnostics.
- Project-specific terminology and supported label editing through Customize Labels mode.

Known limitations: the chart renderer currently supports bar charts only; distribution and time-series chart behavior is not implemented. Evidence-link helpers are present, but evidence links are not yet integrated into the result display. AI appearance assistance can select and combine only effects Artiflex implements; it does not generate CSS or animation code. Some feature styles may still use hard-coded colors and may not respond to project palette changes. A browser smoke test with mocked provider responses does not certify live API calls, CORS, rate limiting, provider cache performance, or every composed-run scenario. Use separate API tests and controlled provider tests for those concerns.

## Product principles

- **General-purpose core; project-specific language.** Users can configure supported labels and field names for a project. Display labels are separate from stable internal identifiers.
- **User-controlled project content.** Dataset content, artifacts, skills, the editable Prompt Baseline, Caching snapshots, appearance themes, and results are held in browser memory unless the user explicitly saves a project file to their device. Artiflex does not provide server-side project storage.
- **Explicit AI request routing.** When a user confirms an AI request, the browser sends the selected request and the user's provider key to `api.maxflex.ai`. The MaxFlex API forwards the request to the selected AI provider; the response returns through MaxFlex to the browser.
- **Human review.** AI output is a proposal or analysis, not approval or an action applied automatically. Review decisions are stored separately from AI output.
- **Flex by default.** Unless the user selects Override Flex, Artiflex requests the Flex service tier. Override Flex omits that tier and uses the provider's default behavior. If the provider rejects a request, the user decides whether to retry with the override.
- **No plaintext API keys in project files.** Keys are entered separately and are not included in ordinary project saves. Users may explicitly choose a supported encrypted-key save option; passwords are not saved.
- **Fixed privacy disclosure.** Project customization cannot relabel or hide the disclosure about the browser-to-MaxFlex-to-provider request path.
- **Project-only appearance.** An accepted appearance belongs only to its Artiflex project. It is not a browser-wide preference, account setting, server-side theme, or separate CSS file. Opening another project applies that project's appearance, or the application defaults if it has no override.

## Data location and AI request routing

The Artiflex website serves application source and static assets; it does not store users' Artiflex projects. The active project is held in browser memory until the user explicitly downloads a project file. Opening a project reads a user-selected local file in the browser. Neither operation uploads the project to the Artiflex host.

When a user confirms an AI request, the browser sends the selected request and provider key to the MaxFlex API, which forwards the request to the selected provider:

```text
Browser → api.maxflex.ai → selected AI provider
Browser ← api.maxflex.ai ← selected AI provider
```

Selected prompt content, skill instructions, included Caching snapshots, enabled live context, artifacts, and other selected data are transmitted when the user confirms the relevant request. An included Prompt Baseline Caching component is a captured snapshot of the editable Baseline; it is sent as part of an ordinary skill-run prompt when that component is included and Caching is enabled. The current editable Baseline is not automatically appended as live content. Style-assistance requests send the user's direction and current effective appearance; project context is included only when selected. Submitted image URLs are passed to the selected provider as image inputs so the model can interpret them. Provider billing, terms, retention, and data-handling practices apply. A browser-resident project does not make an AI request local or prevent a provider from receiving its contents.

The API implementation is designed to use the submitted key transiently and avoid application-level persistence or payload logging. Rate-limit counters are stored separately on the API host. Application code alone cannot establish what web-server, proxy, hosting, monitoring, exception, or other infrastructure logs retain. Those configurations must be reviewed before making broader retention claims.

## Projects and local files

Artiflex projects use the versioned `artiflex-project` JSON format documented in [`project-format.md`](project-format.md). Users explicitly save a project to their device and select a local file to reopen it. Project validation and migration run before imported data replaces active project state.

When a project is opened, the user can choose to replace the active project with the complete project or selectively restore supported sections into the current project. Selective restore merges the selected sections and validates the complete merged project before applying any change. Appearance can be restored separately from project metadata and other sections. If the selection would leave invalid references, restore is rejected without partially changing active project state. Unsupported formats are rejected.

A project may contain dataset records, custom field names, selected subjects, notes, artifact content, skill instructions, editable Prompt Baseline material and updates, Caching snapshots, appearance settings, run outputs, and review decisions. A saved project is not protected storage; inspect and protect it before sharing. Plaintext API credentials must not be included in project files. The importer rejects credential fields and common credential-bearing strings. Version 9 supports optional encrypted API-key storage; its envelope is validated and contains ciphertext rather than a plaintext key. Treat project files as private and protect any password used to encrypt them.

## Datasets and artifacts

Datasets are managed locally in the browser and can be created or imported from CSV. Fields have stable IDs, editable display names, and supported types. Users can edit records, filter the dataset, select one or more records as workflow subjects, and add collection notes. The sample dataset is synthetic and intended only to demonstrate mechanics.

The reserved `__artiflex_index` is generated row-order metadata, not a stable record identifier or join key. `__artiflex_subject_id` is a derived system field for subject groups; it is distinct from source record IDs and imported fields.

Artifacts can be added by pasting text or selecting local `.txt`, `.md`, `.csv`, or `.json` files. An HTTP address may be saved as a reference, but Artiflex does not fetch it. PDF and DOCX text extraction are not implemented. Only content included in a confirmed AI request is sent through the API to the provider.

## Skills and compositions

Skills are project-owned instructions and configuration, not application code. Their input bindings can select dataset fields, selected source records, collection notes, and artifacts. Structured outputs are validated in the browser. Skills can be imported or exported as user-controlled files. Skill instructions, schemas, observation types, composition definitions, records, artifacts, snapshots, and model responses are untrusted content and must not be treated as application commands.

Sequential compositions pass earlier outputs to subsequent steps as structured input and assembled prompt data. Those outputs are treated as untrusted AI-generated content. Verify composed-run behavior with current smoke and API tests before relying on it for a particular workflow.

AI assistance for observation types suggests values only for editable name, purpose, and details fields. The user reviews suggestions before applying them; assistance does not change an observation type's ID, multiplicity, or other skill settings. The optional editable Prompt Baseline can be included separately in an observation-type assistance request only when the user explicitly selects that option; this is independent of Caching snapshots.

## Prompt Baseline and Caching

Artiflex has two related but distinct mechanisms:

1. **Editable Prompt Baseline:** project-owned stable text and an ordered update ledger, managed on the Baseline tab.
2. **Caching workflow:** named, project-local snapshots captured from Dataset, Subjects, Artifacts, the editable Prompt Baseline, or Skills. Caching controls whether captured snapshots are included in skill-run prompts and in what order.

The editable Baseline and its Caching snapshot are not the same content object. Capturing a Baseline creates a snapshot of its current ID, name, stable text, hash, ordered updates, and precedence setting. Later edits to the Baseline do not change the captured snapshot until the user refreshes that Caching component. Baseline is snapshot-only in Caching: it has no live-content toggle, and the current editable Baseline is not automatically appended to ordinary skill runs. To use the Baseline in an ordinary skill-run prompt, capture it on the Baseline tab and ensure its component is included on the Caching tab while Caching is enabled.

### Capturing Caching components

Caching components are explicit snapshots. Artiflex does not create one automatically merely because the user edits a tab.

- **Dataset:** capture the current filtered and searched view, or capture the complete dataset. The snapshot retains its capture scope.
- **Subjects:** capture selected source record IDs, corresponding records and fields, selected Artiflex Subject IDs, label-field information, and collection notes.
- **Artifacts:** capture any selected combination of existing artifacts.
- **Prompt Baseline:** capture the current editable Baseline, including its ordered update ledger. It can be refreshed after the editable Baseline changes.
- **Skills:** capture any selected combination of skills that already exist.

Components remain in browser memory until the user explicitly saves the project. They are not stored on the Artiflex or MaxFlex host.

### Component order, inclusion, and live content

Included components are assembled first in the project's configured order. Enabled live Dataset, Subjects, Artifacts, and Skills content follows them, then run-specific instructions and other request material. The Prompt Baseline snapshot appears at its configured position among the snapshots; the current editable Baseline is not appended as live content. Baseline inclusion, component exclusions, and live-content inclusion are independent controls. A snapshot and live content may overlap; Artiflex does not silently deduplicate them.

Excluding a Baseline snapshot component or disabling Caching omits that snapshot from ordinary skill-run prompts. It does not delete the editable Prompt Baseline from the Baseline tab. Conversely, deactivating the editable Baseline does not itself remove or deactivate a previously captured Caching snapshot; the snapshot remains governed by Caching inclusion, exclusion, order, and refresh controls.

### Snapshot freshness and provider caching

Freshness describes local comparison of a saved snapshot with its source and capture scope. For a Baseline component, freshness compares the snapshot with the current editable Baseline. Refreshing a component updates the local snapshot for future requests; it does not directly create, update, or clear a provider cache entry. OpenAI prompt caching reuses matching cumulative prefixes, not separately addressable Artiflex components. Cache hits and savings are not guaranteed, and aggregate provider usage does not prove that any particular component was reused.

For supported GPT-5.6-and-later OpenAI models, Artiflex uses Responses API explicit prompt-cache controls and the documented `30m` TTL. The API reports provider usage counts where available. A short prefix may not meet the provider's cacheable minimum; request settings, exact content, routing, and cache availability also affect reuse.

## Project appearance and Customize Styles

**Customize Styles** lets the user describe a desired look in natural language. Users do not have to configure individual effect controls. The user can review the request and, before sending, choose whether bounded semantic project context is included.

The current effective appearance is sent as context: the current project's saved appearance, or the deployed application defaults if the project has no override. On retry, the current unaccepted preview becomes the effective appearance for the next request. Image URLs in the current appearance recipe are resubmitted on retries as image inputs, along with URLs extracted from the new direction. This lets the AI build on an existing preview rather than silently restarting from defaults.

The AI returns a constrained appearance suggestion: supported palette tokens and a declarative `background_recipe`. Artiflex validates the provider response, previews it in the browser, and saves it to the current project only when the user accepts it. The user can retry, cancel, or reset to the currently deployed defaults. Opening or switching projects applies only that project's appearance, or the defaults if it has no override. Appearance is never stored as a browser-wide preference.

The palette has dedicated primary, secondary, and tertiary roles, each with base, hover, and soft tokens. When a user names multiple colors, the style-assistance instructions tell the AI to retain them as distinct, noticeable palette roles rather than collapsing them into one dominant hue or relegating requested colors to barely visible tints. Success, warning, and danger tokens keep their semantic meanings and must not be used as decorative substitutes. Visible color coverage depends on the application stylesheets using those tokens; distinct saved values alone do not guarantee prominence throughout the interface. Review the preview. Contrast and suitability are not an accessibility certification.

### Background recipes and images

A background recipe is an ordered list of application-supported layers. Supported types are `aurora`, `drifting_gradient`, `particles`, `falling_stars`, `rain`, `snow`, and `image`. Supported layouts are `background`, `floating_icons`, and `tile`. Supported settings include `speed` (`slow`, `medium`, `fast`), `density` (`sparse`, `balanced`, `dense`), `brightness` (`muted`, `balanced`, `vivid`), `direction` (`vertical`, `diagonal`, `horizontal`), `scale` (`small`, `medium`, `large`), `opacity` (`low`, `medium`, `high`), and ordered six-digit hexadecimal `colors`. Recipes are limited to eight layers.

The model can compose supported layers and choose settings based on the natural-language request. Density affects repeated visual elements where applicable; tile mode uses repeated placement. Artiflex uses application-authored browser code to render the recipe. Provider output is never treated as CSS, selectors, HTML, JavaScript, or executable animation code. Effects remain behind interface content, must not obscure controls or the fixed privacy disclosure, and must honor `prefers-reduced-motion` by disabling or reducing motion. The AI cannot invent a renderer capability Artiflex does not implement.

A user may include a publicly accessible HTTPS image URL in the style direction. Artiflex extracts and previews submitted image references. To let the AI interpret an image, the API sends the URL as an image input; it does not fetch or proxy the image. An image recipe layer may refer only to a URL submitted with that request. References with embedded credentials or disallowed local/private hosts are rejected. The browser may load an accepted image directly from its host; that host may receive the request and associated network metadata. Use only public image URLs appropriate to send to the provider and display in the browser. The deployed Content Security Policy must allow intended HTTPS image sources while keeping script, style, and connection policies restrictive.

The natural-language request can be open-ended, but exact visual results, aesthetic quality, image availability, and a particular percentage of screen area for a requested color cannot be guaranteed. Review each preview before accepting it. Provider terms, billing, retention, and data-handling practices apply to the direction, current appearance, selected project context, image inputs, and other transmitted content.

## Results, charts, and joins

AI responses are represented as response records and may retain raw output alongside parsed output and usage metadata, depending on project settings. Structured output can be incomplete or invalid; validation is a diagnostic, not proof that a response is correct. Human review status and notes are separate from AI output. Results must not be treated as approved or applied automatically.

The current chart renderer provides a bar-chart view over source, response, or joined data. The UI does not currently implement distribution or time-series charts. Explicit joins allow users to select datasets, key fields, and join type; diagnostics report unmatched rows and duplicate matches. Join results are exploratory and do not establish that fields with similar values have the same meaning. The standard current observation join matches response `subject_id` to input `__artiflex_subject_id`. Legacy V4 observation arrays remain legacy history and are not current scalar subject links.

Evidence-link support is not yet connected to the result display. AI-provided citations or artifact references should be treated as unverified unless independently checked against source material.

## Security and demo limitations

- Use synthetic, fictional, or appropriately de-identified demo material. Do not use real student records, regulated documents, or confidential data in this prototype.
- Artiflex is not a production system, a FERPA or other compliance certification, or a substitute for professional review.
- Browser-memory storage and local project files do not make content appropriate for sensitive or regulated use.
- CORS is not authentication or abuse prevention. Public API routes require server-side validation, request limits, rate controls, safe errors, and infrastructure logging review.
- A local project file may contain artifacts, prompts, data, snapshots, formulas, identity mappings, appearance settings, and AI outputs. Protect it before sharing.
- Plaintext API keys must not be placed in URLs, analytics, request history, project files, or error details. Encrypted-key options require protecting the project password. Do not log outbound BYOK request bodies.
- Provider requests transmit selected content through the MaxFlex API. Browser-side project storage does not mean confirmed AI requests remain local.
- PDF/DOCX extraction, arbitrary artifact URL fetching, local response caching, production identity and access controls, and production-grade security controls are outside the current implementation.
- Provider terms, pricing, cache retention, and data-handling practices apply when content is sent to a provider.

## Deployment and maintenance

The public application source belongs under:

```text
/var/www/caseylide.com/toolcrib/artiflex/
```

The separate MaxFlex API is hosted under:

```text
/var/www/api.maxflex.ai/
```

Set `ARTIFLEX_BYOK_ALLOWED_ORIGIN` in `/var/www/.env.master` to the exact HTTPS origin serving Artiflex, for example `https://caseylide.com`. Keep API secrets out of the Artiflex document root and browser code.

The application is organized by feature under `assets/js/` and `assets/css/`. Keep `main.js` focused on startup and stylesheets separated by component and feature. Project-format changes require an explicit format-version and migration policy; do not silently reinterpret or downgrade unknown project versions. Version 9 adds the persisted Caching source type `baseline`; older application versions that do not recognize that source may reject projects containing such a component. Deploy compatible browser code, migration behavior, and format documentation together.

The browser smoke-test harnesses use isolated Artiflex pages and synthetic project data. Style-assistance tests should mock provider responses; background-effect tests should intercept image sources and must not contact live providers or remote image hosts. Caching and Baseline tests should verify capture, freshness, refresh, ordering, inclusion, exclusion, disabled Caching, and ordinary skill-run prompt inclusion. These tests do not certify live API or provider integration, CORS, rate limiting, provider caching, or infrastructure logging. Use an isolated API test setup and fake providers for API verification. Do not use production rate-limit storage, real provider keys, real student data, or live provider requests for routine tests.

The API's public routes are subject to request limits and rate limiting. CORS is not authentication or abuse prevention: non-browser clients can call public routes directly. Review API, web-server, proxy, monitoring, and hosting configuration before enabling or changing public routes. Verify the background renderer and image display under the deployed CSP without broadly weakening it.

## Name

Artiflex is a coined product name inspired by Latin *artifex*, meaning a maker, artisan, or skilled practitioner, and the product's emphasis on flexibility. This README does not assert trademark, domain, or commercial-name clearance.