trefoil-cli 0.2.0__tar.gz → 1.1.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.

Potentially problematic release.


This version of trefoil-cli might be problematic. Click here for more details.

@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: trefoil-cli
3
- Version: 0.2.0
3
+ Version: 1.1.1
4
4
  Summary: CLI for the trefoil agent server
5
5
  Requires-Python: >=3.10
6
6
  Requires-Dist: pyyaml>=6
@@ -2,7 +2,7 @@
2
2
  """Bundle a trefoil config.yml into a single JSON file.
3
3
 
4
4
  Resolves:
5
- - `!Ref file://path` and `!Ref https://url` tags
5
+ - `!include file://path` and `!include https://url` tags
6
6
  - bare `file://path` strings (bare https:// strings are left as-is)
7
7
 
8
8
  Referenced .yml/.yaml/.json files are parsed and resolved recursively;
@@ -13,6 +13,10 @@ directory of the file that references them.
13
13
 
14
14
  Usage: trefoil <domain> <command> [args]
15
15
 
16
+ trefoil init [DIR] [--example=NAME]
17
+ trefoil update
18
+ trefoil engine start [--settings=backend.yml] [--port=8080] [-d]
19
+ trefoil engine stop
16
20
  trefoil config package path/to/config.yml [-o bundle.json]
17
21
  trefoil config sync [path/to/config.yml] [--server URL]
18
22
  trefoil agents list
@@ -29,8 +33,11 @@ import argparse
29
33
  import base64
30
34
  import getpass
31
35
  import importlib.metadata
36
+ import importlib.util
32
37
  import json
33
38
  import os
39
+ import shutil
40
+ import subprocess
34
41
  import sys
35
42
  import time
36
43
  import urllib.error
@@ -41,6 +48,7 @@ from pathlib import Path
41
48
  import yaml
42
49
 
43
50
  DEFAULT_SERVER = "http://localhost:8080"
51
+ EXAMPLES_API = "https://api.github.com/repos/alto-se/trefoil/contents/examples"
44
52
 
45
53
 
46
54
  class Ref:
@@ -52,7 +60,8 @@ class Loader(yaml.SafeLoader):
52
60
  pass
53
61
 
54
62
 
55
- Loader.add_constructor("!Ref", lambda loader, node: Ref(loader.construct_scalar(node)))
63
+ for _tag in ("!include", "!Ref"): # !Ref is the old name, still accepted
64
+ Loader.add_constructor(_tag, lambda loader, node: Ref(loader.construct_scalar(node)))
56
65
 
57
66
 
58
67
  class Packager:
@@ -109,7 +118,7 @@ class Packager:
109
118
 
110
119
  def read_folder(root):
111
120
  """Every file under root as {relative path: text}, skipping hidden files
112
- and __pycache__, like shared bricks on the server."""
121
+ and __pycache__, like shared modules on the server."""
113
122
  files = {}
114
123
  for path in sorted(root.rglob("*")):
115
124
  rel = path.relative_to(root)
@@ -143,6 +152,94 @@ def cmd_package(args):
143
152
  print(out)
144
153
 
145
154
 
155
+ def example_files(url, prefix=""):
156
+ """Yields (relative path, download URL) for every file in an example folder on GitHub."""
157
+ with urllib.request.urlopen(url, timeout=30) as resp:
158
+ entries = json.loads(resp.read())
159
+ for e in entries:
160
+ if e["type"] == "dir":
161
+ yield from example_files(e["url"], prefix + e["name"] + "/")
162
+ elif e["type"] == "file":
163
+ yield prefix + e["name"], e["download_url"]
164
+
165
+
166
+ def cmd_init(args):
167
+ dest = args.dir or Path(args.example)
168
+ if dest.exists() and (not dest.is_dir() or any(dest.iterdir())):
169
+ sys.exit(f"trefoil: {dest} already exists and is not empty")
170
+ try:
171
+ files = list(example_files(f"{EXAMPLES_API}/{quote(args.example)}?ref=main"))
172
+ for rel, url in files:
173
+ with urllib.request.urlopen(url, timeout=30) as resp:
174
+ data = resp.read()
175
+ path = dest / rel
176
+ path.parent.mkdir(parents=True, exist_ok=True)
177
+ path.write_bytes(data)
178
+ except urllib.error.HTTPError as e:
179
+ if e.code == 404:
180
+ sys.exit(f"trefoil: no example named {args.example}")
181
+ sys.exit(f"trefoil: fetching example {args.example}: {e}")
182
+ except urllib.error.URLError as e:
183
+ sys.exit(f"trefoil: cannot fetch example {args.example}: {e.reason}")
184
+ print(f"created {dest} from example {args.example} ({len(files)} files)")
185
+ print(f"next: cd {dest} && trefoil config sync")
186
+
187
+
188
+ def cmd_update(args):
189
+ # An editable install runs straight from a checkout; reinstalling from PyPI would replace it.
190
+ if Path(__file__).with_name("pyproject.toml").exists():
191
+ sys.exit(f"trefoil: running from a source checkout ({Path(__file__).parent}); "
192
+ "pull and run `make cli` instead")
193
+ # uv-created environments (uv tool install, uv venv) have no pip of their own.
194
+ if importlib.util.find_spec("pip"):
195
+ cmd = [sys.executable, "-m", "pip", "install", "--upgrade", "--force-reinstall", "trefoil-cli"]
196
+ elif shutil.which("uv"):
197
+ cmd = ["uv", "pip", "install", "--python", sys.executable, "--upgrade", "--reinstall", "trefoil-cli"]
198
+ else:
199
+ sys.exit("trefoil: neither pip nor uv is available to reinstall trefoil-cli")
200
+ print(f"trefoil {cli_version()}: {' '.join(cmd)}", file=sys.stderr)
201
+ sys.exit(subprocess.run(cmd).returncode)
202
+
203
+
204
+ def cmd_engine_start(args):
205
+ if not shutil.which("docker"):
206
+ sys.exit("trefoil: docker is not installed or not on PATH")
207
+ cmd = ["docker", "run", "--rm", "--name", args.name, "-p", f"{args.port}:8080",
208
+ "-v", "/var/run/docker.sock:/var/run/docker.sock", "-v", f"{args.volume}:/data"]
209
+ if args.settings:
210
+ path = args.settings.resolve()
211
+ if not path.is_file():
212
+ sys.exit(f"trefoil: {args.settings} is not a file")
213
+ mount = f"/trefoil/settings/{path.name}"
214
+ cmd += ["-v", f"{path}:{mount}:ro", "-e", f"TREFOIL_SETTINGS={mount}"]
215
+ # The server resolves env_file against the settings file and fails if
216
+ # it's missing, so mount it where it will look.
217
+ try:
218
+ env_file = (yaml.safe_load(path.read_text()) or {}).get("env_file")
219
+ except (yaml.YAMLError, AttributeError) as e:
220
+ sys.exit(f"trefoil: {args.settings}: {e}")
221
+ if env_file:
222
+ host = (path.parent / env_file).resolve()
223
+ if not host.is_file():
224
+ sys.exit(f"trefoil: env_file {host} (from {args.settings}) not found")
225
+ target = env_file if os.path.isabs(env_file) else os.path.normpath(f"/trefoil/settings/{env_file}")
226
+ cmd += ["-v", f"{host}:{target}:ro"]
227
+ if args.detach:
228
+ cmd.append("-d")
229
+ cmd.append(args.image)
230
+ print(f"trefoil: {' '.join(cmd)}", file=sys.stderr)
231
+ sys.exit(subprocess.run(cmd).returncode)
232
+
233
+
234
+ def cmd_engine_stop(args):
235
+ if not shutil.which("docker"):
236
+ sys.exit("trefoil: docker is not installed or not on PATH")
237
+ # started with --rm, so stopping also removes the container
238
+ cmd = ["docker", "stop", args.name]
239
+ print(f"trefoil: {' '.join(cmd)}", file=sys.stderr)
240
+ sys.exit(subprocess.run(cmd, stdout=subprocess.DEVNULL).returncode)
241
+
242
+
146
243
  def api_request(server, method, path, body=None, timeout=30, raw=False):
147
244
  """Calls the API and returns the decoded JSON, or the bytes with raw=True."""
148
245
  req = urllib.request.Request(server.rstrip("/") + path, data=body, method=method)
@@ -411,12 +508,12 @@ def cmd_agents_list(args):
411
508
  agents = api_request(args.server, "GET", "/agents")
412
509
 
413
510
  rows = [
414
- (a["name"], a.get("model") or "(default)", a.get("provider") or "anthropic", ", ".join(a["bricks"]),
511
+ (a["name"], a.get("model") or "(default)", a.get("provider") or "anthropic", ", ".join(a["modules"]),
415
512
  format_input_schema(a.get("input_schema")), format_fields(a.get("outputs")), str(a["prompts"]),
416
513
  "yes" if a["built"] else "no")
417
514
  for a in agents
418
515
  ]
419
- print_table(("NAME", "MODEL", "PROVIDER", "BRICKS", "INPUT", "OUTPUTS", "PROMPTS", "BUILT"), rows,
516
+ print_table(("NAME", "MODEL", "PROVIDER", "MODULES", "INPUT", "OUTPUTS", "PROMPTS", "BUILT"), rows,
420
517
  empty="no agents")
421
518
 
422
519
 
@@ -469,6 +566,31 @@ def main():
469
566
  return domains.add_parser(name, help=help_text).add_subparsers(
470
567
  dest="command", metavar="<command>", required=True)
471
568
 
569
+ init = domains.add_parser("init", help="scaffold a project from an example config")
570
+ init.add_argument("dir", type=Path, nargs="?", help="directory to create (default: the example's name)")
571
+ init.add_argument("--example", default="echo", metavar="NAME",
572
+ help="example under examples/ in github.com/alto-se/trefoil (default: echo)")
573
+ init.set_defaults(func=cmd_init)
574
+
575
+ update = domains.add_parser("update", help="reinstall the latest trefoil-cli from PyPI")
576
+ update.set_defaults(func=cmd_update)
577
+
578
+ engine = domain("engine", "run the trefoil API server locally with docker")
579
+ engine_start = engine.add_parser("start", help="run the trefoil API server image")
580
+ engine_start.add_argument("--settings", type=Path, metavar="FILE",
581
+ help="backend settings file (backend.yml) to mount into the container")
582
+ engine_start.add_argument("--port", type=int, default=8080, help="host port to publish (default: 8080)")
583
+ engine_start.add_argument("--image", default="ghcr.io/alto-se/trefoil-api:latest",
584
+ help="API image (default: ghcr.io/alto-se/trefoil-api:latest)")
585
+ engine_start.add_argument("--name", default="trefoil-api", help="container name (default: trefoil-api)")
586
+ engine_start.add_argument("--volume", default="trefoil-data",
587
+ help="docker volume (or host path) for the data dir (default: trefoil-data)")
588
+ engine_start.add_argument("-d", "--detach", action="store_true", help="run in the background")
589
+ engine_start.set_defaults(func=cmd_engine_start)
590
+ engine_stop = engine.add_parser("stop", help="stop the running API server container")
591
+ engine_stop.add_argument("--name", default="trefoil-api", help="container name (default: trefoil-api)")
592
+ engine_stop.set_defaults(func=cmd_engine_stop)
593
+
472
594
  config = domain("config", "package and upload agent configs")
473
595
  package = config.add_parser("package", help=__doc__.splitlines()[0])
474
596
  package.add_argument("config", type=Path, help="path to config.yml")
@@ -520,7 +642,7 @@ def main():
520
642
  sub.add_argument("-o", "--output", type=Path, metavar="DIR",
521
643
  help="download every artifact into DIR instead of listing them")
522
644
 
523
- secrets = domain("secrets", "provide secrets that agents' bricks require")
645
+ secrets = domain("secrets", "provide secrets that agents' modules require")
524
646
  secrets_set = secrets.add_parser("set", parents=[server],
525
647
  help="store a secret on the server (value from a prompt or stdin)")
526
648
  secrets_set.add_argument("--name", required=True, metavar="NAME", help="secret name, e.g. github_token")
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "trefoil-cli"
3
- version = "0.2.0"
3
+ version = "1.1.1"
4
4
  description = "CLI for the trefoil agent server"
5
5
  requires-python = ">=3.10"
6
6
  dependencies = ["pyyaml>=6"]
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: trefoil-cli
3
- Version: 0.2.0
3
+ Version: 1.1.1
4
4
  Summary: CLI for the trefoil agent server
5
5
  Requires-Python: >=3.10
6
6
  Requires-Dist: pyyaml>=6
File without changes