@flowllm-ai/axonx-studio 0.0.1 → 0.0.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +145 -9
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,8 +1,31 @@
|
|
|
1
1
|
# AxonX Studio
|
|
2
2
|
|
|
3
|
-
AxonX
|
|
3
|
+
English · [简体中文](https://github.com/FlowLLM-AI/AxonX/blob/main/axonx_studio/README_ZH.md)
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
AxonX Studio is the browser workspace for [AxonX](https://github.com/FlowLLM-AI/AxonX/blob/main/README.md), an agent-native quantitative research framework. It connects task submission, execution monitoring, workspace artifacts, research charts, and an Agent assistant to the same AxonX service.
|
|
6
|
+
|
|
7
|
+
Studio is a React and TypeScript frontend. The AxonX backend executes Tasks, manages files and sessions, and exposes Job APIs; research plugins supply the algorithms. Available tasks, APIs, and results depend on the selected execution machine and its installed plugins.
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
## Features
|
|
12
|
+
|
|
13
|
+
| Area | Capabilities |
|
|
14
|
+
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
15
|
+
| Task submission | Browse installed Task definitions and generate configuration forms from JSON Schema, including upstream Task IDs. |
|
|
16
|
+
| Task management | Filter runs, inspect parameters and outputs, follow progress and logs, view upstream relationships, cancel tasks, and delete selected runs. |
|
|
17
|
+
| Machines | Switch between local and configured remote targets; inspect CPU, memory, GPU, and runtime information. |
|
|
18
|
+
| Data workspace | Browse Tushare data and preview workspace files, including paginated Parquet data. |
|
|
19
|
+
| Research results | Inspect ETL datasets, factor metrics, training configuration and curves, and prediction artifacts. |
|
|
20
|
+
| Backtests and comparison | View return curves, quality metrics, holdings, and yearly/quarterly/monthly summaries; compare two backtests over their common date window. |
|
|
21
|
+
| Agent | Stream responses and tool calls, resume conversations, rename/tag/fork/delete sessions, and stop the current turn. |
|
|
22
|
+
| API interfaces | Browse the selected machine's Job catalog and call APIs through schema-based forms. |
|
|
23
|
+
|
|
24
|
+
The interface supports English and Simplified Chinese, light/dark themes, and saved browser preferences. Hash routes preserve the selected machine and resource, for example `#local/task-defs/catalog/demo`.
|
|
25
|
+
|
|
26
|
+
## Install and start
|
|
27
|
+
|
|
28
|
+
Use an activated Python environment with **Python 3.12+**. Local Task execution is supported on macOS and Linux. Prebuilt Studio packages require no Node.js or frontend build.
|
|
6
29
|
|
|
7
30
|
```bash
|
|
8
31
|
pip install "axonx[studio]"
|
|
@@ -10,26 +33,139 @@ export AXONX_SERVICE_TOKEN='replace-with-your-local-service-token'
|
|
|
10
33
|
axonx start --service.host 127.0.0.1
|
|
11
34
|
```
|
|
12
35
|
|
|
13
|
-
|
|
36
|
+
Open <http://127.0.0.1:1024/>. In **Settings → Local service token**, enter the same token and apply it. Studio saves the token in browser local storage and sends it as a Bearer token on API requests. Use the same settings form to replace or clear it.
|
|
14
37
|
|
|
15
|
-
|
|
38
|
+
You can also place `AXONX_SERVICE_TOKEN` in a `.env` file in the directory where you start AxonX. The CLI loads this file automatically; existing environment variables take precedence. See [example.env](https://github.com/FlowLLM-AI/AxonX/blob/main/example.env) for optional provider settings.
|
|
39
|
+
|
|
40
|
+
If AxonX is already installed, add Studio separately:
|
|
41
|
+
|
|
42
|
+
```bash
|
|
43
|
+
pip install axonx-studio
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
Restart the service after installation. AxonX loads `dist/` through the package's `static_dir()` function and serves the UI at `/` when `service.web_enabled` is enabled.
|
|
47
|
+
|
|
48
|
+
### Run your first task
|
|
49
|
+
|
|
50
|
+
1. Keep the machine selector on **Local**, then open **Submit task**.
|
|
51
|
+
2. Choose the built-in `demo` Task under **Native tasks**.
|
|
52
|
+
3. Set `X` to `2`, `Y` to `3`, and leave `Fail` as `False`.
|
|
53
|
+
4. Click **Submit run**, then open **Task management** and select the run.
|
|
54
|
+
5. Inspect its status, steps, logs, configuration, and final output.
|
|
55
|
+
|
|
56
|
+
Leave **Task Name** empty to generate a name for each experiment. Reusing a fixed name replaces the directory of a finished run. Upstream relationships record lineage; the graph does not automatically execute dependent Tasks.
|
|
57
|
+
|
|
58
|
+
### Optional research and Agent setup
|
|
59
|
+
|
|
60
|
+
- **Research plugins:** install `axonx-alpha158` or `axonx-alpha158-enhanced` in the execution service's Python environment, then restart the service. Research views need completed runs with standard `metadata.json` and artifact outputs.
|
|
61
|
+
- **Tushare downloads:** configure `AXONX_TUSHARE_TOKEN` on the backend. Override `AXONX_TUSHARE_BASE_URL` only when using a compatible custom endpoint.
|
|
62
|
+
- **Agent:** configure the backend's `CLAUDE_CODE_API_KEY`, `CLAUDE_CODE_BASE_URL`, and `CLAUDE_CODE_MODEL_NAME` as needed for your provider. Ordinary Tasks can run without model credentials. Stopping an Agent turn does not cancel a Task it submitted.
|
|
63
|
+
- **Remote machines:** configure backend service `targets`, then select the target in Studio. The browser authenticates to the local service; the backend resolves remote addresses and credentials and forwards requests using `target`.
|
|
64
|
+
|
|
65
|
+
See [research setup](https://github.com/FlowLLM-AI/AxonX/blob/main/docs/en/research/workflow.md), [Agent configuration](https://github.com/FlowLLM-AI/AxonX/blob/main/docs/en/agent/configuration.md), and [remote machines](https://github.com/FlowLLM-AI/AxonX/blob/main/docs/en/guides/remote-machines.md).
|
|
66
|
+
|
|
67
|
+
## npm distribution and static hosting
|
|
68
|
+
|
|
69
|
+
The npm package distributes the built frontend assets:
|
|
16
70
|
|
|
17
71
|
```bash
|
|
18
72
|
npm install @flowllm-ai/axonx-studio
|
|
19
73
|
```
|
|
20
74
|
|
|
21
|
-
|
|
75
|
+
Serve `node_modules/@flowllm-ai/axonx-studio/dist/` with your static server. An AxonX backend is still required. The frontend uses origin-relative API URLs, so configure the same origin to proxy `/health`, `/jobs`, `/files`, `/mcp`, and `/proxy` to that backend. Preserve Authorization headers and SSE streaming for live logs and Agent responses. Hash routing does not require server routes for individual Studio pages.
|
|
76
|
+
|
|
77
|
+
For AxonX's built-in hosting, install the Python package instead.
|
|
22
78
|
|
|
23
|
-
##
|
|
79
|
+
## Develop from source
|
|
24
80
|
|
|
25
|
-
|
|
81
|
+
The frontend toolchain requires **Node.js 22.x ≥ 22.13.0, 24.x, or 26+**, as declared in `package.json`. Run the following from the repository root to install the backend and development dependencies:
|
|
26
82
|
|
|
27
83
|
```bash
|
|
28
84
|
pip install -e '.[dev]'
|
|
85
|
+
export AXONX_SERVICE_TOKEN='replace-with-your-local-service-token'
|
|
86
|
+
axonx start --service.host 127.0.0.1
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
In another terminal:
|
|
90
|
+
|
|
91
|
+
```bash
|
|
29
92
|
cd axonx_studio
|
|
30
|
-
npm ci
|
|
93
|
+
npm ci
|
|
94
|
+
npm run dev
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
Open <http://localhost:4173/> and configure the service token for this browser origin. Vite provides hot updates and proxies API requests to `http://127.0.0.1:1024` by default.
|
|
98
|
+
|
|
99
|
+
To use a different backend:
|
|
100
|
+
|
|
101
|
+
```bash
|
|
102
|
+
AXONX_DEV_SERVER=http://127.0.0.1:2048 npm run dev
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
Vite also reads `.env` files from the repository root. Restart Vite after changing `AXONX_DEV_SERVER`. This setting controls the development proxy; it does not configure the backend URL in a production build.
|
|
106
|
+
|
|
107
|
+
### Build and install local assets
|
|
108
|
+
|
|
109
|
+
```bash
|
|
110
|
+
# From axonx_studio/
|
|
111
|
+
npm run build
|
|
31
112
|
cd ..
|
|
32
113
|
pip install ./axonx_studio
|
|
33
114
|
```
|
|
34
115
|
|
|
35
|
-
|
|
116
|
+
`build` runs TypeScript checks and writes the static site to `dist/`. Restart AxonX to serve the installed package. After frontend changes, rebuild and reinstall to update the packaged assets.
|
|
117
|
+
|
|
118
|
+
| Command (in `axonx_studio/`) | Purpose |
|
|
119
|
+
| ---------------------------- | --------------------------------------------------------------------------------------------------- |
|
|
120
|
+
| `npm run dev` | Start the Vite development server on port 4173 with API proxies. |
|
|
121
|
+
| `npm run build` | Type-check and produce `dist/`. |
|
|
122
|
+
| `npm run preview` | Preview a production build locally; backend proxying is only configured for the development server. |
|
|
123
|
+
| `npm run test` | Run the Vitest suite. |
|
|
124
|
+
| `npm run lint` | Run ESLint. |
|
|
125
|
+
| `npm run format:check` | Check formatting with Prettier. |
|
|
126
|
+
| `npm run format` | Apply Prettier formatting. |
|
|
127
|
+
|
|
128
|
+
`npm pack` and `npm publish` run the `prepack` build automatically. Python packaging includes existing `dist/` assets; build them before creating a Python distribution.
|
|
129
|
+
|
|
130
|
+
## Code organization
|
|
131
|
+
|
|
132
|
+
| Path | Responsibility |
|
|
133
|
+
| ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
|
|
134
|
+
| `src/app/` | Hash routes, navigation, machine selection, shared application state, and lazy page loading. |
|
|
135
|
+
| `src/features/` | Tasks, runtime, machines, Agent, workspace, research, backtests, strategy comparison, and API pages. |
|
|
136
|
+
| `src/shared/api/` | Authenticated Job requests, response decoding, SSE parsing, and shared API types. |
|
|
137
|
+
| `src/shared/schema/` and `src/shared/ui/SchemaForm/` | JSON Schema field rendering and form value conversion. |
|
|
138
|
+
| `src/shared/hooks/` and `src/shared/lib/` | Async resources, polling, copy feedback, formatting, and error helpers. |
|
|
139
|
+
| `src/locales/` and `src/i18n.ts` | English/Chinese translations and language persistence. |
|
|
140
|
+
| `src/styles/` | Design tokens, layout, themes, and feature styles. |
|
|
141
|
+
| `src/webmcp.ts` | Optional browser tools for listing and submitting local Tasks when `document.modelContext` is available. |
|
|
142
|
+
| `public/`, `dist/` | Source static assets and generated build output. |
|
|
143
|
+
| `__init__.py`, `pyproject.toml`, `package.json` | Python asset lookup and Python/npm packaging. |
|
|
144
|
+
|
|
145
|
+
Use `axonx.invoke` or feature API wrappers for Job calls. Requests use `{ arguments, target }`; the client checks the Job response envelope and returns `answer`. Propagate the selected `target` and cancellation signals through feature APIs. Reuse the shared SSE parser for streaming calls.
|
|
146
|
+
|
|
147
|
+
To add a page, register its route in `src/app/routes.ts`, navigation in `navigation.ts`, and rendering in `PageOutlet.tsx`. Add user-facing strings to both locale files. See [Studio development](https://github.com/FlowLLM-AI/AxonX/blob/main/docs/en/development/studio.md) for extension guidance.
|
|
148
|
+
|
|
149
|
+
## Troubleshooting
|
|
150
|
+
|
|
151
|
+
| Symptom | Check |
|
|
152
|
+
| ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
153
|
+
| Backend runs but Studio is unavailable | Install `axonx-studio`, verify `dist/index.html` exists for source builds, enable `service.web_enabled`, and restart the service. |
|
|
154
|
+
| Page loads but APIs return 401 | Match the browser's service token to `AXONX_SERVICE_TOKEN`; separate browser origins have separate saved tokens. |
|
|
155
|
+
| Task or API catalog is empty | Configure the backend service token, verify the selected machine, and install its plugins. Auth-required Jobs are omitted when the service has no token. |
|
|
156
|
+
| Development API requests fail | Check that the backend is running and `AXONX_DEV_SERVER` is correct; restart Vite after changes. |
|
|
157
|
+
| Research results or curves are missing | Inspect task status/logs and `metadata.json`; check `output_params.artifacts`, `training_curve`, and backtest `daily`/`summary` files as applicable. |
|
|
158
|
+
| Remote requests fail | Check backend `targets`, remote service credentials, and connectivity from the local backend. |
|
|
159
|
+
| Static deployment loads but APIs or streams fail | Check same-origin API proxy paths, Authorization forwarding, and SSE buffering. |
|
|
160
|
+
|
|
161
|
+
Workspace preview uses paths relative to the execution workspace. The `/files` API handles staged uploads and cleanup; retrieve complete artifacts from the execution machine's workspace. Deleting runs or workspace entries removes their data and does not rebuild downstream results.
|
|
162
|
+
|
|
163
|
+
## Documentation and license
|
|
164
|
+
|
|
165
|
+
- [Studio getting started](https://github.com/FlowLLM-AI/AxonX/blob/main/docs/en/getting-started/studio.md)
|
|
166
|
+
- [Task management](https://github.com/FlowLLM-AI/AxonX/blob/main/docs/en/guides/task-management.md)
|
|
167
|
+
- [Research artifact contract](https://github.com/FlowLLM-AI/AxonX/blob/main/docs/en/reference/research-artifacts.md)
|
|
168
|
+
- [SSE event protocol](https://github.com/FlowLLM-AI/AxonX/blob/main/docs/en/api/events.md)
|
|
169
|
+
- [Contributing](https://github.com/FlowLLM-AI/AxonX/blob/main/CONTRIBUTING.md)
|
|
170
|
+
|
|
171
|
+
Released under the [Apache License 2.0](https://github.com/FlowLLM-AI/AxonX/blob/main/axonx_studio/LICENSE).
|