1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
// This is free and unencumbered software released into the public domain.
//! Role-specific execution traits and command-line configuration values.
//!
//! Each trait is a marker extending [`Execute`](crate::Execute). It identifies
//! the intended operation but adds no constructor, input parameter, or runtime
//! validation. `T` is the result type; the implementation chooses the associated
//! [`Error`](crate::Execute::Error) type. Bounds can constrain it with, for example,
//! `Fetcher<T, Error = E>`. [`Indexer`] has no type parameters and uses `()` for
//! its result; its error can likewise be constrained with `Indexer<Error = E>`.
//!
//! # Pattern catalog
//!
//! | Trait | Logical input | Logical output | Options |
//! | --- | --- | --- | --- |
//! | [`Adapter`] | SPARQL query | RDF query result | [`AdapterOptions`] |
//! | [`Compiler`] | Natural-language text | SPARQL query | [`CompilerOptions`] |
//! | [`Emitter`] | None | Generated RDF | [`EmitterOptions`] |
//! | [`Fetcher`] | One URL | RDF describing the resource | [`FetcherOptions`] |
//! | [`Indexer`] | RDF | None; updates a persistent index | [`IndexerOptions`] |
//! | [`Lister`] | One collection URL | RDF describing zero or more entries | [`ListerOptions`] |
//! | [`Matcher`] | RDF | RDF describing matches | [`MatcherOptions`] |
//! | [`Prompter`] | Prompt text | Response text | [`PrompterOptions`] |
//! | [`Reader`] | Document or byte stream | Imported RDF | [`ReaderOptions`] |
//! | [`Reasoner`] | RDF | Entailed RDF | [`ReasonerOptions`] |
//! | [`Resolver`] | One URI | Zero or more URLs | [`ResolverOptions`] |
//! | [`Runner`] | Program text | Execution result as text | [`RunnerOptions`] |
//! | [`Writer`] | RDF | Exported document or byte stream | [`WriterOptions`] |
//!
//! All thirteen patterns in the [specification][pps] have corresponding traits
//! here and process wrappers in `asimov-runner`. RDF in this table denotes
//! graphs or datasets, not individual statements, records, or buffers.
//!
//! # Results and streaming
//!
//! These traits prescribe semantic roles, not buffering, stream types, or
//! process management. A streaming implementation must distinguish successful
//! startup from eventual completion and expose later errors through its result.
//! Receiving output alone does not establish success; see [`Execute`](crate::Execute).
//!
//! Concrete behavior is documented in [`asimov-runner`][runner]: consult its
//! [execution and results][results] section for result types, input ownership,
//! output routing, and cancellation; [completion outcomes][completion] for error
//! precedence; and [JSONL transport][jsonl] for graph framing, batching, and composition.
//! The runner's [linear pipelines][pipelines] connect compatible process-backed
//! programs and coordinate their completion independently of these marker traits.
//!
//! # Native capabilities
//!
//! [`ListerCapabilities`] describes optional native sorting, numeric offset,
//! URI cursor (`before`/`after`), and limit support separately from the requests
//! in [`ListerOptions`]. Each capability uses
//! [`OptionSupport`](crate::OptionSupport): unknown, supported, or unsupported.
//! Callers can translate manifest metadata into these values without this crate
//! depending on a manifest schema. Capabilities do not imply host emulation;
//! forwarding and fallback policies are documented by the concrete executor.
//!
//! # Options and defaults
//!
//! Every options type supports `Default`, direct field access, and a
//! `builder()`. Defaults leave optional fields unset and collections empty;
//! builders accept values convertible to `String` for string fields. Values
//! are stored without checking whether the selected program supports them.
//!
//! The companion [`asimov-runner`][runner] wrappers emit configured fields as
//! individual `--name=value` arguments according to supplied capabilities. Hosts
//! may enforce a limit instead of forwarding an unsupported flag, and may also
//! enforce it independently to protect against program bugs. `None` omits an
//! option rather than supplying an empty value. Programs apply these defaults:
//!
//! | Patterns | Input format | Output format | Other defaults |
//! | --- | --- | --- | --- |
//! | Adapter, emitter, fetcher | No input-format option | `jsonl` | — |
//! | Compiler | No input-format option | No output-format option | No pattern-specific options |
//! | Indexer | `jsonl` | No output-format option | Index destination required |
//! | Lister | No input-format option | `jsonl` | No limit or cursor bounds; offset `0`; program-defined order |
//! | Matcher, reasoner | `jsonl` | `jsonl` | — |
//! | Prompter | `text` | `text` | Model `auto` |
//! | Reader | `auto` | `jsonl` | — |
//! | Resolver | No input-format option | No output-format option | No limit |
//! | Runner | No input-format option | No output-format option | No definitions |
//! | Writer | `jsonl` | `auto` | — |
//!
//! `text` means UTF-8 without a standardized chat envelope. `auto` delegates
//! format detection or selection to the program. `jsonl` needs a documented
//! [RDF mapping profile][rdf-mapping] shared by producer and consumer. Setting
//! a format option does not encode, decode, or convert any bytes in this crate.
//!
//! # Additional arguments and files
//!
//! Each `other` vector is an ordered argument list, not a shell command. The
//! runner appends its entries after generated options and before a dedicated
//! URL or URI operand. Each entry is passed verbatim as one argument: use two
//! entries for `--name value`, or one for `--name=value`. Do not add shell quotes
//! or redirection syntax. Repeated builder `other(...)` calls append; the
//! `maybe_other(...)` helpers append only `Some` values.
//!
//! Additional arguments can supply documented extensions or positional files.
//! Keep options before operands; use `--` to end option parsing when a filename
//! begins with `-`. Avoid repeating singleton options already set in fields:
//! precedence is program-defined, so `other` is not an override mechanism.
//!
//! **Format selection and file selection are separate.** For patterns with
//! optional input/output files, no operands select stdin/stdout, one operand
//! selects the input file, and two select input then output. To read stdin and
//! write a file, supply `-` followed by the output path. An indexer instead
//! requires its final operand to name the persistent index. See each trait's
//! synopsis for the applicable operand rules.
//!
//! A named input file replaces stdin as the payload source, and a named output
//! file replaces stdout as the destination. Consult the concrete invocation API
//! for file selection and stream-routing behavior; see the [runner's file operands][files].
//!
//! [pps]: https://asimov-specs.github.io/program-patterns/#patterns
//! [runner]: https://docs.rs/asimov-runner/latest/asimov_runner/programs/
//! [results]: https://docs.rs/asimov-runner/latest/asimov_runner/programs/#execution-and-results
//! [completion]: https://docs.rs/asimov-runner/latest/asimov_runner/struct.ExecutionCompletion.html
//! [jsonl]: https://docs.rs/asimov-runner/latest/asimov_runner/jsonl/
//! [pipelines]: https://docs.rs/asimov-runner/latest/asimov_runner/pipeline/
//! [files]: https://docs.rs/asimov-runner/latest/asimov_runner/programs/#file-operands
//! [rdf-mapping]: https://asimov-specs.github.io/program-patterns/#rdf-mapping
pub use *;
pub use *;
pub use *;
pub use *;
pub use *;
pub use *;
pub use *;
pub use *;
pub use *;
pub use *;
pub use *;
pub use *;
pub use *;