Skip to content

Commit ee6c7fc

Browse files
miyakomiyako
committed
documentation generated by AI
1 parent f552d4b commit ee6c7fc

9 files changed

Lines changed: 608 additions & 0 deletions

File tree

‎llama-cpp/Documentation/Classes/_CLI.md‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
# _CLI
2+
### Abstract base class for wrapping a platform-native CLI executable.
3+
4+
> _CLI.new (executableName : Text; controller : 4D.Class)
5+
6+
| Parameter | Type | | Description |
7+
| --- | --- | --- | --- |
8+
| executableName | Text | -> | Base name of the executable (without `.exe` on Windows) |
9+
| controller | 4D.Class | -> | Class reference for the controller (default: `cs.llama._CLI_Controller`) |
10+
11+
## Description
12+
13+
`_CLI` resolves the platform-specific path to a bundled executable and attaches a controller that manages the underlying `4D.SystemWorker`. It is extended by [`_llama`](_llama.md) and should not be instantiated directly.
14+
15+
### Resolution strategy
16+
17+
On startup the constructor checks for the executable under `/RESOURCES/bin/{platform}/`. If found it stores the full path and calls `chmod +x` on macOS. If not found it falls back to the executable name alone, relying on `$PATH`.
18+
19+
Platform identifiers:
20+
21+
| Platform | Value |
22+
| --- | --- |
23+
| macOS (Intel or Apple Silicon) | `macOS` |
24+
| Windows x64 | `Windows` |
25+
| Windows ARM | `WindowsARM` |
26+
27+
### Properties (read-only)
28+
29+
| Property | Type | Description |
30+
| --- | --- | --- |
31+
| name | Text | Class name |
32+
| EOL | Text | `\n` on macOS, `\r\n` on Windows |
33+
| executableName | Text | Resolved executable file name |
34+
| platform | Text | Platform string (see table above) |
35+
| currentDirectory | 4D.Folder | Folder containing the executable |
36+
| executablePath | Text | Full path (or bare name) of the executable |
37+
| executableFile | 4D.File | `4D.File` reference to the executable |
38+
| controller | cs.llama._CLI_Controller | Attached controller instance |
39+
40+
### Methods
41+
42+
#### escape (in : Text) → Text
43+
44+
Shell-escapes a string for the current platform.
45+
46+
| Parameter | Type | | Description |
47+
| --- | --- | --- | --- |
48+
| in | Text | -> | Raw string to escape |
49+
| Result | Text | <- | Shell-safe string |
50+
51+
On macOS/zsh the method prefixes each shell metacharacter with `\`. On Windows/cmd.exe it wraps the string in double quotes when any metacharacter (`& | < > ( ) % ^ " space`) is present.
52+
53+
#### expand (in : Object) → Object
54+
55+
Re-creates a `4D.File` or `4D.Folder` from its platform path, ensuring paths obtained on one platform are normalized correctly.
56+
57+
| Parameter | Type | | Description |
58+
| --- | --- | --- | --- |
59+
| in | Object | -> | A `4D.File` or `4D.Folder` |
60+
| Result | Object | <- | New object of the same class using the platform path |
61+
62+
#### quote (in : Text) → Text
63+
64+
Wraps a string in double quotes. Useful when building command strings that must always be quoted regardless of content.
65+
66+
| Parameter | Type | | Description |
67+
| --- | --- | --- | --- |
68+
| in | Text | -> | Input text |
69+
| Result | Text | <- | `"input"` |
70+
71+
## See also
72+
73+
- [`_CLI_Controller`](_CLI_Controller.md) — manages `4D.SystemWorker` execution
74+
- [`_llama`](_llama.md) — extends `_CLI` for llama.cpp programs

‎llama-cpp/Documentation/Classes/_CLI_Controller.md‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
# _CLI_Controller
2+
### Manages a queue of `4D.SystemWorker` commands for a `_CLI` instance.
3+
4+
> _CLI_Controller.new (CLI : cs.llama._CLI)
5+
6+
| Parameter | Type | | Description |
7+
| --- | --- | --- | --- |
8+
| CLI | cs.llama._CLI | -> | The owning `_CLI` instance |
9+
10+
## Description
11+
12+
`_CLI_Controller` serializes an ordered queue of shell commands, executing each one in its own `4D.SystemWorker` and advancing to the next only after the previous worker has terminated. It is attached to a `_CLI` instance and is not used directly by application code.
13+
14+
### Properties
15+
16+
| Property | Type | Description |
17+
| --- | --- | --- |
18+
| dataType | Text | Worker data type (`"text"` by default) |
19+
| encoding | Text | Text encoding (`"UTF-8"` by default) |
20+
| variables | Object | Environment variables injected into each worker |
21+
| timeout | Variant | Worker timeout (`Null` = no timeout) |
22+
| hideWindow | Boolean | Hide the console window on Windows (default: `True`) |
23+
| currentDirectory | 4D.Folder | Inherited from the owning `_CLI` |
24+
| SYSTEM_WORKER_CONTEXT | Object | Key-value store keyed by worker PID for per-command context |
25+
| complete | Boolean | `True` when the command queue has been fully drained |
26+
| worker | 4D.SystemWorker | The currently running worker (`Null` when idle) |
27+
| commands | Collection | Pending command strings |
28+
29+
### Event callbacks
30+
31+
The following properties may be set to `4D.Function` values before calling `execute`. If not set in a subclass, they default to the built-in `_onEvent` no-op handler.
32+
33+
| Property | Signature | Description |
34+
| --- | --- | --- |
35+
| onData | ($worker; $params) | Fired when the worker emits stdout data |
36+
| onDataError | ($worker; $params) | Fired when the worker emits stderr data |
37+
| onError | ($worker; $params) | Fired on worker error |
38+
| onResponse | ($worker; $params) | Fired when the worker responds (command finished) |
39+
| onTerminate | ($worker; $params) | Fired when the worker terminates |
40+
41+
### Methods
42+
43+
#### execute (command, message, context) → cs.llama._CLI_Controller
44+
45+
Enqueues one or more commands and starts execution if no worker is currently running.
46+
47+
| Parameter | Type | | Description |
48+
| --- | --- | --- | --- |
49+
| command | Text \| Collection | -> | Shell command string, or a collection of command strings |
50+
| message | Variant \| Collection | -> | Optional stdin payload(s) sent to the worker |
51+
| context | Variant \| Collection | -> | Optional per-command context object(s); retrievable via `SYSTEM_WORKER_CONTEXT` in callbacks |
52+
| Result | cs.llama._CLI_Controller | <- | `This` — enables chaining |
53+
54+
When `message` is an Object or Collection it is serialized to JSON before being posted. Blob and Text values are posted as-is. Scalar values are converted with `String()`.
55+
56+
#### terminate ()
57+
58+
Aborts the queue, clears all pending commands, terminates the active worker, and resets internal state.
59+
60+
## See also
61+
62+
- [`_CLI`](_CLI.md) — owns and instantiates the controller
63+
- [`_llama_Controller`](_llama_Controller.md) — extends `_CLI_Controller` with llama-specific termination handling

‎llama-cpp/Documentation/Classes/_Model.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# _Model
2+
### Extends `_models` to set the model file path and launch `llama-server` after download.
3+
4+
> _Model.new (port : Integer; huggingfaces : cs.event.huggingfaces; options : Object; formula : 4D.Function; event : cs.event.event)
5+
6+
| Parameter | Type | | Description |
7+
| --- | --- | --- | --- |
8+
| port | Integer | -> | Port to listen on |
9+
| huggingfaces | cs.event.huggingfaces | -> | Model download parameters |
10+
| options | Object | -> | Command-line options (mutated; `options.model` is set after first file downloads) |
11+
| formula | 4D.Function | -> | Internal response callback |
12+
| event | cs.event.event | -> | Callback functions |
13+
14+
## Description
15+
16+
`_Model` is the concrete implementation of [`_models`](_models.md). After calling `Super` it immediately triggers `download()` unless `offline` is `true`.
17+
18+
It overrides three methods from `_models`:
19+
20+
### _isRouterMode () → Boolean
21+
22+
Returns `true` when the options object indicates router mode — i.e. when `options.models_preset` is an existing `4D.File` or `options.models_dir` is an existing `4D.Folder`.
23+
24+
### models () → cs.event.models
25+
26+
Overrides the virtual base. In router mode it returns a single unnamed model entry. Otherwise it returns a `cs.event.models` collection containing one `cs.event.model` built from `options.model.name` and whether the file currently exists on disk.
27+
28+
### onDownload (oid : Text)
29+
30+
Overrides the virtual base. When the first file in the download queue finishes, it sets `options.model` to that file's local path (if not already set). Then calls `Super.onDownload` to remove the entry from `files` and trigger `start()` when all downloads are complete.
31+
32+
| Parameter | Type | | Description |
33+
| --- | --- | --- | --- |
34+
| oid | Text | -> | OID of the completed download |
35+
36+
### start ()
37+
38+
Overrides the virtual base. Creates a `cs.llama.workers.worker` wrapping `_server`, calls `worker.start(port, options)`, then fires `event.onSuccess` with the current port options and model list.
39+
40+
### Properties
41+
42+
In addition to properties inherited from `_models`:
43+
44+
| Property | Type | Description |
45+
| --- | --- | --- |
46+
| model | 4D.Folder | Set internally after first download resolves the model path |
47+
48+
## See also
49+
50+
- [`_models`](_models.md) — parent class
51+
- [`_server`](_server.md) — launched by `start()`
52+
- [`llama`](llama.md) — public entry point

‎llama-cpp/Documentation/Classes/_interface.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# _interface
2+
### Abstract base class providing shared server lifecycle methods for the llama namespace.
3+
4+
> _interface.new ()
5+
6+
`_interface` has no constructor parameters. It is not instantiated directly; it is extended by [`llama`](llama.md).
7+
8+
## Description
9+
10+
`_interface` is the root class of the `cs.llama` hierarchy. It provides two methods used by all subclasses:
11+
12+
- **`_onTCP`** — a callback invoked after a TCP port-availability check. If the port is free it dispatches a worker to start the server; if the port is already in use it fires `event.onError` with a descriptive message.
13+
- **`terminate`** — gracefully shuts down the running `llama-server` worker.
14+
15+
### _onTCP ($status, $options)
16+
17+
| Parameter | Type | | Description |
18+
| --- | --- | --- | --- |
19+
| $status | Object | -> | Result of the TCP port check (`success`, `port`, `PID`) |
20+
| $options | Object | -> | Server options including `name`, `port`, `event` |
21+
22+
Called internally after a port probe. When `$status.success` is `true` the method calls `CALL WORKER` to invoke `start` on the server worker, then registers `onModel` as the response callback. When the port is occupied it constructs a `cs.event.error` and calls `event.onError`.
23+
24+
### terminate ()
25+
26+
Obtains the server worker via `cs.llama.workers.worker` and calls `terminate()` on it. Use this from any context where you hold a reference to the `llama` instance.
27+
28+
## Examples
29+
30+
```4d
31+
// Terminate from anywhere — llama.new() with no arguments returns
32+
// a lightweight handle without starting a new server
33+
var $llama : cs.llama.llama
34+
$llama:=cs.llama.llama.new()
35+
$llama.terminate()
36+
```
37+
38+
## See also
39+
40+
- [`llama`](llama.md) — public subclass that extends `_interface`
41+
- [`_server`](_server.md) — CLI wrapper whose worker is targeted by `terminate()`

‎llama-cpp/Documentation/Classes/_llama.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
# _llama
2+
### Extends `_CLI` to target a specific llama.cpp executable.
3+
4+
> _llama.new (command : Text; class : 4D.Class)
5+
6+
| Parameter | Type | | Description |
7+
| --- | --- | --- | --- |
8+
| command | Text | -> | Logical command name; maps to an executable (see table below) |
9+
| class | 4D.Class | -> | Optional custom controller class (must extend `_llama_Controller`) |
10+
11+
## Description
12+
13+
`_llama` extends [`_CLI`](_CLI.md) and resolves the `command` argument to the appropriate llama.cpp binary name before passing it to the parent constructor. It also walks the inheritance chain of the supplied `class` to decide whether to use it as a custom controller or fall back to the default `_llama_Controller`.
14+
15+
### Command mapping
16+
17+
| command value | Executable |
18+
| --- | --- |
19+
| `"embedding"` | `llama-embedding` |
20+
| `"gguf"` | `llama-gguf` |
21+
| `"quantize"` | `llama-quantize` |
22+
| `"cli"` | `llama-cli` |
23+
| `"tokenize"` | `llama-tokenize` |
24+
| _(any other value)_ | `llama-server` |
25+
26+
### Properties
27+
28+
In addition to properties inherited from `_CLI`:
29+
30+
| Property | Type | Description |
31+
| --- | --- | --- |
32+
| port | Integer | Port the server is listening on |
33+
| onData | 4D.Function | Forwarded to the controller's `onData` handler |
34+
| onDataError | 4D.Function | Forwarded to the controller's `onDataError` handler |
35+
| onTerminate | 4D.Function | Called by `_llama_Controller` when the worker terminates |
36+
37+
### Methods
38+
39+
#### bind (option : Object; properties : Collection) → cs.llama._CLI
40+
41+
Copies listed property names from `option` into `This`, used to bind event callbacks from an options object before execution.
42+
43+
| Parameter | Type | | Description |
44+
| --- | --- | --- | --- |
45+
| option | Object | -> | Source object |
46+
| properties | Collection | -> | Property names to copy |
47+
| Result | cs.llama._CLI | <- | `This` |
48+
49+
#### get worker () → 4D.SystemWorker
50+
51+
Returns the active `4D.SystemWorker` from the attached controller.
52+
53+
#### terminate ()
54+
55+
Delegates to `controller.terminate()`, stopping the active worker and draining the command queue.
56+
57+
## See also
58+
59+
- [`_CLI`](_CLI.md) — parent class
60+
- [`_llama_Controller`](_llama_Controller.md) — default controller
61+
- [`_server`](_server.md) — extends `_llama` for `llama-server`

‎llama-cpp/Documentation/Classes/_llama_Controller.md‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
# _llama_Controller
2+
### Extends `_CLI_Controller` with llama-specific worker termination handling.
3+
4+
> _llama_Controller.new (CLI : cs.llama._CLI)
5+
6+
| Parameter | Type | | Description |
7+
| --- | --- | --- | --- |
8+
| CLI | cs.llama._CLI | -> | The owning `_CLI` (typically a `_server` instance) |
9+
10+
## Description
11+
12+
`_llama_Controller` is the default controller used by all `_llama` subclasses. It inherits all queueing and execution behaviour from [`_CLI_Controller`](_CLI_Controller.md) and overrides only `onTerminate` to forward the termination event back to the owning `_llama` instance's `onTerminate` callback.
13+
14+
This allows application code to attach a single `onTerminate` function on the `_server` (or `llama`) instance and have it called automatically when the `llama-server` process exits.
15+
16+
### Overridden event callbacks
17+
18+
The following callbacks are declared (but intentionally left as no-ops) and may be overridden in a subclass:
19+
20+
| Property | Description |
21+
| --- | --- |
22+
| onData | stdout data event |
23+
| onDataError | stderr data event |
24+
| onResponse | response / command-complete event |
25+
| onError | worker error event |
26+
27+
#### onTerminate ($worker : 4D.SystemWorker; $params : Object)
28+
29+
Called when the managed `SystemWorker` terminates. Looks up `onTerminate` on the owning `_server` instance and calls it if present.
30+
31+
| Parameter | Type | | Description |
32+
| --- | --- | --- | --- |
33+
| $worker | 4D.SystemWorker | -> | The worker that terminated |
34+
| $params | Object | -> | Termination parameters from the system worker |
35+
36+
## Examples
37+
38+
### Custom controller subclass
39+
40+
To handle stdout while the server is running, create a subclass of `_llama_Controller` and override `onData`:
41+
42+
```4d
43+
// In your custom controller class (e.g. cs.llama.MyController):
44+
Class extends cs.llama._llama_Controller
45+
46+
Function onData($worker : 4D.SystemWorker; $params : Object)
47+
LOG EVENT(Into 4D debug message; $params.data)
48+
```
49+
50+
Then pass it when constructing the server:
51+
52+
```4d
53+
$llama:=cs.llama.llama.new($port; $huggingfaces; $homeFolder; $options; $event)
54+
// _llama automatically detects MyController extends _llama_Controller
55+
// and uses it in place of the default
56+
```
57+
58+
## See also
59+
60+
- [`_CLI_Controller`](_CLI_Controller.md) — parent class
61+
- [`_llama`](_llama.md) — attaches this controller by default
62+
- [`_server`](_server.md) — the `_llama` subclass whose `onTerminate` is forwarded here

0 commit comments

Comments
 (0)