nace-cli 0.4.1__tar.gz → 0.5.1__tar.gz
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.
- {nace_cli-0.4.1 → nace_cli-0.5.1}/PKG-INFO +18 -7
- {nace_cli-0.4.1 → nace_cli-0.5.1}/README.md +16 -5
- {nace_cli-0.4.1 → nace_cli-0.5.1}/pyproject.toml +2 -2
- {nace_cli-0.4.1 → nace_cli-0.5.1}/pyproject.toml.orig +2 -2
- {nace_cli-0.4.1 → nace_cli-0.5.1}/src/nace_cli/__init__.py +1 -1
- {nace_cli-0.4.1 → nace_cli-0.5.1}/src/nace_cli/_cli.py +41 -4
- {nace_cli-0.4.1 → nace_cli-0.5.1}/src/nace_cli/_decide.py +1 -1
- {nace_cli-0.4.1 → nace_cli-0.5.1}/src/nace_cli/_docops.py +7 -2
- nace_cli-0.5.1/src/nace_cli/_metadata.py +239 -0
- nace_cli-0.5.1/src/nace_cli/_navigate.py +465 -0
- {nace_cli-0.4.1 → nace_cli-0.5.1}/src/nace_cli/_search.py +2 -2
- nace_cli-0.5.1/src/nace_cli/_skill.py +141 -0
- {nace_cli-0.4.1 → nace_cli-0.5.1}/src/nace_cli/_workspaces.py +43 -21
- nace_cli-0.5.1/src/nace_cli/skills/drex-search/SKILL.md +161 -0
- nace_cli-0.5.1/src/nace_cli/skills/drex-workspace/SKILL.md +38 -0
- {nace_cli-0.4.1 → nace_cli-0.5.1}/LICENSE +0 -0
- {nace_cli-0.4.1 → nace_cli-0.5.1}/src/nace_cli/_browser.py +0 -0
- {nace_cli-0.4.1 → nace_cli-0.5.1}/src/nace_cli/_domains.py +0 -0
- {nace_cli-0.4.1 → nace_cli-0.5.1}/src/nace_cli/_entrypoint.py +0 -0
- {nace_cli-0.4.1 → nace_cli-0.5.1}/src/nace_cli/_inputs.py +0 -0
- {nace_cli-0.4.1 → nace_cli-0.5.1}/src/nace_cli/_jobs.py +0 -0
- {nace_cli-0.4.1 → nace_cli-0.5.1}/src/nace_cli/_login.py +0 -0
- {nace_cli-0.4.1 → nace_cli-0.5.1}/src/nace_cli/_output.py +0 -0
- {nace_cli-0.4.1 → nace_cli-0.5.1}/src/nace_cli/_schemas.py +0 -0
- {nace_cli-0.4.1 → nace_cli-0.5.1}/src/nace_cli/_storage.py +0 -0
- {nace_cli-0.4.1 → nace_cli-0.5.1}/src/nace_cli/_upload.py +0 -0
- {nace_cli-0.4.1 → nace_cli-0.5.1}/src/nace_cli/py.typed +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: nace-cli
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.5.1
|
|
4
4
|
Summary: Nace CLI: calibrated decisions and document jobs from the shell
|
|
5
5
|
Keywords: drex,nace,cli,document-intelligence
|
|
6
6
|
Author: Nace AI
|
|
@@ -16,7 +16,7 @@ Classifier: Programming Language :: Python :: 3.12
|
|
|
16
16
|
Classifier: Programming Language :: Python :: 3.13
|
|
17
17
|
Classifier: Programming Language :: Python :: 3.14
|
|
18
18
|
Classifier: Typing :: Typed
|
|
19
|
-
Requires-Dist: nace-sdk>=0.
|
|
19
|
+
Requires-Dist: nace-sdk>=0.8.0,<1
|
|
20
20
|
Requires-Dist: truststore>=0.10.4,<1
|
|
21
21
|
Requires-Python: >=3.11
|
|
22
22
|
Project-URL: Homepage, https://console.nace.ai
|
|
@@ -25,7 +25,7 @@ Description-Content-Type: text/markdown
|
|
|
25
25
|
|
|
26
26
|
# nace-cli
|
|
27
27
|
|
|
28
|
-
`nace` — the
|
|
28
|
+
`nace` — the Drex API from the shell: calibrated decisions and document jobs. Docs: https://console.nace.ai/docs
|
|
29
29
|
|
|
30
30
|
```bash
|
|
31
31
|
pipx install nace-cli # or: uv tool install nace-cli
|
|
@@ -71,7 +71,7 @@ A `SOURCE` is one of:
|
|
|
71
71
|
- `ws:<workspace_id>/<file_id>`, what `nace upload` prints;
|
|
72
72
|
- `job:<parse job id>` to reuse a finished parse (not for `classify`, `-p`, `--mode medium|high` or `--password`).
|
|
73
73
|
|
|
74
|
-
`-p/--pages` and `--mode` apply to parse, split, classify and extract. `--semantic`
|
|
74
|
+
`-p/--pages` and `--mode` apply to parse, split, classify and extract. `--semantic` asks Ground to match each target by meaning: the text describes what to find. On deployments that ground PDF, Word and PowerPoint sources with the exact-match runtime, the answering sentences, table cells, lines, blocks, sections or table rows come back. Any other request field goes in `--option key=value` (dotted keys nest, JSON values parse) or `--options request.json`; flags win over both, and the source always comes from `SOURCE`.
|
|
75
75
|
|
|
76
76
|
Each command waits for the job and prints Markdown for a parse, the result JSON otherwise. For a document too large to return inline, `nace parse` fetches the full Markdown instead of the preview; when it can't, it prints the preview, names the `nace file` command that fetches the rest, and exits `1`. `-o json` prints the whole job, `-o result` only the result, `-o id` the job id; `--save PATH` writes it to a file. `--async` prints the job id and returns at once; `--watch` streams progress to stderr; `--wait-seconds N` asks Drex to hold the create up to 60 s; `--wait-timeout` bounds the client-side wait (default 600 s).
|
|
77
77
|
|
|
@@ -124,7 +124,18 @@ nace search "What were total liabilities at year end?"
|
|
|
124
124
|
nace qa "What was total freight spend in FY2024?" # stderr: session <id>; follow up with --session
|
|
125
125
|
```
|
|
126
126
|
|
|
127
|
-
|
|
127
|
+
A code agent can also search the workspace itself with the navigate tools, following the `drex-search` skill:
|
|
128
|
+
|
|
129
|
+
```bash
|
|
130
|
+
nace skill install --agent claude-code # drex-search and drex-workspace; also codex, cursor, pi, hermes
|
|
131
|
+
nace locate "total liabilities at year end" # the pages and tables that hold it, each with the read-file call that opens it
|
|
132
|
+
nace read-file reports/2025/report.pdf --pages 41
|
|
133
|
+
nace run-sql "SELECT ..." # table names come from locate
|
|
134
|
+
nace folder-metadata reports # file counts, categories and subfolders, without reading the files
|
|
135
|
+
nace catalog # the fields ingestion extracted per document; pass a SELECT to query them
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
`search` and `qa` print the answer, `evidences (N):` with each evidence as `1. path, page N` and its quote indented under it, then the Ground jobs to poll, the tables the answer refers to and any catalog rows; the route goes to stderr. Lists (`jobs`, `workspaces`, `workspace-files`) print a `<what> (N):` header, an indented line per item and `next: <cursor>` when more pages follow. Uploads go to a workspace only with `--workspace`; without it, to the server. `nace workspace-delete` takes the workspace only from `--workspace`.
|
|
128
139
|
|
|
129
140
|
## Domains
|
|
130
141
|
|
|
@@ -144,9 +155,9 @@ nace workspace-create fy25-leases --domain leases # a published domain's slug;
|
|
|
144
155
|
|
|
145
156
|
Stdout carries the payload and stderr the status, so `nace parse doc.pdf > doc.md` captures only the document. A wait that runs out prints the job id on stdout. Exit `0` on success, `1` on an API or job failure (including an ingestion that failed a file, from `nace ingest`, `nace upload --ingest` or `nace job`) (the message names the error type, code, request id and up to five fields that failed validation), `2` on a usage or configuration error.
|
|
146
157
|
|
|
147
|
-
Requests are retried up to twice on a `408`, `429`, `5xx`, dropped connection or timeout,
|
|
158
|
+
Requests are retried up to twice on a `408`, `429`, `5xx`, dropped connection or timeout, with no total retry budget, so a request that failed after a long wait, such as one that hit `--timeout` (120 s) or a slow `529`, is retried too and the command can take several minutes. `schema-create`, `schema-version-add`, `workspace-create`, `domains create`, `domains publish` and `domains duplicate` are never retried.
|
|
148
159
|
|
|
149
|
-
Full guide: https://console.nace.ai/docs/developer-tools/cli (install, sign-in, `decide`, documents, uploads, jobs, schemas, workspaces, search, exit codes).
|
|
160
|
+
Full guide: https://console.nace.ai/docs/developer-tools/cli (install, sign-in, `decide`, documents, uploads, jobs, schemas, workspaces, search, navigate tools, agent skills, exit codes).
|
|
150
161
|
|
|
151
162
|
## License
|
|
152
163
|
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# nace-cli
|
|
2
2
|
|
|
3
|
-
`nace` — the
|
|
3
|
+
`nace` — the Drex API from the shell: calibrated decisions and document jobs. Docs: https://console.nace.ai/docs
|
|
4
4
|
|
|
5
5
|
```bash
|
|
6
6
|
pipx install nace-cli # or: uv tool install nace-cli
|
|
@@ -46,7 +46,7 @@ A `SOURCE` is one of:
|
|
|
46
46
|
- `ws:<workspace_id>/<file_id>`, what `nace upload` prints;
|
|
47
47
|
- `job:<parse job id>` to reuse a finished parse (not for `classify`, `-p`, `--mode medium|high` or `--password`).
|
|
48
48
|
|
|
49
|
-
`-p/--pages` and `--mode` apply to parse, split, classify and extract. `--semantic`
|
|
49
|
+
`-p/--pages` and `--mode` apply to parse, split, classify and extract. `--semantic` asks Ground to match each target by meaning: the text describes what to find. On deployments that ground PDF, Word and PowerPoint sources with the exact-match runtime, the answering sentences, table cells, lines, blocks, sections or table rows come back. Any other request field goes in `--option key=value` (dotted keys nest, JSON values parse) or `--options request.json`; flags win over both, and the source always comes from `SOURCE`.
|
|
50
50
|
|
|
51
51
|
Each command waits for the job and prints Markdown for a parse, the result JSON otherwise. For a document too large to return inline, `nace parse` fetches the full Markdown instead of the preview; when it can't, it prints the preview, names the `nace file` command that fetches the rest, and exits `1`. `-o json` prints the whole job, `-o result` only the result, `-o id` the job id; `--save PATH` writes it to a file. `--async` prints the job id and returns at once; `--watch` streams progress to stderr; `--wait-seconds N` asks Drex to hold the create up to 60 s; `--wait-timeout` bounds the client-side wait (default 600 s).
|
|
52
52
|
|
|
@@ -99,7 +99,18 @@ nace search "What were total liabilities at year end?"
|
|
|
99
99
|
nace qa "What was total freight spend in FY2024?" # stderr: session <id>; follow up with --session
|
|
100
100
|
```
|
|
101
101
|
|
|
102
|
-
|
|
102
|
+
A code agent can also search the workspace itself with the navigate tools, following the `drex-search` skill:
|
|
103
|
+
|
|
104
|
+
```bash
|
|
105
|
+
nace skill install --agent claude-code # drex-search and drex-workspace; also codex, cursor, pi, hermes
|
|
106
|
+
nace locate "total liabilities at year end" # the pages and tables that hold it, each with the read-file call that opens it
|
|
107
|
+
nace read-file reports/2025/report.pdf --pages 41
|
|
108
|
+
nace run-sql "SELECT ..." # table names come from locate
|
|
109
|
+
nace folder-metadata reports # file counts, categories and subfolders, without reading the files
|
|
110
|
+
nace catalog # the fields ingestion extracted per document; pass a SELECT to query them
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
`search` and `qa` print the answer, `evidences (N):` with each evidence as `1. path, page N` and its quote indented under it, then the Ground jobs to poll, the tables the answer refers to and any catalog rows; the route goes to stderr. Lists (`jobs`, `workspaces`, `workspace-files`) print a `<what> (N):` header, an indented line per item and `next: <cursor>` when more pages follow. Uploads go to a workspace only with `--workspace`; without it, to the server. `nace workspace-delete` takes the workspace only from `--workspace`.
|
|
103
114
|
|
|
104
115
|
## Domains
|
|
105
116
|
|
|
@@ -119,9 +130,9 @@ nace workspace-create fy25-leases --domain leases # a published domain's slug;
|
|
|
119
130
|
|
|
120
131
|
Stdout carries the payload and stderr the status, so `nace parse doc.pdf > doc.md` captures only the document. A wait that runs out prints the job id on stdout. Exit `0` on success, `1` on an API or job failure (including an ingestion that failed a file, from `nace ingest`, `nace upload --ingest` or `nace job`) (the message names the error type, code, request id and up to five fields that failed validation), `2` on a usage or configuration error.
|
|
121
132
|
|
|
122
|
-
Requests are retried up to twice on a `408`, `429`, `5xx`, dropped connection or timeout,
|
|
133
|
+
Requests are retried up to twice on a `408`, `429`, `5xx`, dropped connection or timeout, with no total retry budget, so a request that failed after a long wait, such as one that hit `--timeout` (120 s) or a slow `529`, is retried too and the command can take several minutes. `schema-create`, `schema-version-add`, `workspace-create`, `domains create`, `domains publish` and `domains duplicate` are never retried.
|
|
123
134
|
|
|
124
|
-
Full guide: https://console.nace.ai/docs/developer-tools/cli (install, sign-in, `decide`, documents, uploads, jobs, schemas, workspaces, search, exit codes).
|
|
135
|
+
Full guide: https://console.nace.ai/docs/developer-tools/cli (install, sign-in, `decide`, documents, uploads, jobs, schemas, workspaces, search, navigate tools, agent skills, exit codes).
|
|
125
136
|
|
|
126
137
|
## License
|
|
127
138
|
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
[project]
|
|
2
2
|
name = "nace-cli"
|
|
3
|
-
version = "0.
|
|
3
|
+
version = "0.5.1"
|
|
4
4
|
description = "Nace CLI: calibrated decisions and document jobs from the shell"
|
|
5
5
|
readme = "README.md"
|
|
6
6
|
license = "MIT"
|
|
@@ -24,7 +24,7 @@ classifiers = [
|
|
|
24
24
|
"Typing :: Typed",
|
|
25
25
|
]
|
|
26
26
|
dependencies = [
|
|
27
|
-
"nace-sdk>=0.
|
|
27
|
+
"nace-sdk>=0.8.0,<1",
|
|
28
28
|
"truststore>=0.10.4,<1",
|
|
29
29
|
]
|
|
30
30
|
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
[project]
|
|
2
2
|
name = "nace-cli"
|
|
3
|
-
version = "0.
|
|
3
|
+
version = "0.5.1"
|
|
4
4
|
description = "Nace CLI: calibrated decisions and document jobs from the shell"
|
|
5
5
|
authors = [
|
|
6
6
|
{ name = "Nace AI", email = "engineering@nace.ai" }
|
|
@@ -27,7 +27,7 @@ classifiers = [
|
|
|
27
27
|
"Typing :: Typed",
|
|
28
28
|
]
|
|
29
29
|
dependencies = [
|
|
30
|
-
"nace-sdk>=0.
|
|
30
|
+
"nace-sdk>=0.8.0,<1",
|
|
31
31
|
"truststore>=0.10.4,<1",
|
|
32
32
|
]
|
|
33
33
|
|
|
@@ -16,7 +16,23 @@ from nace_sdk import NaceAPIConnectionError, NaceAPIError, NaceClient, NaceError
|
|
|
16
16
|
from nace_sdk.constants import LOG_LEVEL_ENV, read_env
|
|
17
17
|
from nace_sdk.credentials import CredentialsError, resolve_credentials
|
|
18
18
|
|
|
19
|
-
from nace_cli import
|
|
19
|
+
from nace_cli import (
|
|
20
|
+
__version__,
|
|
21
|
+
_browser,
|
|
22
|
+
_decide,
|
|
23
|
+
_docops,
|
|
24
|
+
_domains,
|
|
25
|
+
_jobs,
|
|
26
|
+
_login,
|
|
27
|
+
_metadata,
|
|
28
|
+
_navigate,
|
|
29
|
+
_schemas,
|
|
30
|
+
_search,
|
|
31
|
+
_skill,
|
|
32
|
+
_storage,
|
|
33
|
+
_upload,
|
|
34
|
+
_workspaces,
|
|
35
|
+
)
|
|
20
36
|
from nace_cli._inputs import check_one_stdin_flag
|
|
21
37
|
from nace_cli._output import CommandFailed
|
|
22
38
|
|
|
@@ -24,6 +40,11 @@ from nace_cli._output import CommandFailed
|
|
|
24
40
|
#: create that waits server-side; job waits have their own budget (--wait-timeout).
|
|
25
41
|
DEFAULT_TIMEOUT_SECONDS = 120.0
|
|
26
42
|
_ISSUE_LIMIT = 5
|
|
43
|
+
#: After a missing or unreadable key: an agent running `nace` can't sign in itself, and an MCP server's key isn't its shell's.
|
|
44
|
+
SIGN_IN_HINT = (
|
|
45
|
+
"An agent can't sign in for the user: ask them to run `nace login` in a terminal. It saves the key in the config "
|
|
46
|
+
"file the nace CLI and the nace-mcp server both read; a NACE_API_KEY set in an MCP server's config doesn't reach this shell."
|
|
47
|
+
)
|
|
27
48
|
|
|
28
49
|
|
|
29
50
|
class _StderrHandler(logging.Handler):
|
|
@@ -50,8 +71,18 @@ def main(argv: list[str] | None = None) -> int:
|
|
|
50
71
|
check_one_stdin_flag(args)
|
|
51
72
|
if args.family == "standalone":
|
|
52
73
|
return args.run(args)
|
|
53
|
-
|
|
54
|
-
|
|
74
|
+
try:
|
|
75
|
+
credentials = resolve_credentials()
|
|
76
|
+
except CredentialsError as exc:
|
|
77
|
+
print(f"error: {exc}", file=sys.stderr)
|
|
78
|
+
print(f" {SIGN_IN_HINT}", file=sys.stderr)
|
|
79
|
+
return 2
|
|
80
|
+
with NaceClient(
|
|
81
|
+
api_key=credentials.api_key,
|
|
82
|
+
base_url=credentials.base_url,
|
|
83
|
+
timeout=args.timeout,
|
|
84
|
+
client_info=f"nace-cli/{__version__}",
|
|
85
|
+
) as client:
|
|
55
86
|
return args.run(client, args)
|
|
56
87
|
except CredentialsError as exc:
|
|
57
88
|
print(f"error: {exc}", file=sys.stderr)
|
|
@@ -107,7 +138,10 @@ def _validation_lines(exc: NaceAPIError) -> list[dict[str, Any]]:
|
|
|
107
138
|
_WORKSPACE_HINTS = {
|
|
108
139
|
"workspace_not_found": "`nace workspaces` lists the workspaces your key can use; `nace workspace-use ID` saves one.",
|
|
109
140
|
"session_busy": "The conversation's last turn is still running: wait for it with `nace job <id> --wait`, then ask again.",
|
|
110
|
-
"rate_limited":
|
|
141
|
+
"rate_limited": (
|
|
142
|
+
"Automatic searches and QA turns share a limit of 60 per account every 10 minutes; locates have 150, and file reads "
|
|
143
|
+
"and SQL queries share 600."
|
|
144
|
+
),
|
|
111
145
|
"access_denied": "Your key can use the workspace but not do this: ask an account owner or admin, or whoever created the workspace.",
|
|
112
146
|
"storage_connection_unavailable": (
|
|
113
147
|
"`nace storage list` lists your account's connections. A deployment without customer storage answers this to every call."
|
|
@@ -183,7 +217,10 @@ def build_parser() -> argparse.ArgumentParser:
|
|
|
183
217
|
_domains.add_parsers(sub, common)
|
|
184
218
|
_storage.add_parsers(sub, common)
|
|
185
219
|
_search.add_parsers(sub, common)
|
|
220
|
+
_navigate.add_parsers(sub, common)
|
|
221
|
+
_metadata.add_parsers(sub, common)
|
|
186
222
|
_browser.add_parsers(sub, common)
|
|
223
|
+
_skill.add_parsers(sub)
|
|
187
224
|
return parser
|
|
188
225
|
|
|
189
226
|
|
|
@@ -15,7 +15,7 @@ from nace_cli._docops import parse_ws_source, upload_file, workspace_source
|
|
|
15
15
|
from nace_cli._inputs import read_json, read_text
|
|
16
16
|
from nace_cli._output import to_json
|
|
17
17
|
|
|
18
|
-
#: The
|
|
18
|
+
#: The default image model, which `--image` picks when no model is named; the retired id resolves to `drex-max-v1.1`.
|
|
19
19
|
IMAGE_MODEL = "drex-max"
|
|
20
20
|
#: Drex Max reads at most this many images per request.
|
|
21
21
|
MAX_IMAGES = 8
|
|
@@ -131,7 +131,7 @@ def add_parsers(sub: argparse._SubParsersAction, common: argparse.ArgumentParser
|
|
|
131
131
|
ground.add_argument(
|
|
132
132
|
"--semantic",
|
|
133
133
|
action="store_true",
|
|
134
|
-
help="
|
|
134
|
+
help="Match every target by meaning (its text describes what to find), unless it sets semantic itself.",
|
|
135
135
|
)
|
|
136
136
|
ground.set_defaults(run=run_ground)
|
|
137
137
|
|
|
@@ -190,7 +190,12 @@ def _operation(sub: argparse._SubParsersAction, common: argparse.ArgumentParser,
|
|
|
190
190
|
)
|
|
191
191
|
parser.add_argument("--options", default=None, metavar="JSON", help="Request fields as a JSON object (file, @FILE, inline); flags win.")
|
|
192
192
|
parser.add_argument("--wait-seconds", type=int, default=None, metavar="N", help="Hold the create open up to N seconds (max 60).")
|
|
193
|
-
parser.add_argument(
|
|
193
|
+
parser.add_argument(
|
|
194
|
+
"--idempotency-key",
|
|
195
|
+
default=None,
|
|
196
|
+
metavar="KEY",
|
|
197
|
+
help="Retries return the original job for this key. Omit or change the key to start a new run.",
|
|
198
|
+
)
|
|
194
199
|
add_wait_args(parser)
|
|
195
200
|
add_job_output_args(parser)
|
|
196
201
|
parser.set_defaults(family="client", operation=name)
|
|
@@ -0,0 +1,239 @@
|
|
|
1
|
+
"""``nace folder-metadata`` and ``nace catalog``: what the workspace holds, without reading it.
|
|
2
|
+
|
|
3
|
+
The navigate tools find and read; these answer questions about the workspace as a whole. folder-metadata lists
|
|
4
|
+
folders (file counts, categories, paths) and catalog is the metadata ingestion extracted from every document - its
|
|
5
|
+
type and typed fields such as an invoice's number, parties, date and total - as tables one SELECT reads. The
|
|
6
|
+
folder text follows the ndi CLI's; ``--json`` prints the whole response.
|
|
7
|
+
"""
|
|
8
|
+
|
|
9
|
+
from __future__ import annotations
|
|
10
|
+
|
|
11
|
+
import argparse
|
|
12
|
+
import json
|
|
13
|
+
import sys
|
|
14
|
+
from typing import Any
|
|
15
|
+
|
|
16
|
+
from nace_sdk import NaceClient
|
|
17
|
+
from nace_sdk._core import endpoints as ep
|
|
18
|
+
from nace_sdk._core.tool_types import CatalogResponse, FolderMetadataResponse
|
|
19
|
+
|
|
20
|
+
from nace_cli._navigate import post_tool
|
|
21
|
+
from nace_cli._skill import note_skills
|
|
22
|
+
from nace_cli._workspaces import add_workspace_arg, workspace_id
|
|
23
|
+
|
|
24
|
+
#: The server's largest folder-metadata page (FOLDER_METADATA_MAX_FILES).
|
|
25
|
+
FOLDER_PAGE_MAX = 500
|
|
26
|
+
#: The most paths --names-only lists.
|
|
27
|
+
NAMES_ONLY_MAX = 10_000
|
|
28
|
+
#: A catalog cell longer than this is cut in the text (--json has it whole).
|
|
29
|
+
CELL_CHARS = 300
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
def add_parsers(sub: argparse._SubParsersAction, common: argparse.ArgumentParser) -> None:
|
|
33
|
+
folder = sub.add_parser(
|
|
34
|
+
"folder-metadata",
|
|
35
|
+
parents=[common],
|
|
36
|
+
help="List a folder: file counts, categories, subfolders and its files' paths.",
|
|
37
|
+
description=(
|
|
38
|
+
"Describes each DIR (default /): how many files it holds, their categories and ingestion status, one "
|
|
39
|
+
"line per subfolder, and one page of its files. Non-recursive unless a narrow (--category, --status, "
|
|
40
|
+
"--kind, --name-contains) or --recursive is given. --names-only prints every path in scope, one per line."
|
|
41
|
+
),
|
|
42
|
+
)
|
|
43
|
+
folder.add_argument("targets", nargs="*", default=["/"], metavar="DIR", help="Folders to describe (default /).")
|
|
44
|
+
recursion = folder.add_mutually_exclusive_group()
|
|
45
|
+
recursion.add_argument("--recursive", dest="recursive", action="store_true", default=None, help="The whole subtree.")
|
|
46
|
+
recursion.add_argument("--no-recursive", dest="recursive", action="store_false", default=None, help="This folder only, even when narrowed.")
|
|
47
|
+
folder.add_argument("--category", default=None, help="Exact category name from an earlier listing.")
|
|
48
|
+
folder.add_argument("--status", default=None, metavar="STATUS", help="Ingestion status (e.g. failed).")
|
|
49
|
+
folder.add_argument("--kind", default=None, help="table, document or media.")
|
|
50
|
+
folder.add_argument("--name-contains", default=None, metavar="TEXT", help="Case-insensitive part of a file's path.")
|
|
51
|
+
folder.add_argument("--page-size", type=int, default=100, metavar="N", help="Files listed per page (default 100).")
|
|
52
|
+
folder.add_argument("--start-after", default=None, metavar="PATH", help="Resume the listing after this path.")
|
|
53
|
+
folder.add_argument("--names-only", action="store_true", help="Every path in scope, one per line (all pages).")
|
|
54
|
+
add_workspace_arg(folder)
|
|
55
|
+
folder.set_defaults(run=run_folder_metadata, family="client")
|
|
56
|
+
|
|
57
|
+
catalog = sub.add_parser(
|
|
58
|
+
"catalog",
|
|
59
|
+
parents=[common],
|
|
60
|
+
help="The documents' extracted metadata as tables: list them, or run one SELECT.",
|
|
61
|
+
description=(
|
|
62
|
+
"Without SQL: the catalog's tables - catalog_document (every document section: path, pages, type, "
|
|
63
|
+
"summary) and one table per document type the workspace holds (invoice, contract, ...) with its typed "
|
|
64
|
+
"fields - and how many records each has. With SQL: one read-only SELECT over them (DuckDB dialect); at "
|
|
65
|
+
"most 200 rows come back, and a cut result says so."
|
|
66
|
+
),
|
|
67
|
+
)
|
|
68
|
+
catalog.add_argument("sql", nargs="?", default=None, help="One SELECT over the catalog tables.")
|
|
69
|
+
add_workspace_arg(catalog)
|
|
70
|
+
catalog.set_defaults(run=run_catalog, family="client")
|
|
71
|
+
|
|
72
|
+
|
|
73
|
+
# --- folder-metadata ------------------------------------------------------------------------------
|
|
74
|
+
|
|
75
|
+
|
|
76
|
+
def run_folder_metadata(client: NaceClient, args: argparse.Namespace) -> int:
|
|
77
|
+
note_skills()
|
|
78
|
+
workspace = workspace_id(client, args)
|
|
79
|
+
if args.start_after is not None and len(args.targets) > 1:
|
|
80
|
+
raise ValueError("--start-after resumes one folder's listing; pass a single folder with it")
|
|
81
|
+
|
|
82
|
+
def fetch(directory: str, after: str | None) -> dict[str, Any]:
|
|
83
|
+
body = ep.present(
|
|
84
|
+
{
|
|
85
|
+
"directory": directory,
|
|
86
|
+
"recursive": True if args.names_only and args.recursive is None else args.recursive,
|
|
87
|
+
"category": args.category,
|
|
88
|
+
"ingestion_status": args.status,
|
|
89
|
+
"kind": args.kind,
|
|
90
|
+
"name_contains": args.name_contains,
|
|
91
|
+
"page_size": FOLDER_PAGE_MAX if args.names_only else min(args.page_size, FOLDER_PAGE_MAX),
|
|
92
|
+
"start_after": after,
|
|
93
|
+
}
|
|
94
|
+
)
|
|
95
|
+
response = post_tool(client, workspace, "folder-metadata", body, FolderMetadataResponse)
|
|
96
|
+
return response.model_dump(mode="json", exclude_none=True)
|
|
97
|
+
|
|
98
|
+
outputs: list[str] = []
|
|
99
|
+
for directory in args.targets:
|
|
100
|
+
if args.names_only:
|
|
101
|
+
entries: list[dict[str, Any]] = []
|
|
102
|
+
after = args.start_after
|
|
103
|
+
for _ in range(NAMES_ONLY_MAX // FOLDER_PAGE_MAX):
|
|
104
|
+
page = fetch(directory, after)
|
|
105
|
+
entries += page.get("file_entries") or []
|
|
106
|
+
if not page.get("files_truncated") or not page.get("file_entries"):
|
|
107
|
+
break
|
|
108
|
+
after = entries[-1]["path"]
|
|
109
|
+
page["file_entries"] = entries
|
|
110
|
+
if args.json:
|
|
111
|
+
outputs.append(json.dumps(page, indent=2))
|
|
112
|
+
continue
|
|
113
|
+
# Stdout carries the paths alone, so the list pipes; what is missing or cut goes to stderr.
|
|
114
|
+
if not entries:
|
|
115
|
+
print(f"no files in {directory}", file=sys.stderr)
|
|
116
|
+
elif page.get("files_truncated"):
|
|
117
|
+
print(
|
|
118
|
+
f"... more files: narrow with a folder or --name-contains, or --start-after {entries[-1]['path']}",
|
|
119
|
+
file=sys.stderr,
|
|
120
|
+
)
|
|
121
|
+
outputs.append(render_names(page))
|
|
122
|
+
continue
|
|
123
|
+
page = fetch(directory, args.start_after)
|
|
124
|
+
outputs.append(json.dumps(page, indent=2) if args.json else render_folder(page))
|
|
125
|
+
text = "\n\n".join(output for output in outputs if output)
|
|
126
|
+
if text:
|
|
127
|
+
print(text)
|
|
128
|
+
return 0
|
|
129
|
+
|
|
130
|
+
|
|
131
|
+
def render_names(page: dict[str, Any]) -> str:
|
|
132
|
+
return "\n".join(entry["path"] for entry in page.get("file_entries") or [])
|
|
133
|
+
|
|
134
|
+
|
|
135
|
+
def render_folder(page: dict[str, Any]) -> str:
|
|
136
|
+
lines = [f"directory: {page.get('directory')}", f"files in scope: {page.get('overall_files', 0)}"]
|
|
137
|
+
if page.get("categories"):
|
|
138
|
+
lines.append(f"categories: {_categories(page['categories'])}")
|
|
139
|
+
if page.get("ingestion_summary"):
|
|
140
|
+
lines.append("ingestion: " + ", ".join(f"{k} x{v}" for k, v in sorted(page["ingestion_summary"].items())))
|
|
141
|
+
subdirectories = page.get("subdirectories") or []
|
|
142
|
+
if subdirectories:
|
|
143
|
+
lines.append(f"subdirectories ({len(subdirectories)}):")
|
|
144
|
+
for sub in subdirectories:
|
|
145
|
+
failed = f" ({sub['failed_files']} failed)" if sub.get("failed_files") else ""
|
|
146
|
+
cats = f" categories: {_categories(sub['top_categories'], limit=3)}" if sub.get("top_categories") else ""
|
|
147
|
+
lines.append(f" {sub['name']}/ {sub.get('overall_files', 0)} files{failed}{cats}")
|
|
148
|
+
entries = page.get("file_entries") or []
|
|
149
|
+
if entries:
|
|
150
|
+
cut = " (truncated - resume with --start-after, or narrow with --name-contains or --kind)" if page.get("files_truncated") else ""
|
|
151
|
+
lines.append(f"files listed ({len(entries)}){cut}:")
|
|
152
|
+
for entry in entries:
|
|
153
|
+
extras = " ".join(part for part in (entry.get("category"), entry.get("kind")) if part)
|
|
154
|
+
extras = f" [{extras}]" if extras else ""
|
|
155
|
+
lines.append(f" {entry.get('ingestion_status')} {_size(entry.get('size_bytes')):>9} {entry['path']}{extras}")
|
|
156
|
+
if page.get("hint"):
|
|
157
|
+
lines.append(f"hint: {page['hint']}")
|
|
158
|
+
lines.extend(_coverage(page.get("coverage")))
|
|
159
|
+
return "\n".join(lines)
|
|
160
|
+
|
|
161
|
+
|
|
162
|
+
# --- catalog --------------------------------------------------------------------------------------
|
|
163
|
+
|
|
164
|
+
|
|
165
|
+
def run_catalog(client: NaceClient, args: argparse.Namespace) -> int:
|
|
166
|
+
note_skills()
|
|
167
|
+
body = ep.present({"sql": args.sql})
|
|
168
|
+
response = post_tool(client, workspace_id(client, args), "catalog", body, CatalogResponse).model_dump(mode="json", exclude_none=True)
|
|
169
|
+
if args.json:
|
|
170
|
+
print(json.dumps(response, indent=2))
|
|
171
|
+
elif args.sql is None:
|
|
172
|
+
print(render_catalog_tables(response))
|
|
173
|
+
else:
|
|
174
|
+
print(render_catalog_rows(response))
|
|
175
|
+
return 0
|
|
176
|
+
|
|
177
|
+
|
|
178
|
+
def render_catalog_tables(response: dict[str, Any]) -> str:
|
|
179
|
+
lines = []
|
|
180
|
+
for table in response.get("tables") or []:
|
|
181
|
+
lines.append(f"{table['table']} ({table['in_scope_components']} records): {table.get('description', '')}".rstrip(": "))
|
|
182
|
+
for column in table.get("columns") or []:
|
|
183
|
+
if column["name"].endswith("_status"):
|
|
184
|
+
continue # every field has one: named once in the note below
|
|
185
|
+
lines.append(f" {column['name']} ({column['kind']}){': ' + column['description'] if column.get('description') else ''}")
|
|
186
|
+
empty = [table["table"] for table in response.get("empty_tables") or []]
|
|
187
|
+
if empty:
|
|
188
|
+
lines.append(f"empty (no records here; queries over them return nothing): {', '.join(empty)}")
|
|
189
|
+
lines.append(
|
|
190
|
+
"note: each field FIELD has a FIELD_status column (whether extraction found it); money fields have FIELD_currency. "
|
|
191
|
+
"Repeated fields are their own tables ({table}_{field}: record_id, item_index, value), joined on record_id."
|
|
192
|
+
)
|
|
193
|
+
return "\n".join(lines)
|
|
194
|
+
|
|
195
|
+
|
|
196
|
+
def render_catalog_rows(response: dict[str, Any]) -> str:
|
|
197
|
+
rows = response.get("rows") or []
|
|
198
|
+
cut = ", cut: narrow the WHERE or page with LIMIT/OFFSET" if response.get("truncated") else ""
|
|
199
|
+
lines = [f"{len(rows)} rows{cut}"]
|
|
200
|
+
columns = response.get("columns") or []
|
|
201
|
+
if columns:
|
|
202
|
+
lines.append(" " + " | ".join(columns))
|
|
203
|
+
for row in rows:
|
|
204
|
+
cells = {key: _clip(value) for key, value in row.items()}
|
|
205
|
+
lines.append(" " + json.dumps(cells, ensure_ascii=False, default=str))
|
|
206
|
+
return "\n".join(lines)
|
|
207
|
+
|
|
208
|
+
|
|
209
|
+
# --- shared ---------------------------------------------------------------------------------------
|
|
210
|
+
|
|
211
|
+
|
|
212
|
+
def _clip(value: Any) -> Any:
|
|
213
|
+
if isinstance(value, str) and len(value) > CELL_CHARS:
|
|
214
|
+
return value[:CELL_CHARS] + f"... [{len(value) - CELL_CHARS} more chars, --json has all]"
|
|
215
|
+
return value
|
|
216
|
+
|
|
217
|
+
|
|
218
|
+
def _categories(pairs: list[dict[str, Any]], limit: int | None = None) -> str:
|
|
219
|
+
shown = pairs if limit is None else pairs[:limit]
|
|
220
|
+
rendered = ", ".join(f"{c['name']} x{c['count']}" for c in shown)
|
|
221
|
+
if limit is not None and len(pairs) > limit:
|
|
222
|
+
rendered += f", +{len(pairs) - limit} more"
|
|
223
|
+
return rendered
|
|
224
|
+
|
|
225
|
+
|
|
226
|
+
def _coverage(coverage: dict[str, Any] | None) -> list[str]:
|
|
227
|
+
withheld = (coverage or {}).get("restricted_candidates") or 0
|
|
228
|
+
return [f"note: {withheld} file(s) withheld by access controls"] if withheld else []
|
|
229
|
+
|
|
230
|
+
|
|
231
|
+
def _size(num_bytes: int | None) -> str:
|
|
232
|
+
if num_bytes is None:
|
|
233
|
+
return "?"
|
|
234
|
+
value = float(num_bytes)
|
|
235
|
+
for unit in ("B", "KB", "MB"):
|
|
236
|
+
if value < 1024:
|
|
237
|
+
return f"{int(value)}B" if unit == "B" else f"{value:.1f}{unit}"
|
|
238
|
+
value /= 1024
|
|
239
|
+
return f"{value:.1f}GB"
|