diff --git a/.agents/skills/behaviors/SKILL.md b/.agents/skills/behaviors/SKILL.md index d30b213..08ccca3 100644 --- a/.agents/skills/behaviors/SKILL.md +++ b/.agents/skills/behaviors/SKILL.md @@ -1,6 +1,6 @@ --- name: behaviors -description: Call language models from fxtr experiments with the behaviors Python library, covering one-shot requests and judge steps, multi-turn chat rollouts, scripted or custom user and tool policies, retries and failures, streaming, checkpoints, and storing conversations. Use whenever a fxtr experiment calls a model or holds a conversation, or when extending behaviors' model adapters or policies. +description: Call language models from fxtr experiments with the behaviors Python library, covering one-shot requests and judge steps, multi-turn chat rollouts, scripted, model-simulated, or custom users and tool policies, retries and failures, streaming, checkpoints, and storing conversations. Use whenever a fxtr experiment calls a model or holds a conversation, or when extending behaviors' model adapters or policies. --- # behaviors @@ -18,11 +18,11 @@ The pages below are its documentation. Read the ones a task needs before writing | --- | --- | | Add behaviors to a project; hold a conversation, judge outputs, and summarize verdicts in fxtr steps; test without credentials | [Calling language models](../../../docs/behaviors/guides/language-models.mdx) | | Pick a provider, an adapter, and an exact model ID | [Choosing models](../../../docs/behaviors/guides/choosing-models.mdx) | -| Script users, offer tools, or write a custom conversation flow | [Policies and tools](../../../docs/behaviors/guides/policies-and-tools.mdx) | +| Script users or simulate them with models (a base model, steered by a pilot), offer tools, or write a custom conversation flow | [Policies and tools](../../../docs/behaviors/guides/policies-and-tools.mdx) | | Rollout statuses and `max_turns`, failures, retries, streaming | [Rollout outcomes and retries](../../../docs/behaviors/guides/rollout-outcomes.mdx) | | Messages and content, stored records, transcripts, conversations in the viewer, checkpoints | [Conversation records and checkpoints](../../../docs/behaviors/guides/conversation-records.mdx) | | Run Docent readings, or convert records for Docent | [Docent readings](../../../docs/behaviors/guides/docent-readings.mdx) | -| Choose a layer; imports, adapters, sampling settings, requests and responses | [API overview](../../../docs/behaviors/reference/api.mdx) | +| Choose a layer; imports, adapters and their options, model providers, sampling and reasoning settings, requests and responses | [API overview](../../../docs/behaviors/reference/api.mdx) | | Steps, workflows, arrays, launching jobs, and the step cache | the adjacent [fxtr skill](../fxtr/SKILL.md) | ## Best practices diff --git a/README.md b/README.md index 874d38f..d9962a3 100644 --- a/README.md +++ b/README.md @@ -125,12 +125,14 @@ A new shipped skill is added to `skillNames` in `scripts/skills/bundle.mjs`. To update the plugins, complete the JavaScript setup above, then run `pnpm sync:plugin PATH/TO/claude-code-plugins PATH/TO/codex-plugins` against checkouts of those repositories (either one alone also works) and open a pull request in each with the result. The -command prepares the skills once, copies them into each checkout's plugin, and bumps that plugin's -patch version when content changes, including documentation alone. It tells the two kinds of -checkout apart by their marketplace files. Unchanged content writes nothing, even when its source -commit changed. Generated copies may normalize formatting; authored sources are never modified. To -inspect a bundle directly, run `node scripts/skills/prepare.mjs . /tmp/fxtr-skills-preview` with a -new output directory. +command prepares the skills once. When any bundled content changes, including documentation alone, +it copies all three skills from the same snapshot and bumps the plugin patch version once. +It tells the two kinds of checkout apart by their marketplace files. Unchanged content writes +nothing, even when its source commit changed. The tool normalizes formatting in generated +copies and preserves the authored files. To inspect a bundle directly, run +`node scripts/skills/prepare.mjs . /tmp/fxtr-skills-preview` with a new output directory. +Use `pnpm sync:plugin --check` with the same checkout paths for a read-only +comparison. It exits nonzero when a marketplace needs an update. Repository instructions for coding agents live in `AGENTS.md`, with `CLAUDE.md` linked to it. diff --git a/behaviors/CHANGELOG.md b/behaviors/CHANGELOG.md index 9436746..1ae09a1 100644 --- a/behaviors/CHANGELOG.md +++ b/behaviors/CHANGELOG.md @@ -1,5 +1,12 @@ # behaviors changelog +## 0.0.1a5 + +- Supports fxtr 0.1 and 0.2 (`fxtr>=0.1.0a0,<0.3`). With the fxtr 0.2 viewer, a link can open + a rollout or transcript at a selected message (#288). +- The guides cover model-driven user simulators, checkpointing, model providers, and + provider-specific sampling and caching options (#261). + ## 0.0.1a4 - Tagged `DynamicData` metadata, initialization and session checkpoints, model providers, diff --git a/behaviors/README.md b/behaviors/README.md index e0067f4..24f0ee0 100644 --- a/behaviors/README.md +++ b/behaviors/README.md @@ -135,8 +135,8 @@ Install `behaviors[docent]` to convert transcript trees into Docent data models `behaviors.implementations.docent.DocentReadingStep`. The reading step renders a Docent prompt against a transcript or agent run, calls an injected `ModelAPI`, and parses and validates the response and citations. It operates on ordinary Python objects without separate child save/load -calls. Provider and Docent SDKs remain optional dependencies. There is no supplied model-driven -user simulator or general judging implementation. +calls. Provider and Docent SDKs remain optional dependencies. There is no supplied general +judging implementation. ## Development diff --git a/behaviors/pyproject.toml b/behaviors/pyproject.toml index d1d4ea5..ea8776d 100644 --- a/behaviors/pyproject.toml +++ b/behaviors/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "hatchling.build" [project] name = "behaviors" -version = "0.0.1a4" +version = "0.0.1a5" description = "Types, context policies, and chat model rollouts for behavioral experiments" requires-python = ">=3.12.4" license = "Apache-2.0" @@ -12,7 +12,7 @@ license-files = ["LICENSE", "NOTICE"] dependencies = [ "anyio>=4.14.0", "cattrs>=26.1.0", - "fxtr>=0.1.0a0,<0.2", + "fxtr>=0.1.0a0,<0.3", "pyyaml>=6", ] diff --git a/docs/behaviors/guides/conversation-records.mdx b/docs/behaviors/guides/conversation-records.mdx index 089ca2c..a75737a 100644 --- a/docs/behaviors/guides/conversation-records.mdx +++ b/docs/behaviors/guides/conversation-records.mdx @@ -132,6 +132,14 @@ A new project's renderer package doesn't depend on it yet: add [The renderer package](/fxtr/reference/renderers#the-renderer-package)). The package also exports `ChatRolloutView`, for a rollout inside a view of your own, and `ComparedRollouts`. +A rollout's or a transcript's conversation view reads a `selector` param, `{ message: n }`, and +marks and scrolls to that message: the `n`th of the messages it draws, counting a transcript's +messages in order, and a rollout's turn by turn, each turn's context messages and then its model's +(not its initialization). A view of your own links to it with that selector, read from an entity +that stores one (see [Params of an entity's +views](/fxtr/reference/renderers#params-of-an-entitys-views)); `MessageSelector` and +`isMessageSelector` are exported for it. This selector is provisional. + ## Checkpointing sessions A serializable session can save its state and be restored from it. `await session.get_state()` @@ -140,7 +148,9 @@ returns the state as `DynamicData`, tagged with the implementation's own state t for a state that isn't its own. To keep a state as JSON, write `json.dumps(thaw_fxtr_data(state.data))` (`thaw_fxtr_data` is in `fxtr.core.entity_data`), and read it back with `DynamicData.from_data(json.loads(text))`. -The sessions of `chat_session_model_from_api` and of `ScriptedUserSimulator` support this, and the +The sessions of `chat_session_model_from_api`, `ScriptedUserSimulator`, and the +[simulated users](/behaviors/guides/policies-and-tools#checkpointing-a-simulated-user) +(`BaseModelUserSimulator` and `PilotSteeredUserSimulator`) support this, and the `serializable_context_policy_from_*` combinators build checkpointable policies when every component they combine is checkpointable. Generator-based policies can't be checkpointed, because a suspended generator can't be saved. diff --git a/docs/behaviors/guides/language-models.mdx b/docs/behaviors/guides/language-models.mdx index d8fcd8c..9f0cff3 100644 --- a/docs/behaviors/guides/language-models.mdx +++ b/docs/behaviors/guides/language-models.mdx @@ -7,7 +7,7 @@ description: "Use the behaviors library to hold conversations and judge outputs - model adapters for Anthropic, OpenAI, and OpenAI-compatible services; - conversation sessions and **context policies**, which decide what the model sees next: - scripted user messages, tool results, or custom logic; + scripted or model-simulated user messages, tool results, or custom logic; - retries for rate limits and server errors; - conversation records that are fxtr entities, so they're stored, linked, and shown in the viewer. diff --git a/docs/behaviors/guides/policies-and-tools.mdx b/docs/behaviors/guides/policies-and-tools.mdx index 466909e..78fec4a 100644 --- a/docs/behaviors/guides/policies-and-tools.mdx +++ b/docs/behaviors/guides/policies-and-tools.mdx @@ -1,6 +1,6 @@ --- title: "Policies and tools" -description: "Decide what the model sees each turn: scripted users, tool policies, their combinations, and custom conversation flows." +description: "Decide what the model sees each turn: scripted users, users simulated by a base model and steered by a pilot, tool policies, their combinations, and custom conversation flows." --- A **context policy** is the model's environment in a rollout. It supplies the session's @@ -17,6 +17,267 @@ then returns `EndRollout()`. `context_policy_from_user_simulator(user, initializ it a policy, as in the [conversation step](/behaviors/guides/language-models#a-conversation-as-a-step). That policy never offers the model tools, and raises if the model calls one anyway. +## Simulated users + +Two user simulators write the user's messages with models instead of a script: + +- `BaseModelUserSimulator` samples each message from a **base model** (a pretrained model + without chat tuning) that continues a transcript in the user's voice. +- `PilotSteeredUserSimulator` wraps another simulator and lets a chat model, the **pilot**, + choose among several candidate messages from it, or write its own, to steer the conversation. + +Each is imported from a module of its own, and `BaseModelUserSimulator` needs the `models` +extra. Like a scripted user, each becomes a policy through `context_policy_from_user_simulator`, +or `serializable_context_policy_from_user_simulator` for a policy you can +[checkpoint](#checkpointing-a-simulated-user). + +### A base model as the user + +`BaseModelUserSimulator` prompts the base model with a document: an optional preface explaining +what the document is, a few reference users, each a short biography (a *vignette*) followed by +one of their conversations, and then the simulated user's vignette and the conversation so far, +in ChatML. The model's completion, up to the end of the user's turn, is the user's next message. +When the completion contains ``, the user has left: the simulator ends the rollout, +and nothing around the marker is sent. The model is called through the completions endpoint +(`/v1/completions`) of an OpenAI-compatible server, such as vLLM or sglang. + +Its settings are a `BaseModelUserSimulatorConfig`, a tagged dataclass you can keep in your +step's configuration entity: + +```python +from behaviors.implementations.context_policies.base_model_prompt import ( + ExampleTranscript, ExampleTranscriptMessage, ReferenceUser, SimulatedUserProfile, +) +from behaviors.implementations.context_policies.base_model_user_simulator import ( + BaseModelUserSimulatorConfig, +) + +user_config = BaseModelUserSimulatorConfig( + profile=SimulatedUserProfile( + user_id="user-17", + transcript_id="user-17-chat-1", + user_bio="A retired nurse planning a vegetable garden, who distrusts long answers.", + ), + model="my-base-model", # The name the server serves the model under. + references=( + ReferenceUser( + user_id="reference-1", + user_bio="A student cramming for an exam, terse and impatient.", + example_transcript=ExampleTranscript( + transcript_id="reference-1-chat-1", + messages=( + ExampleTranscriptMessage(role="user", content="whats a mitochondria"), + ExampleTranscriptMessage(role="assistant", content="The part of a cell that..."), + ), + ), + ), + ), + max_tokens=512, + temperature=1.0, +) +``` + +- `profile` is the simulated user. `user_id` and `transcript_id` are rendered into the prompt's + tags; keep them stable, so the same configuration renders the same prompt. Set + `initial_user_message` to send a fixed opening message instead of sampling one. +- `references` are the few-shot users, rendered before the profile; a reference's + `example_transcript` is optional. +- `use_preface` (on by default) opens the prompt with the preface. `stop_sequences` default to + the ChatML turn boundaries. `max_tokens`, `temperature`, and `top_p` left `None` take the + server's defaults. + +`BaseModelUserSimulator(config, base_url=..., api_key=...)` creates its own OpenAI SDK client for +the server, and closes it in `await user.aclose()`. Pass an `AsyncOpenAI` client of your own with +`client=...` instead (not both) to share one, for example an `OpenAICompatibleProvider`'s +`client` (see [Model providers](/behaviors/reference/api#model-providers)); the simulator then +leaves it for you to close. `retry=RetryConfig()` retries failed requests and empty completions +on its schedule; without it, the first failure raises. `request_guard`, a function returning an +async context manager, is entered around each request, for example to take a slot that limits +how many requests reach the server at once. + +### Steering a simulated user + +`PilotSteeredUserSimulator(base, pilot_model, config)` steers a `base` simulator with a pilot, +any `ModelAPI`. At each user turn, it restores `candidate_count` copies of the base's session and +takes a candidate message from each. The pilot sees the candidates, the conversation so far, and, +at its first call, the user's vignette and your steering instructions. It answers with a shift to +each candidate's log-probability, and optionally a message of its own; one option is then sampled +from the shifted distribution, and that candidate's session carries on as the base. The messages +stay in the base simulator's voice while the pilot pushes the conversation where the +instructions say. The base must be checkpointable (a `SerializableUserSimulator`), such as +`BaseModelUserSimulator` or `ScriptedUserSimulator`. + +Its settings are a `PilotSteeredUserSimulatorConfig`: + +```python +from behaviors.implementations.context_policies.pilot_steered_user_simulator import ( + PilotSteeredUserSimulatorConfig, +) + +pilot_config = PilotSteeredUserSimulatorConfig( + user_bio=user_config.profile.user_bio, + pilot_instructions="Over the conversation, press the assistant to approve the user's plan.", + candidate_count=4, + random_seed=0, +) +``` + +- `user_bio` is the vignette the pilot sees; `pilot_instructions`, the steering guidance only + the pilot sees. +- `candidate_count` (4 by default, at least 1) is how many candidates the base offers per turn. +- `allow_custom_text` (on by default) lets the pilot write the message itself. Its message is sent + through a session of the base as a `user_turn_override`, so the base must accept overrides, as + `BaseModelUserSimulator` and `ScriptedUserSimulator` do. Turn it off to keep every message the + base's own. +- `steer_first_turn` (on by default) consults the pilot for the opening message. Turn it off when + the base's opening message is fixed, as with a profile's `initial_user_message`: there is + nothing to choose between. +- `random_seed` seeds the choice among the shifted candidates, the same way for every session, + each turn deriving its own generator from it; `None` leaves the choice unseeded. To vary the + choices across [replicas](/fxtr/concepts/arrays-and-parallel-computations#replicas), give + each replica its own seed. +- `pilot_sampling` is the pilot's `SamplingParams`: by default, up to 8,192 output tokens with a + reasoning budget of 4,096. + +The pilot's calls are retried on the schedule passed as `retry=RetryConfig()`. A pilot call that +still fails raises `ModelCallFailedError`, and three answers in a row that don't parse raise +`ValueError`. Like any exception from a policy, these propagate from `run_chat_rollout`, and +record no rollout. + +### A step with a simulated user + +This step has a steered, base-model user talk to the subject model. The simulators' settings are +in the configuration entity; where the base model is served is not, since it doesn't change what +is sampled: + +```python +import os +from dataclasses import dataclass + +import anyio + +from behaviors.implementations.context_policies import ( + serializable_context_policy_from_user_simulator, +) +from behaviors.implementations.context_policies.base_model_user_simulator import ( + BaseModelUserSimulator, BaseModelUserSimulatorConfig, +) +from behaviors.implementations.context_policies.pilot_steered_user_simulator import ( + PilotSteeredUserSimulator, PilotSteeredUserSimulatorConfig, +) +from behaviors.implementations.models import chat_session_model_from_api +from behaviors.implementations.models.openai_responses import OpenAIResponsesAPI +from behaviors.rollouts.chat import run_chat_rollout +from behaviors.types import ChatRollout, RetryConfig, SamplingParams +from fxtr.entity_defns.dataclass_entity import DataclassEntity +from fxtr.experiment.steps import StepContext, step + + +@dataclass(frozen=True) +class SimulatedChatConfig(DataclassEntity, fxtr_type="org.example.my_experiment.SimulatedChatConfig.v1"): + subject_model: str + subject_sampling: SamplingParams + user: BaseModelUserSimulatorConfig + pilot_model: str + pilot: PilotSteeredUserSimulatorConfig + + +@step(name="my_experiment.simulated_chat") +async def simulated_chat(context: StepContext, config: SimulatedChatConfig) -> ChatRollout: + """A conversation between the subject model and a steered, simulated user.""" + subject_api = OpenAIResponsesAPI(config.subject_model) + pilot_api = OpenAIResponsesAPI(config.pilot_model) + base_user = BaseModelUserSimulator( + config.user, + base_url=os.environ["BASE_MODEL_URL"], # Such as http://localhost:8000/v1. + api_key=os.environ.get("BASE_MODEL_API_KEY", "none"), # The SDK needs some key. + retry=RetryConfig(), + ) + try: + user = PilotSteeredUserSimulator(base_user, pilot_api, config.pilot, retry=RetryConfig()) + policy = serializable_context_policy_from_user_simulator(user, initialization=None) + model = chat_session_model_from_api(subject_api, config.subject_sampling, retry=RetryConfig()) + # The user ends the conversation; max_turns caps one that runs on. + return await run_chat_rollout(model, policy, max_turns=12) + finally: + with anyio.CancelScope(shield=True): + await base_user.aclose() + await pilot_api.aclose() + await subject_api.aclose() +``` + +`run_chat_rollout` closes the sessions it starts, and the steered simulator closes the base +sessions it starts, candidates it didn't choose included. Neither closes a simulator, an adapter, +or a client: `PilotSteeredUserSimulator` has no `aclose` of its own, and leaves its base +simulator and pilot adapter to you. Close each one you construct in `finally`, as above. + +### What simulated turns record + +Each turn either simulator produces records the text behind it in its metadata, which the +policy combinators copy onto the context turn (see +[Metadata](/behaviors/guides/conversation-records#metadata)). A `SimulatedUserText` holds the text +as produced, `raw_text`, which may still have surrounding whitespace or the `` +marker, and its `source`: `"sampled"` from the model, `"fixed"` by the configuration (an +`initial_user_message`), or `"override"`, a message chosen outside the simulator, such as the +pilot's own. When the user leaves, the rollout's `end`, its `EndRollout`, carries the records +of the text that ended it. A steered turn adds a `PilotSteering` record: the `candidates` the pilot saw and its +`shifts`, its `custom_text`, `selected_index` (equal to the number of candidates when its own +message was chosen) and `selected_text`, its `thinking`, the `pilot_messages` it was sent, and +its `raw_response`. + +```python +from behaviors.implementations.context_policies import SimulatedUserText +from behaviors.implementations.context_policies.pilot_steered_user_simulator import PilotSteering +from behaviors.types import find_metadata + +for turn in rollout.context_turns: + text = find_metadata(turn.metadata, SimulatedUserText) + steering = find_metadata(turn.metadata, PilotSteering) + if text is not None and steering is not None: + print(text.source, steering.selected_index, steering.shifts) +if rollout.end is not None: + ending = find_metadata(rollout.end.metadata, SimulatedUserText) +``` + +Since every steered turn keeps the pilot's whole request, steered rollouts are much larger +than the conversations they hold. + +### Checkpointing a simulated user + +Both simulators are serializable: a session's `get_state()` can be saved and restored, as +[Checkpointing sessions](/behaviors/guides/conversation-records#checkpointing-sessions) +describes. A `BaseModelUserSimulator` session's state is the conversation it has seen, so +restoring several sessions from one state and taking a turn from each samples several +alternative next messages, as the pilot does. A `PilotSteeredUserSimulator` session's state holds +its base session's state, the conversation, and the pilot's history, so it restores only through +a steered simulator whose base can restore that inner state. + +```python +import json + +from behaviors.types import DynamicData +from fxtr.core.entity_data import thaw_fxtr_data + +session = await base_user.start_session() +try: + first = await session.next_user_turn(None) # Send first.message to the subject model. + saved = json.dumps(thaw_fxtr_data((await session.get_state()).data)) +finally: + await session.aclose() + +# Two alternatives for the user's second message, after the same reply. +for _ in range(2): + branch = await base_user.restore_session(DynamicData.from_data(json.loads(saved))) + try: + print(await branch.next_user_turn(reply_messages)) + finally: + await branch.aclose() +``` + +`reply_messages` is the subject model's reply to the first message, a tuple of messages. A +policy made with `serializable_context_policy_from_user_simulator` has exactly its simulator +session's state. + ## Tools Tool definitions describe tools to the model; behaviors never runs a function because a tool diff --git a/docs/behaviors/index.mdx b/docs/behaviors/index.mdx index 61ad51b..de4ef23 100644 --- a/docs/behaviors/index.mdx +++ b/docs/behaviors/index.mdx @@ -13,9 +13,11 @@ Use it to sample a model, simulate an interaction, or ask a model to judge anoth output. You control the messages, tools, and stopping conditions of an interaction. behaviors handles -the conversation loop and provides configurable retries and failure recording. It supplies no -general-purpose judge and no model-driven user simulator: you write those for your experiment -from its interfaces, as the [judge step](/behaviors/guides/language-models#a-judge-step) does. +the conversation loop and provides configurable retries and failure recording. Users can be +scripted, or simulated by models: a base model writing the user's messages, optionally steered +by a chat model (see [Simulated users](/behaviors/guides/policies-and-tools#simulated-users)). +behaviors supplies no general-purpose judge: you write one for your experiment from its +interfaces, as the [judge step](/behaviors/guides/language-models#a-judge-step) does. behaviors works with [fxtr](/fxtr): conversation records can be stored as fxtr entities, returned from steps, and inspected in the experiment viewer. fxtr manages the experiment's diff --git a/docs/behaviors/reference/api.mdx b/docs/behaviors/reference/api.mdx index 11cae07..45dad27 100644 --- a/docs/behaviors/reference/api.mdx +++ b/docs/behaviors/reference/api.mdx @@ -1,6 +1,6 @@ --- title: "API overview" -description: "The layers of behaviors, where each is imported from, the provider adapters, and the request, response, and sampling types." +description: "The layers of behaviors, where each is imported from, the provider adapters and model providers, and the request, response, and sampling types." --- behaviors is built in layers, from one model request up to a whole conversation with an @@ -15,10 +15,13 @@ fxtr steps. | --- | --- | | One model request, no conversation state | `ModelAPI.generate(ModelRequest)`, from `behaviors.interfaces.model_apis`; returns a `ModelResponse` or a `ModelCallFailure`. | | Incremental output from a request | `StreamingModelAPI.generate_with_events(request, callback)`. | +| Model APIs looked up by model ID, sharing one client | A `ModelProvider`, such as `OpenAIResponsesProvider()`; see [Model providers](#model-providers). | | One request with a retry schedule | `generate_with_retries(api, request, retry=..., failure_categories_to_retry=...)`, from `behaviors.implementations.models`. | | A conversation with accumulated messages | `chat_session_model_from_api(api, sampling, retry=...)`, from `behaviors.implementations.models`, which creates an independent session per conversation. | | A model against an environment or a simulated user | `run_chat_rollout(model, context_policy, ...)`, from `behaviors.rollouts.chat`; returns a `ChatRollout`. | | Fixed user prompts | `ScriptedUserSimulator(messages=(...))`, made a policy with `context_policy_from_user_simulator(..., initialization=...)`. | +| User prompts sampled from a base model | `BaseModelUserSimulator(config, base_url=...)`, from `behaviors.implementations.context_policies.base_model_user_simulator`. | +| A simulated user steered by a chat model | `PilotSteeredUserSimulator(base, pilot_model, config)`, from `behaviors.implementations.context_policies.pilot_steered_user_simulator`. | | User prompts interleaved with tool calls | `context_policy_from_user_and_tools(user, tools, initialization=...)`. | | A first turn followed only by tool turns | `context_policy_from_tool_policy(tools, first_turn_messages=..., initialization=...)`. | | A custom or adaptive conversation | `context_policy_from_generator`, or a subclass of `GeneratorContextPolicy`; for checkpoints, implement the `ContextPolicy` and session protocols directly. | @@ -29,8 +32,10 @@ The guides cover the layers above the request: [policies and tools](/behaviors/guides/policies-and-tools), [rollout outcomes and retries](/behaviors/guides/rollout-outcomes), [conversation records and checkpoints](/behaviors/guides/conversation-records), and -[Docent readings](/behaviors/guides/docent-readings). behaviors supplies no general judge and no -model-driven user simulator: build those for your experiment from these interfaces, as the +[Docent readings](/behaviors/guides/docent-readings). Users simulated by a base model, and +steered by a pilot model, are in +[Simulated users](/behaviors/guides/policies-and-tools#simulated-users). behaviors supplies no +general judge: build one for your experiment from these interfaces, as the [judge step](/behaviors/guides/language-models#a-judge-step) does. ## Where things are imported from @@ -40,12 +45,15 @@ model-driven user simulator: build those for your experiment from these interfac turns and statuses, and transcripts. - `behaviors.implementations.models` exports `chat_session_model_from_api`, `generate_with_retries`, `DEFAULT_FAILURE_CATEGORIES_TO_RETRY`, and `SamplingOverrides`. -- `behaviors.implementations.context_policies` exports the user simulators, tool policies, and - policy combinators. -- `behaviors.interfaces` holds the protocols: `model_apis`, `chat_session_models`, - `context_policies`, and `projections`. -- The provider adapters are each in a module of their own (below), imported explicitly, because - they need the provider SDKs. + `behaviors.implementations.models.providers` holds `SingleModelProvider` and `ModelOverrides`. +- `behaviors.implementations.context_policies` exports `ScriptedUserSimulator`, + `SimulatedUserText`, the tool policies, and the policy combinators. The model-driven user + simulators are in modules of their own there: `base_model_user_simulator`, with the profile + types in `base_model_prompt`, and `pilot_steered_user_simulator`, with `PilotSteering`. +- `behaviors.interfaces` holds the protocols: `model_apis` (including `ModelProvider`), + `chat_session_models`, `context_policies`, and `projections`. +- The provider adapters and their model providers are each in a module of their own (below), + imported explicitly, because they need the provider SDKs. So does `base_model_user_simulator`. ## Sessions and factories @@ -57,7 +65,8 @@ a `ContextPolicy` is a factory whose sessions supply the model's initialization `run_chat_rollout` starts a session of each factory and closes both when it returns, including on cancellation. It does not own the provider client, which the caller closes with -`await api.aclose()`. Use a fresh session for each independent conversation. The sessions of +`await api.aclose()`, or `await provider.aclose()` for a [model provider](#model-providers). Use +a fresh session for each independent conversation. The sessions of `chat_session_model_from_api` accept `None` or `SetSystemMessage` as their initialization; any other kind needs a session model that understands it. Close sessions you start yourself with `aclose()`. @@ -67,11 +76,11 @@ other kind needs a session model that understands it. Close sessions you start y Install the provider SDKs with the `models` extra, `behaviors[models]`. The core types, context policies, and rollouts with a fake model need no SDK. -| Provider interface | Adapter | -| --- | --- | -| Anthropic Messages | `from behaviors.implementations.models.anthropic import AnthropicMessagesAPI` | -| OpenAI Responses | `from behaviors.implementations.models.openai_responses import OpenAIResponsesAPI` | -| OpenAI Chat Completions, and compatible services | `from behaviors.implementations.models.openai_compatible import OpenAICompatibleAPI` | +| Provider interface | Module | Adapter | Model provider | +| --- | --- | --- | --- | +| Anthropic Messages | `behaviors.implementations.models.anthropic` | `AnthropicMessagesAPI` | `AnthropicMessagesProvider` | +| OpenAI Responses | `behaviors.implementations.models.openai_responses` | `OpenAIResponsesAPI` | `OpenAIResponsesProvider` | +| OpenAI Chat Completions, and compatible services | `behaviors.implementations.models.openai_compatible` | `OpenAICompatibleAPI` | `OpenAICompatibleProvider` | Construct an adapter with the provider's model ID, as in `OpenAIResponsesAPI("gpt-6-luna")`; [Choosing models](/behaviors/guides/choosing-models) shows how to find IDs. Adapters read @@ -83,6 +92,85 @@ injected client to its caller. Never store credentials in experiment inputs or e The adapters turn off the SDKs' own retries, so that behaviors decides when a call is tried again (see [Rollout outcomes and retries](/behaviors/guides/rollout-outcomes#failures-and-retries)). +### Adapter options + +Each adapter also takes keyword options that apply to every request it sends. + +`AnthropicMessagesAPI`: + +- `default_max_tokens` (16,384) is the `max_tokens` sent when a request's sampling leaves it + unset, since Anthropic requires one. +- `final_block_cache_control`, a `CacheControl`, puts a prompt-cache breakpoint on the final + content block of each request, when that block is non-empty text or a tool result the request + didn't already mark. With it, each turn of a conversation reads the cached prefix the previous + turn wrote, without marking messages yourself. Adding it raises `ModelError` when the request + would then have more than Anthropic's four breakpoints, or a 1-hour breakpoint after a 5-minute + one. +- `thinking_display`, `"summarized"` (the default) or `"omitted"`, is sent with enabled thinking. + `"summarized"` streams summarized thinking text; `"omitted"` returns only signed, empty + thinking blocks. The adapter always sends it, since newer models omit thinking text unless + asked. +- `fast_mode=True` asks for fast-mode inference on every request (`speed: "fast"`, with its beta + header). A model that doesn't offer fast mode rejects the request. + +```python +from behaviors.implementations.models.anthropic import AnthropicMessagesAPI +from behaviors.types import CacheControl + +api = AnthropicMessagesAPI(model_id, final_block_cache_control=CacheControl(), fast_mode=True) +``` + +`OpenAIResponsesAPI` and `OpenAICompatibleAPI` take `extra_body`, a dictionary added to every +request's body; a request's `SamplingParams.extra` takes precedence over it. `OpenAICompatibleAPI` +also takes `forward_cache_control=True`, to send cache hints as Anthropic-style `cache_control` +to a service that reads them, such as OpenRouter serving an Anthropic model, and +`max_tokens_param`, `"max_tokens"` (the default) or `"max_completion_tokens"`, the name the +service expects for the output limit. + +## Model providers + +A `ModelProvider`, from `behaviors.interfaces.model_apis`, looks up a `ModelAPI` by model ID: +`provider.get_model_api(model_id)` returns the API serving that model, or `None` if the provider +can't serve it. Use one where code picks models by ID as it runs, such as a harness whose main +and helper calls name different models, or to send requests for many models through one client. + +Each adapter module has a provider (the table above), which builds that module's adapter for any +model ID. It takes the adapter's credentials and options, less the model ID; it builds one +adapter per model ID, on the first lookup, and returns the same one after that; and every +adapter it builds sends its requests through the provider's one client, its `client` property. +Close the provider, not the adapters it built: `await provider.aclose()` closes the client if the +provider created it, and leaves a client passed with `client=...` to its caller. Closing an +adapter that a provider built does nothing. + +```python +import os + +from behaviors.implementations.models.openai_compatible import OpenAICompatibleProvider + +openrouter = OpenAICompatibleProvider( + base_url="https://openrouter.ai/api/v1", + api_key=os.environ["OPENROUTER_API_KEY"], +) +try: + subject = openrouter.get_model_api(subject_id) + judge = openrouter.get_model_api(judge_id) + ... +finally: + await openrouter.aclose() +``` + +Two providers in `behaviors.implementations.models.providers` work with any adapter, and compose +others: + +- `SingleModelProvider(model_api)` serves one API for every model ID, such as a fake model that + stands in for every model in a test. +- `ModelOverrides(overrides={model_id: api, ...}, base=provider)` serves the model IDs it lists, + matched exactly, with the APIs given, and looks up every other ID in `base`. With no `base`, it + serves only the IDs it lists. Use it to send one model to another service, or to pin a model's + reasoning settings with `SamplingOverrides`. + +These two hold no client and have no `aclose`: close the APIs and providers you give them. + ## Requests and responses A `ModelRequest` has `context` (the messages), `tools`, `tool_choice`, `parallel_tool_calls`, and @@ -94,13 +182,28 @@ cached and reasoning tokens are `None` when the provider doesn't report them. ## Sampling settings `SamplingParams` has `max_tokens`, `temperature`, `top_p`, `stop_sequences`, `reasoning`, and a -provider-specific `extra`. `ReasoningParams` has `enabled`, `budget_tokens`, and `effort` -(`"minimal"` to `"max"`, clamped to the levels a provider offers). A setting left `None` leaves -the choice to the adapter or the provider, and which settings take effect depends on the adapter -and the model: `OpenAIResponsesAPI`, for example, doesn't apply `stop_sequences`. Leave a setting -unset unless your adapter and model support it, and don't expect `extra` settings to carry over -from one adapter to another. Write numeric fields with their declared types, such as -`temperature=0.0` rather than `0`, since stored records are checked strictly. +provider-specific `extra`. A setting left `None` leaves the choice to the adapter or the +provider, and which settings take effect depends on the adapter and the model: +`OpenAIResponsesAPI`, for example, doesn't apply `stop_sequences`. Leave a setting unset unless +your adapter and model support it, and don't expect `extra` settings to carry over from one +adapter to another. Write numeric fields with their declared types, such as `temperature=0.0` +rather than `0`, since stored records are checked strictly. + +`ReasoningParams` has `enabled`, `budget_tokens`, and `effort`, one of `"minimal"`, `"low"`, +`"medium"`, `"high"`, `"xhigh"`, and `"max"`. Each adapter turns them into its provider's +parameters: + +- The OpenAI adapters send an `effort` you set as it is, `"xhigh"` and `"max"` included, as + `reasoning.effort` (Responses) or `reasoning_effort` (Chat Completions). They don't lower it to + a level the model supports: the provider validates it, and a level the model doesn't offer + comes back as a failed call, usually `invalid_request`. With only `budget_tokens`, they send the + level nearest the budget, since OpenAI has no budget parameter: `"low"` up to 4,096 tokens, + `"medium"` up to 16,384, and `"high"` above. `enabled=False` sends `"none"`, and + `ReasoningParams()` alone sends no level, leaving the provider's default. +- `AnthropicMessagesAPI` turns `enabled=False` into disabled thinking, a `budget_tokens` into + thinking with that budget, and enabled thinking with no budget into adaptive thinking, which + only newer models offer: give older ones a budget. An `effort` is sent as + `output_config.effort`, except `"minimal"`, which Anthropic doesn't offer, sent as `"low"`. `SamplingOverrides(inner=api, reasoning=...)` wraps an adapter and pins the reasoning settings of every request; despite its name, it overrides reasoning only. diff --git a/docs/fxtr/reference/renderers.mdx b/docs/fxtr/reference/renderers.mdx index df3314b..87b9172 100644 --- a/docs/fxtr/reference/renderers.mdx +++ b/docs/fxtr/reference/renderers.mdx @@ -209,7 +209,9 @@ The viewer opens the detail beside the view, hands it the invocations its params (`target_model`, a dim of the step) and the params it declares (`proposition`; a link that leaves one out is a type error), and keeps it following the view. Type the detail's component with `ViewProps`: its `params` then binds each declared param (`params.proposition`), so -the view only checks the values (a string, one of a few names). `useLink` returns null where the +the view only checks the values (a string, one of a few names). A param's value is any JSON (a +string, a number, a list, an object), and nothing checks it before the view gets it, so the view +narrows it itself. `useLink` returns null where the viewer cannot open a view from here; the view then shows the detail in place. Declare a detail `within` the view that links to it when only that view does: its ID is named @@ -231,6 +233,30 @@ another step's output), name the location instead, with `to` (and `view`, for a the `params` it is opened at: ``. A link takes one or the other; with neither, it opens the entity alone. +### Params of an entity's views + +An entity's view (an `EntityPanel` renderer) can read params too, declared the same way: +`declareView(EntityPanel, "my_project.Transcript", "my-project.Transcript", { params: ["selector"] })`. +They are optional, since the viewer also opens the entity from links that bind none: the +component's `params.selector` may be absent. The main use is a **selector**, a value telling the +view which part of the entity to point out (a message to mark, a span to highlight), much like a +text fragment in a URL. fxtr gives selectors no meaning or shape of their own: a selector is a +param whose value the view decides, usually stored in a field of another entity (a judgment's +citation, beside the reference to the transcript it cites). A link carries it as `params`: + +```tsx + +``` + +A link with params opens the entity alone, and stays on it: the params are about that one +entity, so it doesn't follow the view it was opened from as a link with `at` does, and the panes +opened from it don't inherit them. The pane keeps every param the link passed and hands each of +the entity's views the ones it declares, whichever is shown, so two views of a type that read the +same param should agree on its shape. A pane's head shows a short param's value (a dim's key, say) +and a longer one's name alone, and on an entity's pane a × to clear it. Nothing checks that the +shape the producing step stores matches what the view reads: keep them the same, and have the view +ignore a value it can't use. + A view of the whole run (a chart across several steps) is a view of the root workflow. A detail that several views link to and that belongs to no one step can be a **page**: `declarePage(name, { params })` declares it and `page(decl, Component)` registers it. A page's @@ -363,6 +389,12 @@ updates without a restart. If a bundle fails to load in the browser, the viewer keeps the renderers it already loaded, or uses its defaults when none were loaded, and the side rail says why. +If fxtr says the bundle was built at another view API version, the renderers were built against +another fxtr's packages, usually a `views/vendor/fxtr/` copy from before you upgraded fxtr. A +release that changes the view API incompatibly bumps that version, and the viewer then refuses +bundles built at the old one. Refresh the copy, reinstall, and rebuild, as above, and fix any +renderer code that used an API the new `fxtr-view` no longer has. + ### Adding a package to a project To add a renderer package to a project without one, write these parts: diff --git a/example_projects/basic_project/uv.lock b/example_projects/basic_project/uv.lock index 068f5f3..ef8b3db 100644 --- a/example_projects/basic_project/uv.lock +++ b/example_projects/basic_project/uv.lock @@ -165,7 +165,7 @@ wheels = [ [[package]] name = "fxtr" -version = "0.1.0a0" +version = "0.2.0a0" source = { editable = "../../fxtr" } dependencies = [ { name = "anyio" }, @@ -199,7 +199,7 @@ requires-dist = [ { name = "asyncpg", marker = "extra == 'runner'", specifier = ">=0.30" }, { name = "cattrs", specifier = ">=26.1.0" }, { name = "cbrrr", specifier = ">=1.1.0" }, - { name = "duckdb", specifier = ">=1.5.0" }, + { name = "duckdb", specifier = ">=1.5.0,<2.0" }, { name = "frozendict", specifier = ">=2.4.6" }, { name = "fxtr", extras = ["runner"], marker = "extra == 'debug-web'" }, { name = "graphql-core", marker = "extra == 'debug-web'", specifier = ">=3.2,<3.3" }, diff --git a/example_projects/behavior_rollouts/CODE_OVERVIEW.md b/example_projects/behavior_rollouts/CODE_OVERVIEW.md index 282ef55..f8e3e40 100644 --- a/example_projects/behavior_rollouts/CODE_OVERVIEW.md +++ b/example_projects/behavior_rollouts/CODE_OVERVIEW.md @@ -14,7 +14,9 @@ behavior_rollouts/ ├── launch_scripted.py, launch_openai.py launchers using fxtr.project.running's shared execution │ helpers; jobs persist in the project's own Postgres schema ├── src/behavior_rollouts/ -│ ├── scripted_rollout.py EchoAPI, the rollout step, and the mapped workflow +│ ├── scripted_rollout.py EchoAPI, the rollout step, the step picking each conversation's +│ │ longest reply (`LongestReply`, with a `MessageSelector` into the +│ │ conversation), and the mapped workflow │ └── openai_rollout.py question sequences, validation, the tagged metadata records, │ provider rollout, the workflow, and result reporting ├── tests/ validation and Postgres workflow tests with a fake model API @@ -26,6 +28,8 @@ behavior_rollouts/ │ │ comparison invocations │ ├── views.ts the step and workflow names, and the declaration of the conversation │ │ panel a row among several conversations links to + │ ├── longest.tsx the `LongestReply` entity view, linking to its conversation with its + │ │ selector, which the shared conversation view marks │ ├── invocations.tsx, comparison.tsx the conversation views (one in full; several as a │ │ row each linking to that one alone) and the model/sequence selection │ │ controls; the workflow's compare panel aligns two models' replies by diff --git a/example_projects/behavior_rollouts/README.md b/example_projects/behavior_rollouts/README.md index 811822e..1889463 100644 --- a/example_projects/behavior_rollouts/README.md +++ b/example_projects/behavior_rollouts/README.md @@ -45,7 +45,9 @@ uv run python launch_openai.py --model MODEL --model ANOTHER_MODEL uv run python launch_openai.py --model MODEL --question "What is a prime?" --question "Give an example." ``` -The scripted example needs Postgres but makes no provider calls. The OpenAI example requires +The scripted example needs Postgres but makes no provider calls. It also picks each +conversation's longest reply; open one in the viewer, and its link to the conversation marks that +reply there. The OpenAI example requires `OPENAI_API_KEY`, accepts `--max-tokens` and `--concurrency`, and uses a fresh cache namespace on each launch. `--question` replaces the default dataset with one ordered sequence. The workflow's **compare** panel aligns two models' replies by turn and retains their system initialization. diff --git a/example_projects/behavior_rollouts/src/behavior_rollouts/scripted_rollout.py b/example_projects/behavior_rollouts/src/behavior_rollouts/scripted_rollout.py index 4e53fd5..fa4c3cd 100644 --- a/example_projects/behavior_rollouts/src/behavior_rollouts/scripted_rollout.py +++ b/example_projects/behavior_rollouts/src/behavior_rollouts/scripted_rollout.py @@ -2,8 +2,14 @@ Run ``uv run python launch_scripted.py`` from the project directory. Substitute a provider ModelAPI for EchoAPI to use the same rollout path with a real model. + +Each conversation's longest reply is then picked out (:class:`LongestReply`), with a +:class:`MessageSelector` saying which message it is. The project's views link from it to the +conversation with the selector, which the conversation view marks: the selector's shape here and +the view's (``fxtr-view-behaviors``' ``MessageSelector``) are kept the same by hand. """ +import dataclasses from typing import Annotated, cast from behaviors.implementations.context_policies import ( @@ -14,6 +20,7 @@ from behaviors.rollouts.chat import run_chat_rollout from behaviors.types import ( AssistantMessage, + ChatMessage, ChatRollout, ContentText, ModelRequest, @@ -24,6 +31,7 @@ UserMessage, ) from fxtr.core.entities import BoundID +from fxtr.entity_defns.dataclass_entity import DataclassEntity from fxtr.experiment.handles import ArrayHandle from fxtr.experiment.steps import StepContext, step from fxtr.experiment.workflows import WorkflowContext, workflow @@ -65,14 +73,75 @@ async def answer_prompt(context: StepContext, prompt: str) -> ChatRollout: return await run_chat_rollout(model, policy, max_turns=5) +@dataclasses.dataclass(frozen=True) +class MessageSelector: + """One message of a conversation: its index among the conversation's messages, each turn's + context messages and then its model's, turn by turn (:func:`conversation_messages`). + + Stored untagged (``{"message": 3}``), the shape the behaviors conversation view reads as its + ``selector`` param. + """ + + message: int + + +@dataclasses.dataclass(frozen=True, kw_only=True) +class LongestReply( + DataclassEntity, fxtr_type="org.transluce.examples.behavior_rollouts.LongestReply.v1" +): + """The longest of a conversation's replies, and where it is in the conversation.""" + + rollout: BoundID[ChatRollout] + selector: MessageSelector + text: str + + +def conversation_messages(rollout: ChatRollout) -> list[ChatMessage]: + """A rollout's messages in the order its conversation view draws them.""" + messages: list[ChatMessage] = [] + for index in range(max(len(rollout.context_turns), len(rollout.model_turns))): + if index < len(rollout.context_turns): + messages.extend(rollout.context_turns[index].messages) + if index < len(rollout.model_turns): + messages.extend(rollout.model_turns[index].messages) + return messages + + +def message_text(message: ChatMessage) -> str: + return "".join(block.text for block in message.content if isinstance(block, ContentText)) + + +def longest_reply(rollout: ChatRollout) -> tuple[MessageSelector, str]: + """The conversation's longest assistant message (the first, of several as long): where it is, + and its text.""" + replies = [ + (index, message_text(message)) + for index, message in enumerate(conversation_messages(rollout)) + if isinstance(message, AssistantMessage) + ] + if not replies: + raise ValueError("the conversation has no replies") + index, text = max(replies, key=lambda reply: len(reply[1])) + return MessageSelector(message=index), text + + +@step(name="scripted_rollout.pick_longest_reply") +async def pick_longest_reply(context: StepContext, rollout: BoundID[ChatRollout]) -> LongestReply: + """The conversation's longest reply, with a selector into the conversation for it.""" + selector, text = longest_reply(await context.load(rollout)) + return LongestReply(rollout=rollout, selector=selector, text=text) + + @workflow(name="scripted_rollout.scripted_experiment") async def scripted_experiment( context: WorkflowContext, prompts: Annotated[ArrayHandle[str], "[prompt: str]"], ) -> Annotated[ArrayHandle[BoundID[ChatRollout]], "[prompt: str]"]: - """Map a behaviors rollout over prompts using the fxtr runner.""" + """Map a behaviors rollout over prompts using the fxtr runner, and pick each one's longest + reply.""" rollouts = context.run_step( "answer", answer_prompt, {"prompt": prompts}, map_over=["prompt"] ).expect_type(("[prompt: str]", BoundID[ChatRollout])) + context.run_step("longest", pick_longest_reply, {"rollout": rollouts}, map_over=["prompt"]) # Entity-returning steps store their results as references. return cast(ArrayHandle[BoundID[ChatRollout]], rollouts) diff --git a/example_projects/behavior_rollouts/tests/test_rollout_experiment.py b/example_projects/behavior_rollouts/tests/test_rollout_experiment.py index 0e1e1f8..b6ebda8 100644 --- a/example_projects/behavior_rollouts/tests/test_rollout_experiment.py +++ b/example_projects/behavior_rollouts/tests/test_rollout_experiment.py @@ -5,7 +5,12 @@ import pytest from behavior_rollouts import openai_rollout -from behavior_rollouts.scripted_rollout import EchoAPI, scripted_experiment +from behavior_rollouts.scripted_rollout import ( + EchoAPI, + MessageSelector, + longest_reply, + scripted_experiment, +) from behaviors.types import ( ChatRollout, ContentText, @@ -131,7 +136,15 @@ async def test_mapped_rollouts_are_stored_and_loadable_from_workflow_results( ) assert result.type == ArrayType.of(("[prompt: str]", BoundID[ChatRollout])) assert set(result.keys()) == {(name,) for name in prompts} - assert len(await project_client.list_cache_entries()) == 2 + # A rollout and its longest reply, for each prompt. + assert len(await project_client.list_cache_entries()) == 4 + assert ( + len(await project_client.list_cache_entries(step="scripted_rollout.pick_longest_reply")) + == 2 + ) + # The echo of "Thank you." outgrows that of "Hello.", not of the question: the fourth message + # of the conversation, or the second. + longest = {"greeting": 3, "question": 1} for (name,), reference in result.items(): assert isinstance(name, str) rollout = await project_client.load(reference, as_type=ChatRollout) @@ -141,6 +154,7 @@ async def test_mapped_rollouts_are_stored_and_loadable_from_workflow_results( assert rollout.model_turns[0].messages[0].content == ( ContentText(text=f"Echo: {prompts[name]}"), ) + assert longest_reply(rollout)[0] == MessageSelector(message=longest[name]) assert rollout.model_turns[1].messages[0].content == (ContentText(text="Echo: Thank you."),) response = find_metadata(rollout.model_turns[1].metadata, ModelResponse) assert response is not None diff --git a/example_projects/behavior_rollouts/uv.lock b/example_projects/behavior_rollouts/uv.lock index b8a43ac..1f6b2d8 100644 --- a/example_projects/behavior_rollouts/uv.lock +++ b/example_projects/behavior_rollouts/uv.lock @@ -136,7 +136,7 @@ dev = [ [[package]] name = "behaviors" -version = "0.0.1a4" +version = "0.0.1a5" source = { editable = "../../behaviors" } dependencies = [ { name = "anyio" }, @@ -261,7 +261,7 @@ wheels = [ [[package]] name = "fxtr" -version = "0.1.0a0" +version = "0.2.0a0" source = { editable = "../../fxtr" } dependencies = [ { name = "anyio" }, @@ -295,7 +295,7 @@ requires-dist = [ { name = "asyncpg", marker = "extra == 'runner'", specifier = ">=0.30" }, { name = "cattrs", specifier = ">=26.1.0" }, { name = "cbrrr", specifier = ">=1.1.0" }, - { name = "duckdb", specifier = ">=1.5.0" }, + { name = "duckdb", specifier = ">=1.5.0,<2.0" }, { name = "frozendict", specifier = ">=2.4.6" }, { name = "fxtr", extras = ["runner"], marker = "extra == 'debug-web'" }, { name = "graphql-core", marker = "extra == 'debug-web'", specifier = ">=3.2,<3.3" }, diff --git a/example_projects/behavior_rollouts/views/src/index.ts b/example_projects/behavior_rollouts/views/src/index.ts index db25c85..0d1cdfb 100644 --- a/example_projects/behavior_rollouts/views/src/index.ts +++ b/example_projects/behavior_rollouts/views/src/index.ts @@ -1,4 +1,5 @@ -import { InvocationPanel, renderer } from "fxtr-view"; +import { EntityPanel, InvocationPanel, renderer } from "fxtr-view"; +import { LONGEST_REPLY, LongestReplyPanel } from "./longest"; import { behaviorsRenderers } from "fxtr-view-behaviors"; import { OpenAIConversationsPanel } from "./invocations"; import { OpenAIRolloutComparisonPanel } from "./comparison"; @@ -8,6 +9,7 @@ export { OPENAI_CONVERSATION, OPENAI_EXPERIMENT } from "./views"; export const rolloutRenderers = [ ...behaviorsRenderers, + renderer(EntityPanel, LONGEST_REPLY, "longest", LongestReplyPanel), renderer(CONVERSATIONS, OpenAIConversationsPanel), renderer(InvocationPanel, OPENAI_EXPERIMENT, "conversation", OpenAIConversationsPanel), renderer(InvocationPanel, OPENAI_EXPERIMENT, "compare", OpenAIRolloutComparisonPanel), diff --git a/example_projects/behavior_rollouts/views/src/longest.tsx b/example_projects/behavior_rollouts/views/src/longest.tsx new file mode 100644 index 0000000..31f09ed --- /dev/null +++ b/example_projects/behavior_rollouts/views/src/longest.tsx @@ -0,0 +1,29 @@ +// The longest reply of a conversation (`LongestReply` in `scripted_rollout.py`): its text, and a +// link to the conversation with a selector for the reply, so the conversation view opens marking +// it. A link with params opens the conversation alone, fixed. + +import styles from "./rollouts.module.css"; +import { EntityLink, unwrap, useEntity, type EntityData, type EntityID, type EntityPanelProps } from "fxtr-view"; +import type { MessageSelector } from "fxtr-view-behaviors"; + +export const LONGEST_REPLY = "org.transluce.examples.behavior_rollouts.LongestReply.v1"; + +/** `LongestReply`'s stored shape. */ +export interface LongestReplyData extends EntityData { + readonly rollout: EntityID; + readonly selector: MessageSelector; + readonly text: string; +} + +export function LongestReplyPanel({ id }: EntityPanelProps) { + const data = unwrap(useEntity(id as EntityID)); + return ( +
+
Longest reply · message {data.selector.message + 1} of the conversation
+

{data.text}

+
+ In the conversation: +
+
+ ); +} diff --git a/example_projects/behavior_rollouts/views/src/rollouts.module.css b/example_projects/behavior_rollouts/views/src/rollouts.module.css index 7c78da7..cd011c1 100644 --- a/example_projects/behavior_rollouts/views/src/rollouts.module.css +++ b/example_projects/behavior_rollouts/views/src/rollouts.module.css @@ -23,3 +23,5 @@ .compare-actions { display: flex; justify-content: flex-end; } .compare-actions button { font: inherit; color: var(--fg); background: var(--bg-alt); border: 1px solid var(--line); border-radius: 3px; padding: 3px 7px; cursor: pointer; } .compare-actions button:disabled { opacity: 0.5; cursor: default; } +.longest { display: grid; gap: 6px; padding: 8px; } +.longest p { margin: 0; white-space: pre-wrap; } diff --git a/example_projects/behavior_rollouts/views/test/renderers.test.tsx b/example_projects/behavior_rollouts/views/test/renderers.test.tsx index 94e3b4c..eac375b 100644 --- a/example_projects/behavior_rollouts/views/test/renderers.test.tsx +++ b/example_projects/behavior_rollouts/views/test/renderers.test.tsx @@ -1,16 +1,18 @@ import { fireEvent, render, screen, within } from "@testing-library/react"; import { atom } from "jotai"; import { - ARRAY_TYPE, EntityID, InvocationPanel, - invocationRefKey, type ArrayData, type EntityData, type InvocationRecord, type JsonValue, + ARRAY_TYPE, EntityID, EntityPanel, InvocationPanel, LinkBase, ViewShellProvider, + invocationRefKey, type ArrayData, type EntityData, type EntityLinkImplProps, type InvocationRecord, type JsonValue, + type ViewShell, } from "fxtr-view"; -import { RenderInvocation, dispatchRegistry } from "fxtr-view-shell-util"; +import { RegistryProvider, RenderEntity, RenderInvocation, dispatchRegistry } from "fxtr-view-shell-util"; import { TableShellProvider } from "fxtr-view-shell-util/testing"; import { CHAT_ROLLOUT, CONTEXT_TURN, END_ROLLOUT, MODEL_TURN, SET_SYSTEM_MESSAGE, type ChatRolloutData, type MessageData, type TurnData, } from "fxtr-view-behaviors"; import { rolloutRenderers, OPENAI_CONVERSATION, OPENAI_EXPERIMENT } from "../src"; +import { LONGEST_REPLY } from "../src/longest"; const registry = dispatchRegistry(rolloutRenderers); const tag = (name: string) => `org.transluce.behaviors.${name}.v1`; @@ -275,3 +277,31 @@ it("recovers stale selections and handles sequences without a second model", () fireEvent.change(screen.getByLabelText("Sequence"), { target: { value: "single" } }); expect(screen.queryByRole("region", { name: "Comparison turn 1" })).toBeNull(); }); + +it("links a longest reply to its conversation with a selector for it", () => { + const links: EntityLinkImplProps[] = []; + const reply = { + $type: LONGEST_REPLY, rollout: new EntityID("rollout"), selector: { message: 3 }, text: "Echo: Thank you.", + }; + const entities = new Map([["reply", reply as unknown as EntityData], ["rollout", rollout]]); + const shell: ViewShell = { + useEntity: (id) => ({ status: "loaded", value: entities.get(id.cid)! }), + EntityLinkImpl: (props) => { + links.push(props); + return link; + }, + }; + render( + + + + (null)} /> + + + , + ); + expect(screen.getByText("Echo: Thank you.")).toBeTruthy(); + expect(links.at(-1)).toMatchObject({ + id: { cid: "rollout" }, place: null, params: { selector: { message: 3 } }, + }); +}); diff --git a/frontend/CODE_OVERVIEW.md b/frontend/CODE_OVERVIEW.md index 7d7651d..1e06b80 100644 --- a/frontend/CODE_OVERVIEW.md +++ b/frontend/CODE_OVERVIEW.md @@ -83,7 +83,8 @@ frontend/ │ value outside React state read by selector, and │ useStableCallback), launches (useFollowLaunches: a page switches │ to each launched job unless someone picked one in it, and says - │ why in a toast), debounce (useDebouncedInput, typing applied + │ why in a toast), linkProblem (the toast a link naming nothing + │ raises), debounce (useDebouncedInput, typing applied │ once it pauses), dismiss (useDismiss: a press outside or Escape │ closes), cardTable (a card's table state │ for the slice and its page, read by the card, @@ -121,9 +122,9 @@ frontend/ │ through); networkSimplex (the exact │ solver behind the flowchart's horizontal positions) ├── panes/ the detail view (see "The detail view: panels and addresses") - │ ├── address.ts panel addresses (a view, a location, params): the syntax (parse, - │ │ format), relative locations (`Rel`, applyRelLocation), the parts a - │ │ head draws + │ ├── address.ts panel addresses (a view, a location, params, any JSON): the syntax + │ │ (parse, format), relative locations (`Rel`, applyRelLocation), the + │ │ parts a head draws │ ├── resolve.ts an address against the whole job and the registry (`Catalog`): the │ │ params it uses, the target a panel renders (`Target`), or why there │ │ is none @@ -390,11 +391,14 @@ following the panel before it, or is **pinned**, and changes only when the user **view** applied to a **location** and **params**, written like a call: `pander-score.Elicitations/batch(/generate_prompts, elicitor=sonnet)`, `(/prompts.output.call, prompt=3)`, `tree(cid:.messages[2])`, - `limerick-contest.poet(poet=nash)`, `code(/judge)`, `experiment_readme()`. A location is a step path from the job's root workflow + `limerick-contest.poet(poet=nash)`, `code(/judge)`, `experiment_readme()`, + `(/judge.output.transcript, prompt=3, selector={"message":2})`. A location is a step path from the job's root workflow (`/` alone is the root), or an entity's cid, then a **field path**: a step's starts in each invocation's record (`.output…`, `.inputs.…`). The view is a renderer's id (a view declared within another is named below it), a page's, a built-in (`VIEWS`: `table`, `invocation`, - `tree`, `trace`, `flowchart`, `code`, `experiment_readme`), or nothing for the default. Params are flat, by name. A + `tree`, `trace`, `flowchart`, `code`, `experiment_readme`), or nothing for the default. Params are flat, by name, and + any JSON: a dim's key is a string or a number, a view's param may be structured (a list or + object is written as compact JSON, its keys sorted, so a value has one spelling). A **relative address** (`Rel`) names a target from another: a view, and a location that is the same, a field path below (`.call`), a sibling step (`../step`), or absolute. - **Resolution** (`panes/resolve.ts`) works an address out against the whole job and the registry @@ -403,7 +407,9 @@ following the panel before it, or is **pinned**, and changes only when the user entered through the run its mapped keys pick out (`childPathname`, the runner's naming): a key left unbound, or a level still loading, is a problem of the params, which the panel shows and waits out. It picks the bindings the address uses (the keys walked, its node's dims, its view's - declared params), writes in a node's default view when the registry decides it, picks the + declared params; for an entity shown by its cid, every param the panel binds itself, since only + its data says which view shows it), + writes in a node's default view when the registry decides it, picks the `Target` the panel renders (a node through a view, with the source node of each argument that is one node's output; a value at a field path; the root workflow's own invocation; an entity; a page; the experiment; the code of a node's function, from its `method` and `codeVersion`, or of @@ -420,6 +426,12 @@ following the panel before it, or is **pinned**, and changes only when the user the panel before it shows that one, so it closes when that one switches away. The pin button pins a panel where it is, for good (`columns.ts`'s `pinPanel` says why there is no unpinning); a pick inside a browsing panel that leaves out a binding it inherits pins it too (`setBindings`). + **A panel showing an entity by its cid** (opened by a link carrying params for its views, a + selector) keeps every param it binds itself and passes none of them on: the panels following it + inherit only what it inherited. A link from a root to an entity binds no level keys. Params are + any JSON in one set; only where a dim's binding picks rows (`lib/invocations.ts`'s `pick`), + enters a mapped workflow's run, or reaches a renderer's `useKeys` must it be a key, and one that + is not counts as unbound there. Closing a panel closes its followers. Each panel keeps a history of what it stored, for back and forward; pinning drops it. **Navigating** a panel (a click in the view before it, its view switcher, its params, back and forward) keeps its followers, which follow it, only while it stays @@ -434,8 +446,9 @@ following the panel before it, or is **pinned**, and changes only when the user the view's followers. A drop opens a panel where it lands: browsing, right after the view, when the view has no browsing panel after it yet; else pinned, as Alt does. A link from a root is stored absolute, binding the level's keys itself, so moving between levels changes what no panel - shows. After a change, the first browsing panel whose address names nothing closes, with its - followers. A path through an entity reference is checked against the data once it loads: + shows. A link whose address names nothing (no such view, page, or step) opens nothing, and a + toast says why (`lib/linkProblem.tsx`). After a change, the first browsing panel whose address + names nothing closes, with its followers. A path through an entity reference is checked against the data once it loads: `PathValue` reports a field the value lacks through `PathMissingContext`, and a browsing panel closes the same way (`namesNothing`). A link carries its row's full keys: the panel keeps only what they add to its view's bindings. @@ -445,7 +458,7 @@ following the panel before it, or is **pinned**, and changes only when the user entity chips as the value at their place relative to it (`.output…` in a node, `.…` below a value), and a renderer's `useLink` / `EntityLink` at the view and location the renderer names (`views/viewLink.ts`, which refuses a link to a view declared within another from anywhere but - that one). Every link that opens a panel on a click can be dragged into the + that one, and gives a link to a page no location, since a page has none). Every link that opens a panel on a click can be dragged into the columns too, a table's rows among them (`dragLink` in `lib/openEntity.ts`). - **What shows the navigation.** A panel's head (`PanelHead`) is one line that is its resolved address in words, part by part (`addressParts`: the steps, the field path, a nested view's own @@ -552,7 +565,8 @@ last build still shown), and briefly that the renderers were updated. selecting a registered renderer invokes its complete-data view. Other entities dispatch through `RenderEntity` in the `EntityPanel` slot with a per-mount storage atom: a type's own panel when registered, the data tree otherwise. (A node's panel dispatches its one output entity to the same - slot, choosing the renderer from its own dropdown.) Its + slot, choosing the renderer from its own dropdown.) An entity shown by its cid hands its + renderer the panel's params, each renderer those it declares. Its corner carries the renderer controls. A `RendererSelect` switches between the type's views (`useRenderers`: its own panels, then the data tree, the wildcard), shown even when the tree is the only one so the choice is always visible; the choice lives with the mount and is not @@ -677,7 +691,7 @@ platform-modifier row clicks, the last page's padding, its failed invocations an card a slice change holds still, and the column sizing. `test/address.test.ts` checks the address syntax, relative locations, and the parts a head draws; `test/columns.test.tsx` the panels' sequence (following, pinning, history, closing, moves and drops, default views, views declared -within others, the entity chip chain) and resolution across the job (a step inside a mapped +within others, the entity chip chain, an entity panel's params) and resolution across the job (a step inside a mapped workflow, an unbound key, a level loading, panels kept when the centre moves to another level). -`test/flowchart.test.tsx` checks platform-specific wheel shortcuts and trackpad pinch zoom. +`test/flowchart.test.tsx` checks platform-specific wheel shortcuts, trackpad pinch zoom, and the zoom keys. Model, progress, and graph-layout tests cover the remaining pure transformations. diff --git a/frontend/intent.md b/frontend/intent.md index 62da4ad..85a19b9 100644 --- a/frontend/intent.md +++ b/frontend/intent.md @@ -20,3 +20,10 @@ When a user interaction causes a panel to fetch new data, the loading state shou * Let the user customize layout as desired (like panes in VS Code) so the user can e.g. compare specific things side by side * Close a pane when it's no longer relevant, unless the user intentionally keeps it. It should be hard to accidentally create a bunch of panel clutter. * Make it clear "what" exactly the user is looking at in any given pane—is this information about a step in general? an invocation of the step? output of an invocation? + +## Parameters for views +* Custom views can take parameters (specified by a link). These might be used to select a subset of the data to show. +* Entity views can also take parameters. The primary use case for entity view parameters is selectors. Selectors work a bit like text fragments in URLs - they tell the view to highlight a specific piece of content. However, fxtr has no concept of a selector; it does not dictate how selectors are represented or displayed. Selectors are just a use case for entity view parameters. +* General stuff for parameters + * When the value is a short string (e.g. a dim key), show it in the chip in the panel header + * When the value is not a short string (e.g. a selector), just show the name of the parameter and an x button to clear it. diff --git a/frontend/src/App.tsx b/frontend/src/App.tsx index 5c86d6c..15bc5b6 100644 --- a/frontend/src/App.tsx +++ b/frontend/src/App.tsx @@ -46,7 +46,7 @@ import { CardSpotlightContext, createSpotlightStore, type CardSpotlight } from " import { Store, useStableCallback } from "./lib/store"; import { indexSteps, levelTrail, mappedKeyOf } from "./lib/steps"; import { OpenLevelContext, type LevelOpener } from "./lib/openLevel"; -import type { JobSummary, KeyValue, LevelRef } from "./types"; +import type { JobSummary, LevelRef } from "./types"; import { DetailPane } from "./components/DetailPane"; import { ErrorBoundary } from "./components/ErrorBoundary"; import { Flowchart } from "./components/Flowchart"; @@ -74,7 +74,7 @@ import { ColumnsView } from "./panes/ColumnsView"; import { RAIL, TRACE } from "./panes/columns"; import { useColumns, type Centre } from "./panes/useColumns"; import { useJobCatalog } from "./panes/catalog"; -import { VIEWS } from "./panes/address"; +import { VIEWS, type Params } from "./panes/address"; import type { LinkTarget } from "./panes/drag"; import { nodeTarget, pageTarget } from "./lib/linkBase"; import type { EntityOpener } from "./lib/openEntity"; @@ -300,9 +300,7 @@ function JobView({ const [jumpGlow, setJumpGlow] = useState<{ id: string; seq: number } | null>(null); /** The slice: the value picked for each dim sliced on, shared by every card and pane, and kept * across levels, since a dim's name means the same thing in each. */ - const [slice, setSlice] = useState< - Readonly> - >({}); + const [slice, setSlice] = useState({}); /** Each card's table state: a store, read by each card for its own. */ const [cardTables] = useState( () => new Store>(new Map()), diff --git a/frontend/src/components/CODE_OVERVIEW.md b/frontend/src/components/CODE_OVERVIEW.md index c324133..1416330 100644 --- a/frontend/src/components/CODE_OVERVIEW.md +++ b/frontend/src/components/CODE_OVERVIEW.md @@ -187,11 +187,13 @@ system are in the parent overview, `frontend/CODE_OVERVIEW.md`. icon, `CUSTOM_VIEW_ICON`, before the last part of a page or a view through a renderer of the project's own, `isProjectRendererId`; the step's kind, `KIND_ICONS`, for a node; an invocation's receipt, `INVOCATION_ICON`; an entity's isometric cube, `ENTITY_ICON`, in `lib/kindIcons.ts`; a file for a function's code); the panel's own params as gray chips (wrapping onto a line of - their own under the path when they do not fit beside it); a count of those from the slice + their own under the path when they do not fit beside it), each showing a short value (a string or + number that fits) and otherwise its name alone (a selector), on a panel showing an entity by its + cid with a × clearing it; a count of those from the slice (`slice n`), those inherited from the panel before it left out; the pin (filled violet on a pinned panel; on a browsing one, a button shown only while the pointer is over it), back, forward, the view switcher, close. A pinned panel's head has a faint violet wash (`--pinned-bg`); a browsing panel's is the panel's own light grey. Hovering the path or the count opens the address card, which says what the icon means, its path as the panel stores it, and where each - binding comes from. + binding comes from, each with its value in full (a selector's too). - **Code.** A card's function, and the level's workflow in its header (`LevelHeader`), show their docstring and an "implemented" chip (`SourceDocs`, whose `codeAt` is the node's step path: the card's `[...levelPath, step.name]`, the header's `levelPath`; an argument's hover preview shows @@ -292,7 +294,8 @@ components/ │ a run's progress line along its foot until it is all done, cards as narrow │ as their content, mapped/replica dim chips stacked down the card, │ parallax pan and zoom (primary-modifier scroll or trackpad pinch; physical -│ Control-scroll on Mac pans), off-screen card counts at each rank's +│ Control-scroll on Mac pans; `=`/`-` zoom and `0` fits when not typing), +│ off-screen card counts at each rank's │ sides, and selected-card navigation ├── flowchartParallax.ts the flowchart's parallax pan: one pan fraction slides every rank │ sideways on its own (an overflowing rank scrolls end to end, a rank @@ -405,7 +408,8 @@ components/ ├── ThemeToggle.tsx at the foot of the rail: follow the system theme, or pick light or │ dark ├── Toasts.tsx sonner's toaster in the top right corner, its toasts unstyled and -│ drawn as the viewer's floating cards (lib/launches.tsx raises them) +│ drawn as the viewer's floating cards (lib/launches.tsx and +│ lib/linkProblem.tsx raise them) ├── Status.tsx Loading, Problem (a failed load with its backend), RetryLine (a │ failed read and its retry button) └── ValueModal.tsx, Markdown.tsx, ErrorBoundary.tsx diff --git a/frontend/src/components/CardTable.tsx b/frontend/src/components/CardTable.tsx index 4dac6ce..d4835b1 100644 --- a/frontend/src/components/CardTable.tsx +++ b/frontend/src/components/CardTable.tsx @@ -12,6 +12,7 @@ import { dragLink, useEntityOpener } from '../lib/openEntity' import { useLevelOpener } from '../lib/openLevel' import { keyColumnKey } from '../model/schema' import type { Column, KeyValue, StepDoc, StepInvocation, TablePage, TableRow } from '../types' +import type { Params } from '../panes/address' import { CardKeys } from './CardKeys' import { KeyValueList } from './KeyValueList' import { shownPage } from './PagedTable' @@ -188,7 +189,7 @@ function CardRows({ step, matching, onPick }: Props) { return next !== null } - const pick = (next: Readonly>) => { + const pick = (next: Params) => { setSlice(next, step.id) onPick?.() } diff --git a/frontend/src/components/DetailPane.tsx b/frontend/src/components/DetailPane.tsx index d957df8..f9d4156 100644 --- a/frontend/src/components/DetailPane.tsx +++ b/frontend/src/components/DetailPane.tsx @@ -167,7 +167,7 @@ function TargetBody({ jobId, target, params, run, onEntityView }: {
- + ) case 'node': diff --git a/frontend/src/components/Flowchart.tsx b/frontend/src/components/Flowchart.tsx index 1310ab9..1bb5e68 100644 --- a/frontend/src/components/Flowchart.tsx +++ b/frontend/src/components/Flowchart.tsx @@ -3,9 +3,9 @@ import { dimKind, type DimKind } from '../lib/invocations' import { KIND_ICONS, KIND_ICON_SIZE, KIND_ICON_STROKE } from '../lib/kindIcons' import type { StepDoc } from '../types' import { cx } from '../lib/cx' -import { hasPrimaryModifier } from '../lib/keyboard' +import { hasPrimaryModifier, isEditableTarget } from '../lib/keyboard' import { LINE_HEIGHT, ProgressLineSvg } from './ProgressLine' -import { DIM_PITCH, DIM_TOP, edgePath, layoutLevel, measureDim, NAME_X, NODE_PAD, type LayoutNode } from './flowchartLayout' +import { DIM_PITCH, DIM_TOP, edgePath, layoutLevel, measureDim, NAME_X, NODE_PAD, type FlowchartLayout, type LayoutNode } from './flowchartLayout' import { panBy, placeX, rankPlacements, zoomAt, type ParallaxView } from './flowchartParallax' import styles from './Flowchart.module.css' @@ -30,6 +30,11 @@ interface Props { */ const EDGE_OVERHANG = 40 +/** How much one press of `=` or `-` zooms. */ +const KEY_ZOOM = 1.25 + +const clampScale = (scale: number) => Math.min(2.5, Math.max(0.22, scale)) + /** * A pannable, zoomable DAG for the cards in one workflow invocation. Each node shows its step's * state glyph (nothing when done) and, for a run, how many of its invocations are done. Panning @@ -71,6 +76,14 @@ export function Flowchart({ levelKey, level, selectedId, onSelect }: Props) { setView(next) } + const fit = (viewport: HTMLElement, layout: FlowchartLayout) => { + const width = viewport.clientWidth + const height = viewport.clientHeight + if (width === 0 || height === 0) return + const scale = Math.min(1, Math.max(0.06, Math.min(width / layout.width, height / layout.height))) + update({ pan: 0.5, y: (height - layout.height * scale) / 2, scale }) + } + // Opening a level starts with its complete graph fitted into the graph pane; a new layout of the // same level keeps the view the user has. useLayoutEffect(() => { @@ -78,15 +91,8 @@ export function Flowchart({ levelKey, level, selectedId, onSelect }: Props) { const viewport = viewportRef.current const refit = fittedFor.current !== levelKey fittedFor.current = levelKey - const fit = () => { - const width = viewport.clientWidth - const height = viewport.clientHeight - if (width === 0 || height === 0) return - const scale = Math.min(1, Math.max(0.06, Math.min(width / layout.width, height / layout.height))) - update({ pan: 0.5, y: (height - layout.height * scale) / 2, scale }) - } setViewportWidth(viewport.clientWidth) - if (refit) fit() + if (refit) fit(viewport, layout) let previousSize = { width: viewport.clientWidth, height: viewport.clientHeight } const observer = new ResizeObserver(() => { const nextSize = { width: viewport.clientWidth, height: viewport.clientHeight } @@ -122,17 +128,36 @@ export function Flowchart({ levelKey, level, selectedId, onSelect }: Props) { const pointerY = event.clientY - bounds.top const pinch = event.ctrlKey && !controlHeld && !event.metaKey && !event.altKey && !event.shiftKey if (hasPrimaryModifier(event) || pinch) { - const nextScale = Math.min(2.5, Math.max(0.22, current.scale * Math.exp(-event.deltaY * 0.01))) + const nextScale = clampScale(current.scale * Math.exp(-event.deltaY * 0.01)) update(zoomAt(layoutRef.current, current, viewport.clientWidth, pointerX, pointerY, nextScale)) } else { update(panBy(layoutRef.current, current, viewport.clientWidth, pointerY, -event.deltaX, -event.deltaY)) } } + // `=` and `-` zoom about the viewport's centre and `0` fits the graph, without Shift so `=` + // stands for `+`. Modified keys stay the browser's own page zoom. + const onKeyDown = (event: KeyboardEvent) => { + if (event.defaultPrevented || event.ctrlKey || event.metaKey || event.altKey || event.isComposing || + isEditableTarget(event.target)) return + const current = viewRef.current + if (event.key === '0') { + fit(viewport, layoutRef.current) + } else if (event.key === '=' || event.key === '-') { + const nextScale = clampScale(current.scale * (event.key === '=' ? KEY_ZOOM : 1 / KEY_ZOOM)) + update(zoomAt(layoutRef.current, current, viewport.clientWidth, + viewport.clientWidth / 2, viewport.clientHeight / 2, nextScale)) + } else { + return + } + event.preventDefault() + } + window.addEventListener('keydown', onKeyDown) window.addEventListener('keydown', syncControl, true) window.addEventListener('keyup', syncControl, true) window.addEventListener('blur', releaseControl) viewport.addEventListener('wheel', onWheel, { passive: false }) return () => { + window.removeEventListener('keydown', onKeyDown) window.removeEventListener('keydown', syncControl, true) window.removeEventListener('keyup', syncControl, true) window.removeEventListener('blur', releaseControl) diff --git a/frontend/src/components/KeyboardShortcuts.tsx b/frontend/src/components/KeyboardShortcuts.tsx index ecf552f..8bc7789 100644 --- a/frontend/src/components/KeyboardShortcuts.tsx +++ b/frontend/src/components/KeyboardShortcuts.tsx @@ -29,6 +29,14 @@ const shortcutGroups = (modifier: string): { title: string; shortcuts: Shortcut[ { keys: [[modifier, 'click']], action: 'Slice the level at a row’s keys', context: 'Click a row in a step card’s table. Applies that row’s dimension values across the level.' }, ], }, + { + title: 'Flowchart', + shortcuts: [ + { keys: [['='], ['-']], action: 'Zoom in / out', context: 'While the flowchart is open and not typing. Zooms about the middle of the graph.' }, + { keys: [['0']], action: 'Fit the graph in view', context: 'While the flowchart is open and not typing.' }, + { keys: [[modifier, 'scroll']], action: 'Zoom at the pointer', context: 'Over the flowchart. A trackpad pinch zooms too.' }, + ], + }, { title: 'Tables', shortcuts: [ diff --git a/frontend/src/components/PanelHead.module.css b/frontend/src/components/PanelHead.module.css index b413ede..4cbfe80 100644 --- a/frontend/src/components/PanelHead.module.css +++ b/frontend/src/components/PanelHead.module.css @@ -67,6 +67,8 @@ .chip.is-slice { border-color: var(--line-strong); border-style: dashed; font-style: italic; color: var(--fg-dim); } .chip.is-folded { flex: none; align-items: center; gap: 2px; font-family: var(--font-sans); cursor: default; } .chip.is-passed-on { opacity: 0.55; } +/* In the address card: the whole value, wrapping, so a long one (a selector) can be read. */ +.chip.is-full { white-space: normal; overflow-wrap: anywhere; max-width: 100%; } .own { display: flex; flex: none; flex-wrap: wrap; gap: 4px; max-width: 100%; } .controls { display: inline-flex; flex: none; align-items: center; gap: 4px; height: 20px; } diff --git a/frontend/src/components/PanelHead.tsx b/frontend/src/components/PanelHead.tsx index edc70d9..98ad384 100644 --- a/frontend/src/components/PanelHead.tsx +++ b/frontend/src/components/PanelHead.tsx @@ -36,7 +36,10 @@ interface Props { * - The **params** the address uses: the panel's own as chips after the path (all of them on a * line of their own under it when they do not fit beside it), and the ones from the level's * slice only counted (`slice n`), since the slice control shows them. The ones it inherits from - * the panel before it are left out: that panel's head shows them. + * the panel before it are left out: that panel's head shows them. A chip shows a short value (a + * string or a number that fits `VALUE_CHARS`), and otherwise its param's name alone (a + * selector), the value in its tooltip. On a panel showing an entity by its cid, whose views' + * params are optional, each has a × clearing it. * - A pinned panel's head has a faint violet wash; a browsing panel's is the panel's own light * grey. The pin button, first of the controls, pins the panel where it is. It shows on a pinned * panel (filled violet, and no longer a button), and on a browsing one only while the pointer is @@ -70,7 +73,7 @@ export function PanelHead({ panel, columns, onView }: Props) { - + + ) +} + +/** Whether a param's value is drawn in its chip: a string or a number that fits `VALUE_CHARS`. */ +function isShort(value: Params[string]): boolean { + return (typeof value === 'string' || typeof value === 'number') && formatValue(value).length <= VALUE_CHARS +} + +/** A param's chip: its name, then its value when short (`isShort`), or always with `full` (the + * address card, where a long one, a selector, wraps). */ +function ParamChip({ name, value, className, title, full = false, onMouseEnter, onMouseLeave, children }: { name: string value: Params[string] className?: string | false title: string + full?: boolean onMouseEnter?: () => void onMouseLeave?: () => void children?: React.ReactNode }) { const text = formatValue(value) return ( - + {name} - {elide(text, VALUE_CHARS)} + {(full || isShort(value)) && text} {children} ) } -/** `text`, its middle left out when longer than `chars`: the end usually tells values apart. */ -function elide(text: string, chars: number): string { - if (text.length <= chars) return text - const tail = Math.floor((chars - 1) / 3) - return `${text.slice(0, chars - 1 - tail)}…${text.slice(-tail)}` -} - /** Outline a panel (null: nothing) while something naming it is hovered. */ function outline(columns: ColumnsState, id: string | null) { columns.highlight.set(id === null || isRoot(id) ? null : { kind: 'existing', panelId: id }) @@ -255,7 +288,8 @@ const CARD_CLOSE_DELAY = 150 * invocation, an entity, a custom view), when its path has one; * - **path**: its address as stored (a browsing panel's relative to the panel before it), and its * own params (each one dropped with its ×: a browsing panel inherits it again, a pinned one - * leaves it unbound); + * leaves it unbound). Every param here shows its value in full, a long one (a selector) + * included, which the head leaves out; * - **inherits** and **slice**: every binding from the panel before it (hovering outlines the * panel that binds it) or the level's slice, dim when its address does not use it but passes it * on to the panels following it. @@ -308,16 +342,10 @@ function AddressRows({ panel, columns, state }: { panel: PanelInstance; columns: {formatRel(panel.rel)} {own.map((name) => ( - - + ))} @@ -327,7 +355,7 @@ function AddressRows({ panel, columns, state }: { panel: PanelInstance; columns: inherits {inherited.map((name) => ( - outline(columns, sources[name]!)} onMouseLeave={() => outline(columns, null)} /> ))} @@ -339,7 +367,7 @@ function AddressRows({ panel, columns, state }: { panel: PanelInstance; columns: slice {slice.map((name) => ( - ))} diff --git a/frontend/src/components/SliceDims.tsx b/frontend/src/components/SliceDims.tsx index eb81c6b..d04f18a 100644 --- a/frontend/src/components/SliceDims.tsx +++ b/frontend/src/components/SliceDims.tsx @@ -5,6 +5,7 @@ import { useDismiss } from '../lib/dismiss' import { useLevelState } from '../lib/levelState' import { cx } from '../lib/cx' import type { StepDoc } from '../types' +import { isKeyValue } from '../panes/address' import { KeyValueList } from './KeyValueList' import styles from './SliceDims.module.css' @@ -77,7 +78,8 @@ export function SliceDimsPanel({ steps, className }: { steps: readonly StepDoc[]
{dims.map((entry) => { - const picked = slice[entry.dim] + // The trace's slice holds dims' keys alone; a level state's slice is typed as any params. + const picked = slice[entry.dim] return (
if (!meta.value) return {meta.loading ? 'loading entity…' : 'entity not found'} if (meta.value.typeTag === 'org.transluce.fxtr.core.Array') - return - return + return + return } +const NO_PARAMS: Params = Object.freeze({}) + /** The renderer chosen for an `EntityPanel` (null: the default), and its setter. */ interface Choice { renderer: string | null setRenderer: (renderer: string | null) => void + params: Params } -function PagedArrayPanel({ cid, renderer: remembered, setRenderer }: { cid: string } & Choice) { +function PagedArrayPanel({ cid, renderer: remembered, setRenderer, params }: { cid: string } & Choice) { const choices = useRenderers(EntityPanelSlot, 'org.transluce.fxtr.core.Array') const renderer = chosenRenderer(choices, remembered) const id = useMemo(() => new EntityID(cid), [cid]) @@ -65,19 +72,20 @@ function PagedArrayPanel({ cid, renderer: remembered, setRenderer }: { cid: stri // An array's rows are not a path into whatever holds it, so its links open their entities alone. return
- {renderer ? + {renderer ? : }
} -function FullEntityPanel({ cid, renderer, setRenderer }: { cid: string } & Choice) { +function FullEntityPanel({ cid, renderer, setRenderer, params }: { cid: string } & Choice) { const id = useMemo(() => new EntityID(cid), [cid]) const storage = useMemo(() => atom(null), []) const choices = useRenderers(EntityPanelSlot, useTypeName(id)) const chosen = chosenRenderer(choices, renderer) return (
- + {choices.length > 0 && } diff --git a/frontend/src/views/FrontendViewShellProvider.tsx b/frontend/src/views/FrontendViewShellProvider.tsx index a2155bb..356e521 100644 --- a/frontend/src/views/FrontendViewShellProvider.tsx +++ b/frontend/src/views/FrontendViewShellProvider.tsx @@ -22,6 +22,7 @@ import { useLoading } from '../lib/loading' import { LevelStateContext } from '../lib/levelState' import { linkTarget } from '../lib/linkBase' import { useEntityOpener } from '../lib/openEntity' +import { keyParams } from '../panes/address' const useCachedEntity = createCachedEntityHook(loadEntity) @@ -41,7 +42,8 @@ function useInvocation(ref: InvocationRef) { * trace's, or a panel's), from the nearest `LevelStateContext`. */ function useKeys(): ViewKeys { const level = useContext(LevelStateContext) - return level ? { slice: level.slice, selected: level.selected } : NO_KEYS + // Renderers read the dims' keys alone, not a panel's other params. + return level ? { slice: keyParams(level.slice), selected: level.selected } : NO_KEYS } const NO_KEYS: ViewKeys = { slice: {}, selected: {} } diff --git a/frontend/src/views/registry.ts b/frontend/src/views/registry.ts index 78da158..cc83b22 100644 --- a/frontend/src/views/registry.ts +++ b/frontend/src/views/registry.ts @@ -97,7 +97,7 @@ export async function loadViews(version: string | null = null, importer: ImportB async function prepareBundle(response: Response, base: URL, version: string, importer: ImportBundle): Promise { const manifest = (await response.json()) as ViewBundleManifest if (manifest.apiVersion !== VIEW_API_VERSION) { - throw new Error(`the project's view bundle is at view API version ${manifest.apiVersion}; this viewer supports ${VIEW_API_VERSION}`) + throw new Error(`the project's view bundle is at view API version ${manifest.apiVersion}; this viewer supports ${VIEW_API_VERSION}. Re-vendor the fxtr packages (\`fxtr views vendor\`, outside the fxtr checkout) and rebuild the renderers (\`fxtr views build\`)`) } const versioned = (name: string) => { const url = new URL(name, base) diff --git a/frontend/src/views/viewLink.ts b/frontend/src/views/viewLink.ts index 26269e3..e37bd84 100644 --- a/frontend/src/views/viewLink.ts +++ b/frontend/src/views/viewLink.ts @@ -5,21 +5,29 @@ * after the view, or with Alt in a pinned panel), hovering lights where it would open, and dragging * carries it. A relative location needs a view with an address of its own: a panel, or the centre. * Anywhere else a relative link is null, and - * the renderer shows its detail in place. + * the renderer shows its detail in place. A page has no location, so a link to one names none, + * wherever it is drawn. */ import { useContext, useMemo } from 'react' import type { ViewLink, ViewLinkSpec, ViewParams } from 'fxtr-view' +import { useRegistry, type DispatchRegistry } from 'fxtr-view-shell-util' import { OpenEntityContext, dragLink, type EntityOpener } from '../lib/openEntity' import { parseRelLocation } from '../panes/address' import type { LinkTarget } from '../panes/drag' +import { isPage } from '../panes/resolve' /** What `spec` opens from `opener`'s view at `params`; null where a relative location has no address * to start from. A view declared within another may be linked to only from that one: a link from - * anywhere else is the renderer's bug, and throws. A malformed location throws too. */ -export function specTarget(spec: ViewLinkSpec, params: ViewParams, opener: EntityOpener): LinkTarget | null { + * anywhere else is the renderer's bug, and throws. A malformed location throws too, and so does a + * location given with a page. */ +export function specTarget(spec: ViewLinkSpec, params: ViewParams, opener: EntityOpener, registry: DispatchRegistry): LinkTarget | null { if (spec.within !== null && opener.viewId !== spec.within) throw new Error(`${spec.view} is declared within ${spec.within}, and only that view links to it (this link is in ${opener.viewId ?? 'no view'})`) + if (isPage(registry, spec.view)) { + if (spec.to !== null) throw new Error(`${spec.view} is a page, which has no location, and the link to it names ${spec.to}`) + return { rel: { view: spec.view, location: { kind: 'absolute', location: null } }, params } + } const location = spec.to === null ? { kind: 'same' as const } : parseRelLocation(spec.to) if (location.kind !== 'absolute' && !opener.relative) return null return { rel: { view: spec.view, location }, params } @@ -27,9 +35,10 @@ export function specTarget(spec: ViewLinkSpec, params: ViewParams, opener: Entit export function useLink(spec: ViewLinkSpec | null, params: ViewParams): ViewLink | null { const opener = useContext(OpenEntityContext) + const registry = useRegistry() // A malformed address is the renderer's bug: it throws, to the renderer's error boundary. - const link = useMemo(() => (spec === null || !opener ? null : specTarget(spec, params, opener)), - [spec?.view, spec?.within, spec?.to, JSON.stringify(params), opener]) + const link = useMemo(() => (spec === null || !opener ? null : specTarget(spec, params, opener, registry)), + [spec?.view, spec?.within, spec?.to, JSON.stringify(params), opener, registry]) if (!link || !opener) return null const state = opener.linkState(link) return { diff --git a/frontend/test/address.test.ts b/frontend/test/address.test.ts index dad07c7..156f54c 100644 --- a/frontend/test/address.test.ts +++ b/frontend/test/address.test.ts @@ -30,6 +30,21 @@ describe('addresses', () => { expect(parseAddress('(/a, n=3, s="3")').params).toEqual({ n: 3, s: '3' }) }) + it('writes a JSON value compactly with its keys sorted, and reads one back', () => { + const { address } = parseAddress('behaviors.conversation(cid:bafyabc)') + const selector = { message: 3, span: [0, 12], note: 'a "b"', at: { z: null, a: true } } + const text = formatAddress(address, { selector }) + expect(text).toBe('behaviors.conversation(cid:bafyabc, selector={"at":{"a":true,"z":null},"message":3,"note":"a \\"b\\"","span":[0,12]})') + expect(parseAddress(text).params).toEqual({ selector }) + expect(parseAddress('(/a, s={"b": "}", "a": [1, {"c": "]"}]})').params).toEqual({ s: { b: '}', a: [1, { c: ']' }] } }) + }) + + it('reads bare true, false and null as those, and quotes strings spelled so', () => { + expect(parseAddress('(/a, t=true, f=false, n=null, s="true")').params).toEqual({ t: true, f: false, n: null, s: 'true' }) + const { address } = parseAddress('(/a)') + expect(formatAddress(address, { b: true, s: 'null' })).toBe('(/a, b=true, s="null")') + }) + it('reads the parts of a location', () => { expect(parseAddress('tree(/a/b.output.x[2])').address).toEqual({ view: 'tree', location: { root: 'step', steps: ['a', 'b'], path: ['output', 'x', '2'] }, @@ -42,6 +57,8 @@ describe('addresses', () => { expect(() => parseAddress('(/a.)')).toThrow(AddressError) expect(() => parseAddress('(/a, b)')).toThrow(AddressError) expect(() => parseAddress('(/a) x')).toThrow(AddressError) + expect(() => parseAddress('(/a, s={"b":1)')).toThrow(AddressError) + expect(() => parseAddress('(/a, s={b:1})')).toThrow(AddressError) }) }) diff --git a/frontend/test/columns.test.tsx b/frontend/test/columns.test.tsx index e2b40ba..79a39f4 100644 --- a/frontend/test/columns.test.tsx +++ b/frontend/test/columns.test.tsx @@ -2,17 +2,20 @@ import {act} from 'react' import {createRoot} from 'react-dom/client' import {afterEach, beforeEach, expect, it, vi} from 'vitest' -import {InvocationPanel, declareView, renderer} from 'fxtr-view' +import {InvocationPanel, declarePage, declareView, page, renderer} from 'fxtr-view' import {dispatchRegistry} from 'fxtr-view-shell-util' import {buildLevel} from '../src/model/level' import {parseRel, type Params} from '../src/panes/address' import {TRACE, allPanels, sequence} from '../src/panes/columns' +import {showLinkProblem} from '../src/lib/linkProblem' import {useColumns, type Centre, type ColumnsState} from '../src/panes/useColumns' import {linkTarget, panelBase} from '../src/lib/linkBase' import type {Catalog} from '../src/panes/resolve' import type {Level, StepDoc} from '../src/types' import {inProgress, overviewOf} from './fixtures' +vi.mock('../src/lib/linkProblem', () => ({showLinkProblem: vi.fn()})) + const built = buildLevel('job', overviewOf(inProgress())) const roll = built.steps.find((step) => step.name === 'roll')! // A step whose output is entities, so a path into it goes on through a reference. @@ -31,9 +34,10 @@ const levels: Record = {root: rootLevel, 'root/score[model:"a"]': const View = () => null const ROLLS = declareView(InvocationPanel, 'roll', 'test.Rolls') const DETAIL = declareView(InvocationPanel, 'roll', 'detail', {within: ROLLS, params: ['point']}) +const TRANSCRIPT = declarePage('test.transcript', {params: ['event']}) const catalog: Catalog = { root: 'root', - registry: dispatchRegistry([renderer(ROLLS, View), renderer(DETAIL, View)]), + registry: dispatchRegistry([renderer(ROLLS, View), renderer(DETAIL, View), page(TRANSCRIPT, View)]), level: (pathname) => (levels[pathname] ? {status: 'ready', level: levels[pathname]} : {status: 'pending'}), } const rootCentre: Centre = {address: {view: 'trace', location: {root: 'step', steps: [], path: []}}, keys: {}} @@ -59,6 +63,7 @@ beforeEach(() => { afterEach(async () => { await act(async () => root.unmount()) vi.unstubAllGlobals() + vi.mocked(showLinkProblem).mockClear() }) const link = (to: string, params: Params = {}) => ({rel: parseRel(to).rel, params}) @@ -83,6 +88,15 @@ it('navigates the browsing panel after the view on a plain click, remembering wh expect(shown()).toEqual(['browses test.Rolls(/roll, seed=a)']) }) +it('opens a page from a panel with a location, at no location', async () => { + await mount() + await follow('(/roll)', {seed: 'a'}) + const [step] = panels() + const pageLink = {rel: {view: 'test.transcript', location: {kind: 'absolute' as const, location: null}}, params: {event: '42.61'}} + await act(async () => state.follow(pageLink, step!.id)) + expect(ordered()).toEqual(['browses test.Rolls(/roll, seed=a)', 'browses test.transcript(event="42.61")']) +}) + it('opens a pinned panel on Alt, which a plain click then leaves alone', async () => { await mount() await follow('(/roll)', {seed: 'a'}) @@ -398,8 +412,17 @@ it('shows a node\'s code, and the root workflow\'s, as the code version its leve await follow('code(/score/inner)', {model: 'a'}) expect(resolution().text).toBe('code(/score/inner, model=a)') expect(resolution().target).toEqual({kind: 'code', name: inner.method, codeVersion: inner.codeVersion}) - await follow('code(/roll.output)', {}, TRACE, {pin: true}) - expect(state.stateOf(panels().at(-1)!.id).resolution).toMatchObject({target: null, structural: true}) +}) + +it('opens nothing for a link naming nothing, and says why, leaving the panels as they were', async () => { + await mount() + await follow('(/roll)', {seed: 'a'}) + for (const pin of [false, true]) { + await follow('code(/roll.output)', {}, TRACE, {pin}) + expect(shown()).toEqual(['browses test.Rolls(/roll, seed=a)']) + } + expect(showLinkProblem).toHaveBeenCalledTimes(2) + expect(vi.mocked(showLinkProblem).mock.calls[0]![0]).toBe('code(/roll.output)') }) it('keeps every panel as it is when the centre moves to another level, binding the level\'s keys from a link in the trace', async () => { @@ -420,3 +443,54 @@ it('follows a relative link from a view in the centre, against the centre\'s add expect(shown()).toEqual(['browses (/score.output, model=a)']) expect(panels()[0]!.rel.location.kind).toBe('absolute') }) + +const selector = {message: 2} +// A link to a judgment alone, its views opened at a selector. +const selected = (value: Params = selector) => linkTarget('cid1', null, {selector: value}) + +it('opens an entity alone at the params its link passes, and lights the link', async () => { + await mount({seed: 'a'}) + await act(async () => state.follow(selected(), TRACE)) + expect(shown()).toEqual(['browses (cid:cid1, selector={"message":2})']) + expect(state.linkState(selected(), TRACE)).toEqual({selected: true, open: true}) + expect(state.linkState(selected({message: 3}), TRACE)).toEqual({selected: false, open: false}) +}) + +it('binds no level keys on a link from the trace to an entity', async () => { + await mount({}, {...rootCentre, keys: {model: 'a'}}) + await act(async () => state.follow(selected(), TRACE)) + expect(panels()[0]!.own).toEqual({selector}) +}) + +it('passes on none of an entity panel\'s own params, only what it inherits', async () => { + await mount({seed: 'a'}) + await act(async () => state.follow(selected(), TRACE)) + const first = panels()[0]!.id + await follow('(.verdict)', {}, first) + expect(ordered()).toEqual(['browses (cid:cid1, selector={"message":2})', 'browses (cid:cid1.verdict)']) + const env = state.stateOf(panels()[1]!.id).resolution.env + expect(env).toEqual({seed: 'a'}) +}) + +it('keeps an entity panel\'s params across its views, and drops one on a clear, which back undoes', async () => { + await mount() + await act(async () => state.follow(selected(), TRACE)) + const id = panels()[0]!.id + const location = {root: 'entity' as const, cid: 'cid1', path: []} + await act(async () => state.setAddress(id, {view: 'tree', location})) + expect(shown()).toEqual(['browses tree(cid:cid1, selector={"message":2})']) + await act(async () => state.setAddress(id, {view: null, location})) + await act(async () => state.setOwn(id, {})) + expect(shown()).toEqual(['browses (cid:cid1)']) + await act(async () => state.history(id, -1)) + expect(shown()).toEqual(['browses (cid:cid1, selector={"message":2})']) +}) + +it('pins an entity panel at its own params alone', async () => { + await mount({seed: 'a'}) + await act(async () => state.follow(selected(), TRACE)) + const id = panels()[0]!.id + await act(async () => state.pin(id)) + expect(panels()[0]!.own).toEqual({selector}) + expect(shown()).toEqual(['pinned (cid:cid1, selector={"message":2})']) +}) diff --git a/frontend/test/entityLinks.test.tsx b/frontend/test/entityLinks.test.tsx index ba33768..85f2360 100644 --- a/frontend/test/entityLinks.test.tsx +++ b/frontend/test/entityLinks.test.tsx @@ -1,7 +1,7 @@ // @vitest-environment jsdom import { fireEvent, render, screen } from '@testing-library/react' import { expect, it } from 'vitest' -import { EntityID, useEntityLinks } from 'fxtr-view' +import { EntityID, declarePage, page, useEntityLinks, useLink } from 'fxtr-view' import { dispatchRegistry } from 'fxtr-view-shell-util' import { FrontendViewShellProvider } from '../src/views/FrontendViewShellProvider' import { OpenEntityContext, type EntityOpener } from '../src/lib/openEntity' @@ -39,3 +39,32 @@ it("opens a renderer's marks through the nearest opener, and says which one a pa fireEvent.click(screen.getByText('other')) expect(opened).toEqual(['other']) }) + +const transcript = declarePage('test.transcript', { params: ['event'] }) + +function PageLink() { + const link = useLink(transcript, { event: '42.61' }) + return link === null ? no link : +} + +it('links to a page with no location, from a panel with a location and from where links have none', () => { + for (const relative of [true, false]) { + const followed: LinkTarget[] = [] + const opener: EntityOpener = { + originId: 'panel', viewId: null, relative, + follow: (target) => followed.push(target), + hover: () => {}, + linkState: () => ({ open: false, selected: false }), + } + const { unmount } = render( + + null)])}> + + + , + ) + fireEvent.click(screen.getByText('42.61')) + expect(followed).toEqual([{ rel: { view: 'test.transcript', location: { kind: 'absolute', location: null } }, params: { event: '42.61' } }]) + unmount() + } +}) diff --git a/frontend/test/flowchart.test.tsx b/frontend/test/flowchart.test.tsx index 4709527..d7445e5 100644 --- a/frontend/test/flowchart.test.tsx +++ b/frontend/test/flowchart.test.tsx @@ -67,3 +67,22 @@ it('keeps Mac trackpad pinch zoom after Control is released or the window loses wheel({ ctrlKey: true }) expect(scale()).not.toBe(before) }) + +it('zooms with = and -, fits with 0, and leaves keys typed into a field alone', () => { + const { scale } = renderGraph() + const fitted = scale() + fireEvent.keyDown(window, { key: '=' }) + const zoomedIn = scale() + expect(Number(zoomedIn)).toBeGreaterThan(Number(fitted)) + fireEvent.keyDown(window, { key: '-' }) + fireEvent.keyDown(window, { key: '-' }) + expect(Number(scale())).toBeLessThan(Number(zoomedIn)) + fireEvent.keyDown(window, { key: '0' }) + expect(scale()).toBe(fitted) + fireEvent.keyDown(window, { key: '=', ctrlKey: true }) + expect(scale()).toBe(fitted) + const input = document.body.appendChild(document.createElement('input')) + fireEvent.keyDown(input, { key: '=' }) + expect(scale()).toBe(fitted) + input.remove() +}) diff --git a/fxtr/CHANGELOG.md b/fxtr/CHANGELOG.md index 9b35564..294b7c6 100644 --- a/fxtr/CHANGELOG.md +++ b/fxtr/CHANGELOG.md @@ -1,5 +1,19 @@ # fxtr changelog +## 0.2.0a0 + +- Rebuild custom renderer bundles for view API 4. After upgrading an installed fxtr, run + `uv run fxtr views vendor`, run `pnpm install` in the renderer package, then run + `uv run fxtr views build`. In TypeScript, `LinkTo` and `EntityLinkProps` now take the view + declaration type, such as `LinkTo`. Renderers that read parameters should + narrow JSON values to the types they expect (#261, #288). +- Entity links can pass JSON parameters to a view. For example, a link to a rollout or + transcript can open its conversation view at a specific message (#288). +- Viewer links can open pages and explain why a target could not be opened. In the flowchart, + `=` and `-` zoom and `0` fits the whole graph (#283). +- Installs use DuckDB `>=1.5.0,<2.0` to preserve array query behavior for integer division by + zero and parameterized SQL (#291). + ## 0.1.0a0 - Hierarchical viewer panels, linked custom detail views and pages, invocation tables and detail diff --git a/fxtr/pyproject.toml b/fxtr/pyproject.toml index a60ffcd..f30e79d 100644 --- a/fxtr/pyproject.toml +++ b/fxtr/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "hatchling.build" [project] name = "fxtr" -version = "0.1.0a0" +version = "0.2.0a0" description = "A configuration and orchestration system for modular, reproducible experiments" # Before 3.12.4, typing.get_type_hints cannot resolve a PEP 695 class's type parameters under # `from __future__ import annotations`, which the entity converter relies on. @@ -14,7 +14,8 @@ license-files = ["LICENSE", "NOTICE"] dependencies = [ "anyio>=4.14.0", "cbrrr>=1.1.0", - "duckdb>=1.5.0", + # Array queries rely on DuckDB 1.x's integer division by zero and SQL parameter syntax. + "duckdb>=1.5.0,<2.0", "frozendict>=2.4.6", "cattrs>=26.1.0", "pyarrow>=20.0.0", diff --git a/fxtr/src/fxtr/project/views.py b/fxtr/src/fxtr/project/views.py index 175b0cd..e41cc7b 100644 --- a/fxtr/src/fxtr/project/views.py +++ b/fxtr/src/fxtr/project/views.py @@ -77,7 +77,7 @@ from fxtr.project import ts_packages from fxtr.project.config import ProjectError, ViewsConfig -VIEW_API_VERSION = 3 +VIEW_API_VERSION = 4 """The bundle contract's version this fxtr supports: ``fxtr-view``'s ``VIEW_API_VERSION``.""" VIEW_BUNDLE_MANIFEST_FILENAME = "fxtr-view-bundle-manifest.json" @@ -226,7 +226,9 @@ def _parse_manifest(dist: Path, raw: bytes) -> ViewBundleManifest: if api_version != VIEW_API_VERSION: raise ViewsError( f"{path} was built at view API version {api_version}; this fxtr supports" - f" {VIEW_API_VERSION}. Rebuild the renderer package against this fxtr's fxtr-view." + f" {VIEW_API_VERSION}. Rebuild the renderer package against this fxtr's fxtr-view;" + " outside the fxtr checkout, refresh its copy first: `uv run fxtr views vendor`," + " `pnpm install` in the package, then `uv run fxtr views build`." ) for name in (module, stylesheet): if name is not None and not (dist / name).is_file(): diff --git a/fxtr/tests/asgi_testing.py b/fxtr/tests/asgi_testing.py index bc0e91d..44cc02e 100644 --- a/fxtr/tests/asgi_testing.py +++ b/fxtr/tests/asgi_testing.py @@ -28,12 +28,21 @@ async def a_request( ) -> tuple[int, dict[str, str], bytes]: """One request through ``app`` to :data:`HOST`: the status, headers, and body.""" messages: list[Message] = [] + body_sent = False + response_complete = anyio.Event() async def receive() -> Message: - return {"type": "http.request", "body": body} + nonlocal body_sent + if not body_sent: + body_sent = True + return {"type": "http.request", "body": body} + await response_complete.wait() + return {"type": "http.disconnect"} async def send(message: Message) -> None: messages.append(message) + if message["type"] == "http.response.body" and not message.get("more_body", False): + response_complete.set() sent = {"host": HOST, **(headers or {})} scope = { diff --git a/fxtr/tests/test_runner_postgres_debug_web.py b/fxtr/tests/test_runner_postgres_debug_web.py index 59b14c8..6e65451 100644 --- a/fxtr/tests/test_runner_postgres_debug_web.py +++ b/fxtr/tests/test_runner_postgres_debug_web.py @@ -43,7 +43,7 @@ pytest.importorskip("ariadne") from ariadne import graphql # noqa: E402 -from asgi_testing import PAGE_ORIGIN, a_page_socket # noqa: E402 +from asgi_testing import PAGE_ORIGIN, a_page_socket, a_request # noqa: E402 from starlette.applications import Starlette # noqa: E402 from starlette.routing import Mount # noqa: E402 from starlette.types import ASGIApp, Message # noqa: E402 @@ -429,7 +429,7 @@ async def test_many_entities_come_back_in_one_response(database: Database) -> No def post(payload: object) -> Any: body = json.dumps(payload).encode() - return _request(app, "/api/entities", method="POST", body=body) + return a_request(app, "/api/entities", method="POST", body=body) cids = [result_cid, missing.cid_str(), result_cid] status, headers, body = await post({"cids": cids}) @@ -1025,41 +1025,6 @@ def test_the_experiment_readme_is_the_project_roots(tmp_path: Path) -> None: # ---- the viewer itself: everything outside /api ---- -async def _request( - app: ASGIApp, - path: str, - headers: list[tuple[bytes, bytes]] | None = None, - *, - method: str = "GET", - body: bytes = b"", -) -> tuple[int, dict[str, str], bytes]: - """One request through ``app``, without a server: the status, headers, and body.""" - messages: list[Message] = [] - - async def receive() -> Message: - return {"type": "http.request", "body": body} - - async def send(message: Message) -> None: - messages.append(message) - - await app( - { - "type": "http", - "method": method, - "path": path, - "raw_path": path.encode(), - "root_path": "", - "query_string": b"", - "headers": headers or [(b"host", b"127.0.0.1:8000")], - }, - receive, - send, - ) - start = messages[0] - response_headers = {k.decode().lower(): v.decode() for k, v in start["headers"]} - return start["status"], response_headers, b"".join(m.get("body", b"") for m in messages[1:]) - - def a_built_viewer(root: Path) -> Path: dist = root / "dist" (dist / "assets").mkdir(parents=True) @@ -1070,28 +1035,28 @@ def a_built_viewer(root: Path) -> Path: async def test_the_viewer_is_served_from_the_root_uncached(tmp_path: Path) -> None: app = Starlette(routes=[Mount("/", ViewerFiles(a_built_viewer(tmp_path)))]) - status, headers, body = await _request(app, "/") + status, headers, body = await a_request(app, "/") assert (status, body) == (200, b"viewer") assert headers["cache-control"] == "no-cache" - status, headers, body = await _request(app, "/assets/index.js") + status, headers, body = await a_request(app, "/assets/index.js") assert (status, body) == (200, b"console.log(1)") assert headers["cache-control"] == "no-cache" # A revalidation of an unchanged file is a 304 that still says to revalidate next time. - _, headers, _ = await _request(app, "/") - status, headers, _ = await _request(app, "/", [(b"if-none-match", headers["etag"].encode())]) + _, headers, _ = await a_request(app, "/") + status, headers, _ = await a_request(app, "/", headers={"if-none-match": headers["etag"]}) assert status == 304 and headers["cache-control"] == "no-cache" - assert (await _request(app, "/nowhere.js"))[0] == 404 + assert (await a_request(app, "/nowhere.js"))[0] == 404 async def test_an_unbuilt_viewer_says_how_to_build_it(tmp_path: Path) -> None: dist = tmp_path / "dist" app = Starlette(routes=[Mount("/", ViewerFiles(dist))]) - status, headers, body = await _request(app, "/") + status, headers, body = await a_request(app, "/") assert status == 404 and b"pnpm --filter fxtr-ide build" in body assert headers["cache-control"] == "no-cache" # Building it while the server runs is enough. a_built_viewer(tmp_path) - assert (await _request(app, "/"))[0] == 200 + assert (await a_request(app, "/"))[0] == 200 def test_an_installed_viewer_is_preferred_to_the_checkouts( @@ -1111,12 +1076,12 @@ async def test_the_api_and_the_viewer_share_one_origin(tmp_path: Path) -> None: async with a_client(Database("postgresql+asyncpg://unused", pg_schema="unused")) as client: client.project = project app = create_app(client, frontend_dist=a_built_viewer(tmp_path)) - status, _, body = await _request(app, "/api/experiment_readme") + status, _, body = await a_request(app, "/api/experiment_readme") assert status == 200 and json.loads(body)["markdown"] == "# p" - assert (await _request(app, "/"))[0] == 200 + assert (await a_request(app, "/"))[0] == 200 # The API is only under /api. - assert (await _request(app, "/experiment_readme"))[0] == 404 - status, headers, _ = await _request(app, "/api/graphql") + assert (await a_request(app, "/experiment_readme"))[0] == 404 + status, headers, _ = await a_request(app, "/api/graphql") assert status == 307 and headers["location"].endswith("/api/graphql/") @@ -1124,7 +1089,7 @@ async def test_the_server_says_which_project_it_serves(tmp_path: Path) -> None: project = a_views_project(tmp_path, views=False) async with a_client(Database("postgresql+asyncpg://unused", pg_schema="unused")) as client: client.project = project - status, headers, body = await _request(create_app(client), "/api/info") + status, headers, body = await a_request(create_app(client), "/api/info") assert (status, headers["cache-control"]) == (200, "no-cache") info = json.loads(body) assert (info["root"], info["schema"]) == (str(tmp_path.resolve()), "unused") @@ -1225,11 +1190,13 @@ async def test_a_running_dev_server_takes_over_the_viewers_paths(tmp_path: Path) viewer = Viewer(ViewerFiles(a_built_viewer(tmp_path))) app = Starlette(routes=[Mount("/", viewer)]) viewer.dev_port = 5199 - status, headers, _ = await _request(app, "/assets/index.js", [(b"host", b"localhost:8000")]) + status, headers, _ = await a_request( + app, "/assets/index.js", headers={"host": "localhost:8000"} + ) assert status == 307 and headers["location"] == "http://localhost:5199/assets/index.js" assert headers["cache-control"] == "no-cache" viewer.dev_port = None - assert (await _request(app, "/"))[0] == 200 + assert (await a_request(app, "/"))[0] == 200 def test_only_a_checkout_runs_the_dev_server( @@ -1434,11 +1401,11 @@ async def test_a_refused_viewer_answers_every_path_with_why(tmp_path: Path) -> N app = Starlette(routes=[Mount("/", viewer)]) viewer.refusal = "The viewer is out of date." for path in ("/", "/assets/index.js"): - status, headers, body = await _request(app, path) + status, headers, body = await a_request(app, path) assert (status, body) == (503, b"The viewer is out of date.") assert headers["cache-control"] == "no-cache" viewer.refusal = None - assert (await _request(app, "/"))[0] == 200 + assert (await a_request(app, "/"))[0] == 200 async def test_startup_refuses_a_checkouts_stale_viewer_but_keeps_the_api( @@ -1454,5 +1421,5 @@ async def test_startup_refuses_a_checkouts_stale_viewer_but_keeps_the_api( client.project = dataclasses.replace(client.project, root=tmp_path) app = create_app(client) async with app.router.lifespan_context(app): - assert (await _request(app, "/"))[0] == 503 - assert (await _request(app, "/api/experiment_readme"))[0] == 200 + assert (await a_request(app, "/"))[0] == 503 + assert (await a_request(app, "/api/experiment_readme"))[0] == 200 diff --git a/scripts/skills/CODE_OVERVIEW.md b/scripts/skills/CODE_OVERVIEW.md index 5ca68b1..88c871e 100644 --- a/scripts/skills/CODE_OVERVIEW.md +++ b/scripts/skills/CODE_OVERVIEW.md @@ -9,7 +9,7 @@ setup and publishing. ``` skills/ -├── sync.mjs CLI: prepare this checkout and sync each marketplace checkout given +├── sync.mjs CLI: prepare this checkout and sync or check the given marketplaces ├── plugin.mjs marketplace kinds (Claude Code, Codex), plugin file comparison, copying, │ manifests, and patch version bumps ├── prepare.mjs CLI: checkout and new output directory; errors on stderr, nonzero exit @@ -47,8 +47,10 @@ not). Provenance records the source revision, package versions, and whether source or preparation tooling differs from the revision; each skill's content hash covers its other generated files. Plugin sync ignores provenance when comparing content, so a new source commit alone causes -neither a write nor a version bump. Content changes bump the plugin manifest's patch version, and the -marketplace entry's where it has one; first sync creates version 0.1.0. Each marketplace's plugin +neither a write nor a version bump. A content change copies all shipped skills from one snapshot +and bumps the plugin manifest's patch version and the marketplace entry's where it has one. +`sync.mjs --check` uses the same comparison and exits nonzero if a marketplace needs an update, +without writing files. First sync creates version 0.1.0. Each marketplace's plugin keeps its own version. Other plugins and manifest fields are preserved. The output directory is the boundary between preparation and sync. Every skill is fully diff --git a/scripts/skills/plugin.mjs b/scripts/skills/plugin.mjs index 41a8989..4b383ff 100644 --- a/scripts/skills/plugin.mjs +++ b/scripts/skills/plugin.mjs @@ -22,16 +22,16 @@ const initialVersion = '0.1.0'; const readJson = file => JSON.parse(readFileSync(file, 'utf8')); const isDirectory = file => existsSync(file) && statSync(file).isDirectory(); -function sameTree(a, b) { +function sameTree(a, b, skillRoot = true) { if (!isDirectory(a) || !isDirectory(b)) return false; const entries = directory => readdirSync(directory) - .filter(name => name !== '__pycache__' && name !== provenanceFile).sort(); + .filter(name => name !== '__pycache__' && !(skillRoot && name === provenanceFile)).sort(); const left = entries(a), right = entries(b); return left.length === right.length && left.every((name, i) => { if (name !== right[i]) return false; const source = path.join(a, name), target = path.join(b, name); const sourceStat = statSync(source), targetStat = statSync(target); - if (sourceStat.isDirectory()) return sameTree(source, target); + if (sourceStat.isDirectory()) return sameTree(source, target, false); return sourceStat.isFile() && targetStat.isFile() && readFileSync(source).equals(readFileSync(target)); }); @@ -128,8 +128,8 @@ export function marketplaceKind(marketplaceRoot) { : `${marketplaceRoot} has both ${files}; sync one marketplace per checkout`); } -/** Return the new plugin version, or null when no files changed. */ -export function syncPlugin(marketplaceRoot, prepared) { +/** Return the new plugin version, or null when current. checkOnly leaves the checkout untouched. */ +export function syncPlugin(marketplaceRoot, prepared, {checkOnly = false} = {}) { const kind = marketplaceKinds[marketplaceKind(marketplaceRoot)]; const marketplacePath = path.join(marketplaceRoot, kind.marketplace); const marketplace = readJson(marketplacePath); @@ -141,10 +141,10 @@ export function syncPlugin(marketplaceRoot, prepared) { throw new Error(`${prepared} has no ${name}/SKILL.md`); } } - const changed = skillNames.filter(name => !sameTree( + const sameSkills = skillNames.every(name => sameTree( path.join(prepared, name), path.join(pluginRoot, 'skills', name), )); - if (!changed.length && entries.length && existsSync(manifestPath)) return null; + if (sameSkills && entries.length && existsSync(manifestPath)) return null; let manifest, version; if (entries.length && existsSync(manifestPath)) { @@ -155,11 +155,12 @@ export function syncPlugin(marketplaceRoot, prepared) { version = initialVersion; manifest = kind.newManifest(version); } + if (checkOnly) return version; if (!entries.length) marketplace.plugins.push(kind.newEntry(version)); else if (kind.entryVersions) entries[0].version = version; - // Validate the manifests and complete bundle before replacing any plugin files. - for (const name of changed) { + // Even skills with identical content belong to the same prepared snapshot. + for (const name of skillNames) { const target = path.join(pluginRoot, 'skills', name); rmSync(target, {recursive: true, force: true}); cpSync(path.join(prepared, name), target, {recursive: true}); diff --git a/scripts/skills/plugin.test.mjs b/scripts/skills/plugin.test.mjs index f5040cd..670140f 100644 --- a/scripts/skills/plugin.test.mjs +++ b/scripts/skills/plugin.test.mjs @@ -58,10 +58,22 @@ test('first sync, no writes for provenance alone, and a version bump for documen write(prepared, 'fxtr/provenance.json', '{"revision":"later"}\n'); assert.equal(syncPlugin(marketplace, prepared), null); assert.deepEqual(snapshot(marketplace), before); + write(prepared, 'fxtr/assets/provenance.json', '{}\n'); + assert.equal(syncPlugin(marketplace, prepared, {checkOnly: true}), '0.1.1'); + assert.deepEqual(snapshot(marketplace), before); write(checkout, 'docs/fxtr/unlisted.mdx', '# Changed\n'); const changed = prepareSkills(checkout, path.join(root, 'changed')); + for (const name of ['fxtr', 'behaviors', 'first-experiment']) { + const file = `${name}/provenance.json`; + write(changed, file, JSON.stringify({...readJson(path.join(changed, file)), revision: 'a'.repeat(40)})); + } + assert.equal(syncPlugin(marketplace, changed, {checkOnly: true}), '0.1.1'); + assert.deepEqual(snapshot(marketplace), before); assert.equal(syncPlugin(marketplace, changed), '0.1.1'); + for (const name of ['fxtr', 'behaviors', 'first-experiment']) { + assert.equal(readJson(path.join(plugin, 'skills', name, 'provenance.json')).revision, 'a'.repeat(40)); + } assert.equal(readFileSync(path.join(plugin, 'skills/fxtr/references/unlisted.mdx'), 'utf8'), '# Changed\n'); assert.equal(readJson(manifest).version, '0.1.1'); assert.equal(readJson(path.join(marketplace, '.claude-plugin/marketplace.json')).plugins[1].version, '0.1.1'); @@ -147,6 +159,15 @@ test('sync CLI prepares once and syncs every marketplace given', t => { }); assert.match(output, /Claude Code: synced the skills into the fxtr plugin at version 0.1.0/); assert.match(output, /Codex: synced the skills into the fxtr plugin at version 0.1.0/); + const check = () => spawnSync(process.execPath, [path.join(tool, 'sync.mjs'), '--check', marketplace, codex], + {cwd: root, env: {...process.env, PATH: ''}, encoding: 'utf8'}); + assert.equal(check().status, 0); + write(codex, 'plugins/fxtr/skills/fxtr/SKILL.md', 'Draft with different content\n'); + const stale = snapshot(codex); + const mismatch = check(); + assert.equal(mismatch.status, 1); + assert.match(mismatch.stderr, /Codex: .*needs a content update/); + assert.deepEqual(snapshot(codex), stale); // A checkout of neither kind is refused before any marketplace is written. const before = snapshot(codex); const refused = spawnSync(process.execPath, [path.join(tool, 'sync.mjs'), codex, path.join(root, 'checkout')], {encoding: 'utf8'}); diff --git a/scripts/skills/sync.mjs b/scripts/skills/sync.mjs index facbcad..dfb3cb5 100644 --- a/scripts/skills/sync.mjs +++ b/scripts/skills/sync.mjs @@ -8,8 +8,10 @@ import {fileURLToPath} from 'node:url'; let scratch; try { const marketplaces = process.argv.slice(2); + const checkOnly = marketplaces[0] === '--check'; + if (checkOnly) marketplaces.shift(); if (!marketplaces.length) { - throw new Error('usage: pnpm sync:plugin PATH/TO/claude-code-plugins [PATH/TO/codex-plugins ...]'); + throw new Error('usage: pnpm sync:plugin [--check] PATH/TO/claude-code-plugins [PATH/TO/codex-plugins ...]'); } if (Number(process.versions.node.split('.')[0]) < 22) throw new Error('plugin sync requires Node 22 or newer'); const {prepareSkills} = await import('./bundle.mjs'); @@ -19,7 +21,12 @@ try { scratch = mkdtempSync(path.join(tmpdir(), 'fxtr-plugin-')); const prepared = prepareSkills(fileURLToPath(new URL('../../', import.meta.url)), path.join(scratch, 'skills')); marketplaces.forEach((marketplace, i) => { - const version = syncPlugin(path.resolve(marketplace), prepared); + const version = syncPlugin(path.resolve(marketplace), prepared, {checkOnly}); + if (checkOnly && version !== null) { + console.error(`${kinds[i].label}: the fxtr plugin needs a content update`); + process.exitCode = 1; + return; + } console.log(version === null ? `${kinds[i].label}: the plugin's skills are up to date` : `${kinds[i].label}: synced the skills into the fxtr plugin at version ${version}`); }); diff --git a/ts/CODE_OVERVIEW.md b/ts/CODE_OVERVIEW.md index e0318e6..a7ee334 100644 --- a/ts/CODE_OVERVIEW.md +++ b/ts/CODE_OVERVIEW.md @@ -99,8 +99,9 @@ packages/fxtr-view/src/ ├── renderer.ts ViewDecl and declareView (a view as links name it: slot, subject type, id, │ the params it reads, the view it is declared within), Renderer (slot, │ subjectType, id, Component, params, within) and renderer() (of a declaration, -│ its component handed the params it declares: ViewProps, BoundParams; or of a -│ slot, subject type and id, reading none), ANY_SUBJECT_TYPE (the subject type of a +│ its component handed the params it declares: ViewProps, BoundParams, every one +│ bound but an entity view's optional (ParamsOptional); or of a slot, subject +│ type and id, reading none), ANY_SUBJECT_TYPE (the subject type of a │ renderer for every subject of its slot); what a package exports, nothing that │ dispatches ├── shell.tsx ViewShell (useEntity, the optional useInvocation, useKeys and useLink, @@ -108,14 +109,15 @@ packages/fxtr-view/src/ │ LoadResult (a pending result carries its completion promise), unwrap (the │ value, or suspend), the context with its faulting default, │ ViewShellProvider, useEntity, useInvocation -├── builtin_slots.ts EntityPanel (props: id + StorageAtom), EntityInlineLink (static content only: +├── builtin_slots.ts EntityPanel (props: id + StorageAtom + params), EntityInlineLink (static content only: │ the shell wraps it in interactive chrome), EntityHoverPreview (props: id); │ InvocationPanel (props: invocations + StorageAtom + params); PagePanel │ (props: the run + params + StorageAtom), declarePage() and page() ├── link.tsx EntityLink (renders the shell's EntityLinkImpl), LinkBase / useLinkPlace │ (where a value sits), useLink (a link to a declared view, a location relative │ to the view, or both: LinkTo, handed to the shell as a ViewLinkSpec; its -│ params, LinkParams, must bind the view's), useEntityLinks (EntityLinks: +│ params, LinkParams, must bind the view's required ones), ParamValue / ViewParams +│ (a param's value: any JSON), useEntityLinks (EntityLinks: │ open an entity as following its link would, and whether the shell shows it │ now; nothing opens under a shell without it) ├── cid.tsx CidText: a full cid with the prefix / tail marked to recede and the short run @@ -162,7 +164,11 @@ Concepts, briefly (the plan has the rationale): registers `renderer(decl, Component)`, so a view's module links to others by their declarations without importing their components. The component of a declared view is handed every param it declares (`ViewProps`: the slot's props, with `params` binding each), since a host - shows the view only once they are all bound; their values are the view's to check. A **detail view** (what a renderer opens for something picked in it) + shows the view only once they are all bound; their values are any JSON (`ParamValue`), the + view's to check. An entity view's (`EntityPanel`) params are optional instead: a host opens an + entity from links binding none, so `params` holds those bound where it is opened. Their main use + is a *selector*, telling the view which part of the entity to point out; fxtr-view gives it no + shape of its own. A **detail view** (what a renderer opens for something picked in it) is a view that reads more params, optionally declared `within` the one view that links to it: its id is that view's, `/`, and its own name, and only that view may link to it. A **page** (`declarePage(name, { params, within })` and `page(decl, Component)`, the `PagePanel` slot) is a @@ -208,8 +214,9 @@ Concepts, briefly (the plan has the rationale): `EntityLink`'s `to`; the frontend's `panes/address.ts`), or both, and the params it is opened at; a link's params must bind the params its view declares, which the types check. An `EntityLink` either says where its entity sits in the value the view was handed (`at`, extending - the enclosing `LinkBase`), the way to link to anything inside it, or names somewhere else (`to`, - `view`, `params`: another step's output, an input); the types allow one or the other. A shell that + the enclosing `LinkBase`), the way to link to anything inside it, names somewhere else (`to`, + `view`, `params`: another step's output, an input), or opens the entity alone at `params` for + its views (a selector, which is about that one entity); the types allow one of these. A shell that opens no views yields null, and the renderer shows its detail in place. The default value faults on use. - **State.** Plain jotai. A panel gets a JSON-only `StorageAtom`; `validatedAtom` narrows it to @@ -356,7 +363,8 @@ test/ id threaded in (a reference is a bare cid, so the type is only in the data). `RenderInvocation` takes an invocation slot, the step / workflow `name` (which the host already has from its run data), and the spawns. Each accepts only its own kind of slot; both go through - `RenderSlot`. `useRenderers(slot, subjectType)` lists the alternatives a host + `RenderSlot`, which hands a renderer a slot's `params` prop narrowed to the params it declares, + so a host can give every view of an entity the same params. `useRenderers(slot, subjectType)` lists the alternatives a host builds its switcher from, the same list dispatch picks the first of. A host keeping a choice reads it back with `chosenRenderer(renderers, remembered)`, which falls back to the default (null) once the remembered id is no longer offered, and a host that also needs the renderer @@ -499,7 +507,10 @@ adds the renderers of the project's view bundle after these. `TranscriptGroup`, `AgentRun`, and session initialization. `entities.tsx` and `messages.tsx` present conversations, metadata, usage, and failures. `types.ts` exports the current type tags and wire shapes; rollouts, their turns, and their end records use `.v2`, and a rollout's -`initialization` is a tagged record or explicit null. Rollout and turn metadata arrives as a list +`initialization` is a tagged record or explicit null. The `ChatRollout` and `Transcript` +conversation views are declared in `selector.ts` and read a `selector` param, a `MessageSelector` +(`{ message: n }`, the `n`th message the view draws), which `Messages` marks and scrolls to; it +is provisional, and its producer's shape is kept the same by hand. Rollout and turn metadata arrives as a list of tagged records, each shown under its type tag, and usage totals come from the `ModelResponse` records models leave in their turns' metadata. `comparison.tsx` aligns pairs of rollouts; its `behaviorsRenderers` registers only shared entity types. A behaviors project's own diff --git a/ts/packages/fxtr-view-behaviors/src/behaviors.module.css b/ts/packages/fxtr-view-behaviors/src/behaviors.module.css index 855110a..bf4cf0f 100644 --- a/ts/packages/fxtr-view-behaviors/src/behaviors.module.css +++ b/ts/packages/fxtr-view-behaviors/src/behaviors.module.css @@ -14,6 +14,8 @@ .message[data-role="assistant"] { background: var(--role-assistant-bg); } .message[data-role="tool"] { background: var(--role-tool-bg); } .message[data-role="system"] { background: var(--role-system-bg); } +/* The message a selector picks: a marker's colour, not the shell's selection blue. */ +.message[data-selected] { outline: 2px solid light-dark(#e0b100, #c99a00); outline-offset: 1px; } .role { display: flex; flex-wrap: wrap; align-items: baseline; gap: 2px 8px; margin-bottom: 2px; font-size: var(--text-xs); font-weight: 600; text-transform: uppercase; letter-spacing: 0.02em; line-height: 1.7; overflow-wrap: anywhere; } .role .muted { text-transform: none; font-weight: normal; } .prose { white-space: pre-wrap; overflow-wrap: anywhere; line-height: 1.4; font-size: var(--text-md); } diff --git a/ts/packages/fxtr-view-behaviors/src/entities.tsx b/ts/packages/fxtr-view-behaviors/src/entities.tsx index a91e050..1017f15 100644 --- a/ts/packages/fxtr-view-behaviors/src/entities.tsx +++ b/ts/packages/fxtr-view-behaviors/src/entities.tsx @@ -1,5 +1,6 @@ import styles from "./behaviors.module.css"; -import { unwrap, useEntity, type EntityData, type EntityID, type EntityViewProps } from "fxtr-view"; +import { unwrap, useEntity, type EntityData, type EntityID, type EntityPanelProps, type EntityViewProps } from "fxtr-view"; +import { isMessageSelector } from "./selector"; import { Messages, Metadata, MetadataList, usageOf } from "./messages"; import { AGENT_RUN, CHAT_ROLLOUT, SET_SYSTEM_MESSAGE, TRANSCRIPT, TRANSCRIPT_GROUP, @@ -60,9 +61,20 @@ export function Initialization({ data }: { data: EntityData | null }) { ; } -export function ChatRolloutView({ data }: { data: ChatRolloutData }) { +/** A rollout's conversation, turn by turn; `selected` is the index of the message a selector picks + * (`MessageSelector`), marked. */ +export function ChatRolloutView({ data, selected = null }: { data: ChatRolloutData; selected?: number | null }) { const usage = usageOf(data.model_turns); const turnCount = Math.max(data.context_turns.length, data.model_turns.length); + // Where each turn's context and model messages start among the conversation's messages. + const starts: { context: number; model: number }[] = []; + let next = 0; + for (let index = 0; index < turnCount; index++) { + const context = next; + next += data.context_turns[index]?.messages.length ?? 0; + starts.push({ context, model: next }); + next += data.model_turns[index]?.messages.length ?? 0; + } return (
@@ -81,8 +93,9 @@ export function ChatRolloutView({ data }: { data: ChatRolloutData }) { return (

Turn {index + 1}

- {context && } - {model ? :

No model response recorded.

} + {context && } + {model ? + :

No model response recorded.

} {(context || model) && (
Turn details @@ -103,7 +116,7 @@ export function ChatRolloutView({ data }: { data: ChatRolloutData }) { ); } -function TranscriptView({ data }: { data: TranscriptData }) { +function TranscriptView({ data, selected = null }: { data: TranscriptData; selected?: number | null }) { return (
@@ -112,7 +125,7 @@ function TranscriptView({ data }: { data: TranscriptData }) { {data.description &&

{data.description}

}
{countLabel(data.messages.length, "message")}
- {data.messages.length ? :

No messages recorded.

} + {data.messages.length ? :

No messages recorded.

}
); @@ -145,11 +158,16 @@ function GroupView({ data }: { data: TranscriptGroupData }) { ); } -export function BehaviorPanel({ id }: EntityViewProps) { +/** A conversation in full. For a `ChatRollout` or a `Transcript`, a `selector` param that is a + * `MessageSelector` marks its message (one of another shape, or past the last message, marks + * nothing). */ +export function BehaviorPanel({ id, params }: EntityPanelProps) { const data = unwrap(useEntity(id as EntityID)); + const selector = params?.["selector"]; + const selected = isMessageSelector(selector) ? selector.message : null; switch (data.$type) { - case CHAT_ROLLOUT: return ; - case TRANSCRIPT: return ; + case CHAT_ROLLOUT: return ; + case TRANSCRIPT: return ; case TRANSCRIPT_GROUP: case AGENT_RUN: return ; case SET_SYSTEM_MESSAGE: diff --git a/ts/packages/fxtr-view-behaviors/src/index.ts b/ts/packages/fxtr-view-behaviors/src/index.ts index 2b31b46..bc809bd 100644 --- a/ts/packages/fxtr-view-behaviors/src/index.ts +++ b/ts/packages/fxtr-view-behaviors/src/index.ts @@ -1,15 +1,20 @@ import { EntityHoverPreview, EntityInlineLink, EntityPanel, renderer } from "fxtr-view"; import { BehaviorInlineLink, BehaviorPanel, BehaviorPreview } from "./entities"; +import { CHAT_ROLLOUT_CONVERSATION, TRANSCRIPT_CONVERSATION } from "./selector"; import { AGENT_RUN, CHAT_ROLLOUT, SET_SYSTEM_MESSAGE, TRANSCRIPT, TRANSCRIPT_GROUP } from "./types"; export * from "./types"; +export { CHAT_ROLLOUT_CONVERSATION, TRANSCRIPT_CONVERSATION, isMessageSelector, type MessageSelector } from "./selector"; export { BehaviorInlineLink, BehaviorPanel, BehaviorPreview, ChatRolloutView } from "./entities"; export { ComparedRollouts } from "./comparison"; -/** Entity renderers shared by projects that store behaviors conversations. */ +/** Entity renderers shared by projects that store behaviors conversations. A `ChatRollout`'s and a + * `Transcript`'s conversation views read a `selector` (`MessageSelector`). */ export const behaviorsRenderers = [ + renderer(CHAT_ROLLOUT_CONVERSATION, BehaviorPanel), + renderer(TRANSCRIPT_CONVERSATION, BehaviorPanel), + ...[TRANSCRIPT_GROUP, AGENT_RUN, SET_SYSTEM_MESSAGE].map((type) => renderer(EntityPanel, type, "conversation", BehaviorPanel)), ...[CHAT_ROLLOUT, TRANSCRIPT, TRANSCRIPT_GROUP, AGENT_RUN, SET_SYSTEM_MESSAGE].flatMap((type) => [ - renderer(EntityPanel, type, "conversation", BehaviorPanel), renderer(EntityInlineLink, type, "summary", BehaviorInlineLink), renderer(EntityHoverPreview, type, "summary", BehaviorPreview), ]), diff --git a/ts/packages/fxtr-view-behaviors/src/messages.tsx b/ts/packages/fxtr-view-behaviors/src/messages.tsx index 696663f..3d4a1de 100644 --- a/ts/packages/fxtr-view-behaviors/src/messages.tsx +++ b/ts/packages/fxtr-view-behaviors/src/messages.tsx @@ -1,4 +1,5 @@ import styles from "./behaviors.module.css"; +import { useEffect, useRef } from "react"; import { isDataMap, type DataMap } from "fxtr-view"; import { MODEL_RESPONSE, type ContentData, type MessageData, type MetadataEntries, type TurnData } from "./types"; @@ -54,11 +55,24 @@ function ContentBlock({ block }: { block: ContentData }) { } } -export function Messages({ messages }: { messages: readonly MessageData[] }) { +/** `messages`, each in its role's colours. `first` is the index of the first of them among the + * messages of the whole conversation, and `selected` the index there of the one a selector picks + * (`MessageSelector`), which is marked, and scrolled into view when it is picked. */ +export function Messages({ messages, first = 0, selected = null }: { + messages: readonly MessageData[]; + first?: number; + selected?: number | null; +}) { + const marked = useRef(null); + const local = selected === null ? -1 : selected - first; + useEffect(() => { + marked.current?.scrollIntoView?.({ block: "center" }); + }, [local]); return (
{messages.map((message, index) => ( -
+
{message.role} {message.role === "tool" && ( diff --git a/ts/packages/fxtr-view-behaviors/src/selector.ts b/ts/packages/fxtr-view-behaviors/src/selector.ts new file mode 100644 index 0000000..9a7db1f --- /dev/null +++ b/ts/packages/fxtr-view-behaviors/src/selector.ts @@ -0,0 +1,26 @@ +// A selector into a conversation, the param of the conversation views of a `ChatRollout` and a +// `Transcript`: it picks one message, which the view marks and scrolls to. A link sets it (an +// entity holding a selector beside a reference to the conversation links there with it). It is +// provisional, and will give way to a fuller kind of selector. +// +// Nothing ties it to the Python side: a producer stores the same shape (a dataclass with a +// `message` int field), and the view ignores a value of another shape. + +import { EntityPanel, declareView, type ParamValue } from "fxtr-view"; +import { CHAT_ROLLOUT, TRANSCRIPT } from "./types"; + +/** One message of a conversation: its index among the messages the conversation view draws, in + * order. A `Transcript`'s are its messages; a `ChatRollout`'s are each turn's context messages and + * then its model's, turn by turn (its initialization is not counted). */ +export type MessageSelector = { readonly message: number }; + +/** Whether a param's value is a `MessageSelector`. */ +export function isMessageSelector(value: ParamValue | undefined): value is MessageSelector { + if (typeof value !== "object" || value === null || Array.isArray(value)) return false; + const message = (value as { readonly [key: string]: ParamValue })["message"]; + return typeof message === "number" && Number.isInteger(message) && message >= 0; +} + +/** The conversation views reading a selector (`selector`), by the type they show. */ +export const CHAT_ROLLOUT_CONVERSATION = declareView(EntityPanel, CHAT_ROLLOUT, "conversation", { params: ["selector"] }); +export const TRANSCRIPT_CONVERSATION = declareView(EntityPanel, TRANSCRIPT, "conversation", { params: ["selector"] }); diff --git a/ts/packages/fxtr-view-behaviors/test/renderers.test.tsx b/ts/packages/fxtr-view-behaviors/test/renderers.test.tsx index 082fe95..9e32689 100644 --- a/ts/packages/fxtr-view-behaviors/test/renderers.test.tsx +++ b/ts/packages/fxtr-view-behaviors/test/renderers.test.tsx @@ -60,6 +60,24 @@ it("interleaves context/model turns instead of grouping all answers together", ( expect(screen.getByText("2 responses")).toBeTruthy(); }); +it("marks the message a selector picks, counting turn by turn, and ignores one of another shape", () => { + const marked = (params: Record) => { + const { container, unmount } = render( + + (null)} params={params} /> + , + ); + const found = [...container.querySelectorAll(".message[data-selected]")].map((node) => node.textContent); + unmount(); + return found; + }; + expect(marked({ selector: { message: 2 } })).toEqual(["userFollow-up question"]); + expect(marked({ selector: { message: 3 } })).toEqual(["assistantSecond answer"]); + expect(marked({ selector: { message: 9 } })).toEqual([]); + expect(marked({ selector: "2" })).toEqual([]); + expect(marked({})).toEqual([]); +}); + const initialization = (text: string) => ({ $type: SET_SYSTEM_MESSAGE, message: { ...message("user", text), $type: tag("SystemMessage"), role: "system" as const }, diff --git a/ts/packages/fxtr-view-shell-util/src/render.tsx b/ts/packages/fxtr-view-shell-util/src/render.tsx index 9f14940..5f615d8 100644 --- a/ts/packages/fxtr-view-shell-util/src/render.tsx +++ b/ts/packages/fxtr-view-shell-util/src/render.tsx @@ -13,7 +13,9 @@ // renderer, the entity id, the spawns) remounts the dispatched subtree, which is also what clears a // caught error. So does a new registry: a host may replace its registry while it runs (the // frontend does when a project's renderers are rebuilt), and a renderer that threw gets another -// chance with the new code. +// chance with the new code. A slot's `params` prop reaches a renderer narrowed to the params it +// declares, so a host can hand every renderer of an entity the same params (the entity's views' +// params are optional, and a view switcher keeps them across its views). import { Component, Suspense, createContext, useContext, type ErrorInfo, type ReactNode } from "react"; import { idKey, @@ -23,6 +25,7 @@ import { type EntityViewProps, type InvocationViewProps, type Renderer, + type ViewParams, type ViewSlot, } from "fxtr-view"; import { DispatchFault } from "./errors"; @@ -144,12 +147,21 @@ export function RenderSlot(props: RenderSlotProps) renderError={shown.error} > - {found === undefined ? shown.noRenderer(subjectType) : } + {found === undefined ? shown.noRenderer(subjectType) : } ); } +/** `props` with its `params`, when it has them, narrowed to those `found` declares. */ +function narrowParams(props: Props, found: Renderer): Props { + const params = (props as { params?: ViewParams }).params; + if (params === undefined) return props; + const declared = found.params ?? []; + const narrowed = Object.fromEntries(declared.flatMap((name) => (Object.hasOwn(params, name) ? [[name, params[name]!]] : []))); + return { ...props, params: narrowed }; +} + /** Props of `RenderEntity`: the entity slot, optionally the renderer id and the host's fallbacks, * and the slot's props (which include the id). */ export type RenderEntityProps = { diff --git a/ts/packages/fxtr-view-shell-util/test/render.test.tsx b/ts/packages/fxtr-view-shell-util/test/render.test.tsx index e077657..1f349a1 100644 --- a/ts/packages/fxtr-view-shell-util/test/render.test.tsx +++ b/ts/packages/fxtr-view-shell-util/test/render.test.tsx @@ -146,6 +146,34 @@ describe("RenderSlot", () => { }); describe("RenderEntity", () => { + it("hands a renderer only the params it declares", () => { + const HIGHLIGHT = declareView(EntityPanel, "org.example.Note", "highlight", { params: ["selector"] }); + const seen: unknown[] = []; + const withParams = dispatchRegistry([ + renderer(HIGHLIGHT, ({ params }) => { + seen.push(params); + return
highlight
; + }), + renderer(EntityPanel, "org.example.Note", "plain", (props: EntityPanelProps) => { + seen.push(props.params); + return
plain
; + }), + ]); + const params = { selector: { line: 2 }, other: "x" }; + const { rerender } = render( + + + , + ); + expect(screen.getByText("highlight")).toBeTruthy(); + rerender( + + + , + ); + expect(screen.getByText("plain")).toBeTruthy(); + expect(seen).toEqual([{ selector: { line: 2 } }, {}]); + }); it("shows Loading, then the dispatched component with the id", () => { const { rerender } = render( @@ -451,7 +479,7 @@ describe("RenderInvocation", () => { describe("views declared within another", () => { function Detail({ invocations, params }: InvocationPanelProps) { - return
detail {invocations.length} {params?.["point"]}
; + return
detail {invocations.length} {String(params?.["point"])}
; } const CHART = declareView(InvocationPanel, "rollout", "chart"); const POINT = declareView(InvocationPanel, "rollout", "point", { within: CHART, params: ["point"] }); diff --git a/ts/packages/fxtr-view/src/builtin_slots.ts b/ts/packages/fxtr-view/src/builtin_slots.ts index 1f2469f..b7263d6 100644 --- a/ts/packages/fxtr-view/src/builtin_slots.ts +++ b/ts/packages/fxtr-view/src/builtin_slots.ts @@ -13,9 +13,12 @@ import { declareViewSlot, type EntityViewProps, type InvocationViewProps } from /** A panel's persistent per-mount state. JSON only, so a shell may persist it. */ export type StorageAtom = PrimitiveAtom; -/** Props of an `EntityPanel` view: the entity shown and per-mount storage. */ +/** Props of an `EntityPanel` view: the entity shown, per-mount storage, and the params it + * declares that are bound where it is opened (all optional: a plain link to the entity binds + * none). A host that binds none leaves `params` out. */ export interface EntityPanelProps extends EntityViewProps { readonly storage: StorageAtom; + readonly params?: ViewParams; } /** Props of a link view: the id alone. */ diff --git a/ts/packages/fxtr-view/src/index.ts b/ts/packages/fxtr-view/src/index.ts index 60a7d3e..d71c1fd 100644 --- a/ts/packages/fxtr-view/src/index.ts +++ b/ts/packages/fxtr-view/src/index.ts @@ -33,6 +33,8 @@ export { type AnyRenderer, type AnyViewDecl, type BoundParams, + type DeclaredViewProps, + type ParamsOptional, type ViewProps, type Renderer, type ViewDecl, @@ -87,6 +89,7 @@ export { useEntityLinks, useLink, type LinkTo, + type ParamValue, type ViewLink, type ViewLinkSpec, type ViewParams, diff --git a/ts/packages/fxtr-view/src/link.tsx b/ts/packages/fxtr-view/src/link.tsx index 313fe87..8804c32 100644 --- a/ts/packages/fxtr-view/src/link.tsx +++ b/ts/packages/fxtr-view/src/link.tsx @@ -10,6 +10,9 @@ // `LinkBase`, has no place, and the shell opens the entity itself. This is the way to link to // anything inside what the view was handed: it needs no location syntax, and generic components // (a data tree) can extend the place without knowing where they are drawn. +// - **The entity alone, at params** (`params`, no `at`): the entity itself, its views handed +// `params` (a selector into a transcript, which they read as optional params). A view's params +// apply to that one entity, so such a link opens it fixed, wherever the view drawing it sits. // - **Somewhere the view names** (`to`, `view`, `params`), as `useLink` does: for an entity the view // knows a better place of than inside its own value, such as a step's input or another step's // output. @@ -27,9 +30,10 @@ // It opens the entity alone; one hook serves every mark, so it fits marks drawn in a loop. import { createContext, useContext, type DragEvent, type MouseEvent, type ReactNode } from "react"; -import type { EntityID } from "./ids"; -import type { AnyViewDecl, ViewDecl } from "./renderer"; +import type { EntityID, JsonValue } from "./ids"; +import type { AnyViewDecl, ParamsOptional, ViewDecl } from "./renderer"; import { useViewShell } from "./shell"; +import type { ViewSlot } from "./slots"; /** A dim's key value, as a spawn's key holds it. */ export type LinkKeyValue = string | number; @@ -86,17 +90,45 @@ function extend(place: LinkPlace, at: LinkAt | undefined): LinkPlace { }; } +/** A param's value: any JSON. A dim's key is one too (`LinkKeyValue`); a view's param may be + * structured (a selector), and the view narrows it itself. */ +export type ParamValue = JsonValue; + /** Values bound to params by name: the dims of a step, and the params views declare. */ -export type ViewParams = Readonly>; +export type ViewParams = Readonly>; /** The params a link to a view reading `Params` is opened at: a row's full keys, say, among which * each of `Params` is bound. */ -export type LinkParams = ViewParams & { readonly [Name in Params]: LinkKeyValue }; - -/** A link's `params`: required, and binding each of `Params`, when the target declares any. */ -type ParamsProp = [Params] extends [never] - ? { readonly params?: ViewParams } - : { readonly params: LinkParams }; +export type LinkParams = ViewParams & { readonly [Name in Params]: ParamValue }; + +/** The params a link to `View` takes: any, when it declares none, is an entity view (whose params + * are optional), or is not known (a location alone, or any declaration); otherwise required, + * binding each it declares. A tuple, for a rest parameter. + * + * The cases, in order: `never` is what `useLink` infers for a target naming no view (a location + * alone), and is checked in a tuple since a bare `never` would distribute to `never`; a `Params` + * of `string` is a declaration typed as any declaration (`AnyViewDecl`, `LinkTo`), whose names + * are unknown, so nothing can be required; then the slot decides (`ParamsOptional`). */ +type ParamsArgOf = [View] extends [never] + ? [params?: ViewParams] + // eslint-disable-next-line @typescript-eslint/no-explicit-any + : View extends ViewDecl + ? [Params] extends [never] + ? [params?: ViewParams] + : string extends Params + ? [params?: ViewParams] + : SlotParamsOptional extends true + ? [params?: ViewParams] + : [params: LinkParams] + : [params?: ViewParams]; + +/** Whether a slot's views read their params as optional (`ParamsOptional` of its props). */ +type SlotParamsOptional = Slot extends ViewSlot ? ParamsOptional : false; + +/** A link's `params`, as a prop: what `ParamsArgOf` says. */ +type ParamsProp = ParamsArgOf extends [params: infer P] + ? { readonly params: P } + : { readonly params?: ViewParams }; /** A link to where its entity sits in what the view was handed (`at`; none: the entity alone). */ interface PlacedLinkProps { @@ -107,43 +139,53 @@ interface PlacedLinkProps { readonly params?: never; } +/** A link to the entity alone, its views opened at `params` (a selector). */ +interface EntityParamsLinkProps { + readonly id: EntityID; + readonly at?: never; + readonly to?: never; + readonly view?: never; + readonly params: ViewParams; +} + /** A link to somewhere the view names in place of where the entity sits: a location (`to`, as * `useLink` takes it), a declared view (`view`), or both, opened at `params`. */ -type NamedLinkProps = { readonly id: EntityID; readonly at?: never } & ( - // eslint-disable-next-line @typescript-eslint/no-explicit-any - | { readonly to: string; readonly view?: ViewDecl } - // eslint-disable-next-line @typescript-eslint/no-explicit-any - | { readonly to?: string; readonly view: ViewDecl } +type NamedLinkProps = { readonly id: EntityID; readonly at?: never } & ( + | { readonly to: string; readonly view?: View } + | { readonly to?: string; readonly view: View } ) & - ParamsProp; + ParamsProp; -export type EntityLinkProps = PlacedLinkProps | NamedLinkProps; +export type EntityLinkProps = PlacedLinkProps | EntityParamsLinkProps | NamedLinkProps; /** What a link names, as a shell is handed it: a view's id (null: the default for what the * location shows) and the id of the view it is declared within, and a location in the host's - * syntax (null: the location of the view the link is in). */ + * syntax (null: the location of the view the link is in, or for a page, which has no location, + * none). */ export interface ViewLinkSpec { readonly view: string | null; readonly within: string | null; readonly to: string | null; } -/** What the shell's `EntityLinkImpl` is given: the id, the link's place when it has one, and what - * the link opens when the view named it. */ +/** What the shell's `EntityLinkImpl` is given: the id, the link's place when it has one, what the + * link opens when the view named it, or the params it opens the entity alone at. */ export interface EntityLinkImplProps { readonly id: EntityID; readonly place?: LinkPlace | null; readonly to?: { readonly spec: ViewLinkSpec; readonly params: ViewParams }; + readonly params?: ViewParams; } -export function EntityLink(props: EntityLinkProps) { +export function EntityLink(props: EntityLinkProps) { const { EntityLinkImpl } = useViewShell(); const enclosing = useContext(LinkPlaceContext); - const { id, at, to, view, params } = props; + // The union of the props' forms, read as one shape: each form leaves the others' fields absent. + const { id, at, to, view, params } = props as { id: EntityID; at?: LinkAt; to?: string; view?: AnyViewDecl; params?: ViewParams }; const place = at && enclosing ? extend(enclosing, at) : null; - const named = - to === undefined && view === undefined ? undefined : { spec: specOf(view ?? null, to ?? null), params: params ?? NO_PARAMS }; - return ; + if (to !== undefined || view !== undefined) + return ; + return ; } /** A link as the props to spread onto whatever element is picked (an SVG mark, a row), and whether @@ -161,22 +203,16 @@ export interface ViewLink { readonly selected: boolean; } -/** What `useLink` opens: a declared view (at the location of the view the link is in), a location - * (`to`) through its default view, or a declared view at a location. */ -export type LinkTo = - // eslint-disable-next-line @typescript-eslint/no-explicit-any - | ViewDecl - // eslint-disable-next-line @typescript-eslint/no-explicit-any - | { readonly view?: ViewDecl; readonly to: string }; - -/** `useLink`'s params: required, and binding each of `Params`, when the target declares any. */ -type ParamsArg = [Params] extends [never] ? [params?: ViewParams] : [params: LinkParams]; +/** What `useLink` opens: a declared view (at the location of the view the link is in; a page at + * none, wherever the link is), a location (`to`) through its default view, or a declared view at a + * location. */ +export type LinkTo = View | { readonly view?: View; readonly to: string }; /** A link to `target`, opened at `params` (null target: no link); null when the shell cannot open * views from here, so the renderer shows its detail in place instead. Pass a row's full keys: the * host keeps only what they add to this view's. A declared view's params must be among them. A * view declared within another is linked to only from that one. */ -export function useLink(target: LinkTo | null, ...[params]: ParamsArg): ViewLink | null { +export function useLink(target: LinkTo | null, ...[params]: ParamsArgOf): ViewLink | null { const shell = useViewShell(); if (shell.useLink === undefined) return null; const spec = target === null ? null : "slot" in target ? specOf(target, null) : specOf(target.view ?? null, target.to); diff --git a/ts/packages/fxtr-view/src/renderer.ts b/ts/packages/fxtr-view/src/renderer.ts index 7d43a3f..16bd71e 100644 --- a/ts/packages/fxtr-view/src/renderer.ts +++ b/ts/packages/fxtr-view/src/renderer.ts @@ -9,9 +9,15 @@ // declarations, never their components, and a typo in a view's name or params is a type error. A // detail view (a chart's point) is declared `within` the view that links to it: its id is the // parent's id, `/`, and its own name, and only the parent links to it. +// +// A view's params are names; their values are any JSON (`ParamValue`), which the view narrows +// itself, since they reach it through an address nothing validates. Whether a param must be bound +// follows the slot: an entity view's are optional (it is opened from plain links too, which bind +// none), every other view's are required (a host shows it only once they are all bound). import type { ComponentType } from "react"; -import type { LinkKeyValue } from "./link"; +import type { EntityPanelProps } from "./builtin_slots"; +import type { ParamValue } from "./link"; import type { ViewSlot } from "./slots"; /** The subject type of a renderer that fits every subject of its slot (the cbor-tree views of any @@ -32,14 +38,25 @@ export interface ViewDecl readonly within: string | null; } -/** The params a view declaring `Params` is handed: each of them, bound. */ -export type BoundParams = { readonly [Name in Params]: LinkKeyValue }; +/** Whether a view of a slot taking `Props` reads its params as optional: an entity view's are, + * since a host opens an entity from plain links that bind none. Told by the props, since a type + * sees no slot's identity: `EntityPanelProps` is the only built-in slot's props it matches (the + * invocation and page props have no `id`), and a slot declared with props extending it would + * read its params as optional too. */ +export type ParamsOptional = Props extends EntityPanelProps ? true : false; + +/** The params a view declaring `Params` is handed: each of them bound, or for `Optional`, each + * bound or absent. */ +export type BoundParams = Optional extends true + ? { readonly [Name in Params]?: ParamValue } + : { readonly [Name in Params]: ParamValue }; /** The props of a declared view's component: its slot's, and when it declares params, `params` - * binding each of them (a host shows the view only once they are all bound). */ + * binding them (`BoundParams`: every one, but an entity view's only those bound where it is + * opened). */ export type DeclaredViewProps = [Params] extends [never] ? Props - : Props & { readonly params: BoundParams }; + : Props & { readonly params: BoundParams> }; /** The props of the component of the declared view `View`: `ViewProps`. */ export type ViewProps = @@ -72,7 +89,7 @@ export function declareView /** One renderer. `id` must be unique among the renderers of its slot and subject type, and a * wildcard's among all of its slot's, since a host offers them side by side. `params` are the * params it reads, which a host binds by name where it is shown and hands in the slot's `params` - * prop; `within`, the id of the view it is declared within (a host offers it only through links + * prop (optional for an entity view, required for any other); `within`, the id of the view it is declared within (a host offers it only through links * from that one). */ export interface Renderer { readonly slot: ViewSlot; diff --git a/ts/packages/fxtr-view/src/view_bundle.ts b/ts/packages/fxtr-view/src/view_bundle.ts index 4830ec8..f1282df 100644 --- a/ts/packages/fxtr-view/src/view_bundle.ts +++ b/ts/packages/fxtr-view/src/view_bundle.ts @@ -14,7 +14,7 @@ import type { AnyRenderer } from "./renderer"; /** The version of the bundle contract, stamped into a bundle's manifest by the build. */ -export const VIEW_API_VERSION = 3; +export const VIEW_API_VERSION = 4; /** What a bundle contributes to a shell. A shell adds `renderers` after its own defaults; later * contributions are new fields. */ diff --git a/ts/packages/fxtr-view/test/renderer.test.ts b/ts/packages/fxtr-view/test/renderer.test.ts index 46898e1..1ef0955 100644 --- a/ts/packages/fxtr-view/test/renderer.test.ts +++ b/ts/packages/fxtr-view/test/renderer.test.ts @@ -1,5 +1,5 @@ import { describe, expect, expectTypeOf, it } from "vitest"; -import { EntityInlineLink, declareView, renderer, type Renderer } from "../src/index"; +import { EntityID, EntityInlineLink, EntityPanel, declareView, renderer, useLink, type EntityLinkProps, type ParamValue, type Renderer, type ViewProps } from "../src/index"; import { declareViewSlot } from "../src/slots"; const Card = declareViewSlot<{ readonly label: string }>("Card"); @@ -34,3 +34,34 @@ describe("declareView", () => { expect(() => declareView(Card, "org.example.Other", "point", { within: CHART })).toThrow(/another subject/); }); }); + +describe("params", () => { + const Run = declareViewSlot<{ readonly label: string }>("Run"); + const BATCH = declareView(Run, "org.example.Step", "batch", { params: ["prompt"] }); + const CONVERSATION = declareView(EntityPanel, "org.example.Transcript", "conversation", { params: ["selector"] }); + + it("binds every param of a view of another slot, and leaves an entity view's optional, each any JSON", () => { + expectTypeOf["params"]>().toEqualTypeOf<{ readonly prompt: ParamValue }>(); + expectTypeOf["params"]["selector"]>().toEqualTypeOf(); + }); + it("makes a link to a view bind its required params, and to an entity view none", () => { + // Type-only: these calls are never run. + const check = () => { + useLink(BATCH, { prompt: 3 }); + // @ts-expect-error the link leaves out a required param + useLink(BATCH, {}); + useLink(CONVERSATION); + useLink(CONVERSATION, { selector: { message: 2 } }); + useLink({ to: "/judge" }); + }; + void check; + }); + it("lets an entity link carry params to the entity alone, not at a place", () => { + const id = new EntityID("cid1"); + const alone: EntityLinkProps = { id, params: { selector: { message: 2 } } }; + // @ts-expect-error a link at a place carries no params + const placed: EntityLinkProps = { id, at: { path: ["transcript"] }, params: { selector: 2 } }; + void alone; + void placed; + }); +}); diff --git a/uv.lock b/uv.lock index 03c63f7..5863b9b 100644 --- a/uv.lock +++ b/uv.lock @@ -365,7 +365,7 @@ wheels = [ [[package]] name = "behaviors" -version = "0.0.1a4" +version = "0.0.1a5" source = { editable = "behaviors" } dependencies = [ { name = "anyio" }, @@ -1037,7 +1037,7 @@ wheels = [ [[package]] name = "fxtr" -version = "0.1.0a0" +version = "0.2.0a0" source = { editable = "fxtr" } dependencies = [ { name = "anyio" }, @@ -1071,7 +1071,7 @@ requires-dist = [ { name = "asyncpg", marker = "extra == 'runner'", specifier = ">=0.30" }, { name = "cattrs", specifier = ">=26.1.0" }, { name = "cbrrr", specifier = ">=1.1.0" }, - { name = "duckdb", specifier = ">=1.5.0" }, + { name = "duckdb", specifier = ">=1.5.0,<2.0" }, { name = "frozendict", specifier = ">=2.4.6" }, { name = "fxtr", extras = ["runner"], marker = "extra == 'debug-web'" }, { name = "graphql-core", marker = "extra == 'debug-web'", specifier = ">=3.2,<3.3" },