simula-gen 0.1.0__py3-none-any.whl

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.
simula/__init__.py ADDED
@@ -0,0 +1,5 @@
1
+ """Schema-driven synthetic data generation."""
2
+
3
+ __all__ = ["__version__"]
4
+
5
+ __version__ = "0.1.0"
simula/cli.py ADDED
@@ -0,0 +1,120 @@
1
+ from __future__ import annotations
2
+
3
+ import argparse
4
+ import asyncio
5
+ import time
6
+
7
+ from .config import load_config
8
+ from .console import error, info, phase, set_quiet
9
+ from .evaluate import run_evaluation
10
+ from .generate import generate_dataset
11
+ from .models import ModelRouter
12
+ from .taxonomy import build_taxonomy
13
+ from .utils import artifact_path, summarize_cost, write_json
14
+
15
+
16
+ def main(argv: list[str] | None = None) -> int:
17
+ return asyncio.run(_main(argv))
18
+
19
+
20
+ def _run_header(cfg, resume: bool) -> None:
21
+ # Echo the run's key parameters up front so a long generate/run isn't a silent black box.
22
+ # One key per line. phase() supplies the blank line above (separating it from the shell prompt);
23
+ # the trailing blank here plus the taxonomy phase's own blank give two lines before the build.
24
+ models = cfg.models
25
+ fmt = "text" if cfg.is_schema_free else "json"
26
+ phase(f"{cfg.project.name} → {cfg.output_dir}")
27
+ info(f"[dim]format = {fmt}[/dim]")
28
+ info(f"[dim]target = {cfg.generation.target_size}[/dim]")
29
+ info(f"[dim]resume = {resume}[/dim]")
30
+ info("[dim]models:[/dim]")
31
+ info(f"[dim] strategic = {models.strategic.model}[/dim]")
32
+ info(f"[dim] bulk = {models.bulk.model}[/dim]")
33
+ info(f"[dim] critic = {models.critic.model}[/dim]")
34
+ info("")
35
+
36
+
37
+ async def _main(argv: list[str] | None = None) -> int:
38
+ parser = argparse.ArgumentParser(prog="simula", description="Schema-driven synthetic data generator.")
39
+ sub = parser.add_subparsers(dest="command", required=True)
40
+ for name in ("validate", "taxonomy", "generate", "evaluate", "run"):
41
+ cmd = sub.add_parser(name)
42
+ cmd.add_argument("config")
43
+ cmd.add_argument("--quiet", action="store_true", help="Suppress live spinners/progress bars (keep phase markers and the final summary).")
44
+ if name in {"generate", "run"}:
45
+ resume = cmd.add_mutually_exclusive_group()
46
+ resume.add_argument("--resume", dest="resume", action="store_true", default=True)
47
+ resume.add_argument("--no-resume", dest="resume", action="store_false")
48
+ cmd.add_argument(
49
+ "--stop-after",
50
+ choices=["taxonomy", "strategies", "meta_prompts", "none"],
51
+ help="Halt once this stage's artifact is written, so it can be edited before rerunning. Overrides generation.stop_after; 'none' disables a config-set stop.",
52
+ )
53
+
54
+ args = parser.parse_args(argv)
55
+ set_quiet(getattr(args, "quiet", False))
56
+ cfg = None
57
+ router = None
58
+ try:
59
+ cfg = load_config(args.config)
60
+ if getattr(args, "stop_after", None):
61
+ cfg.generation.stop_after = None if args.stop_after == "none" else args.stop_after
62
+ router = ModelRouter(cfg.data)
63
+
64
+ # Validate prints static run information and does not invoke any model calls.
65
+ if args.command == "validate":
66
+ info(f"Config OK: {cfg.path}")
67
+ info(f"Output dir: {cfg.output_dir}")
68
+ info(f"Output format: {cfg.output_format}")
69
+ return 0
70
+
71
+ if args.command == "taxonomy":
72
+ taxonomy = await build_taxonomy(cfg, router)
73
+ info("")
74
+ info(f"Wrote taxonomy with {len(taxonomy.get('factors', []))} factors to {cfg.output_dir}")
75
+ return 0
76
+
77
+ if args.command == "generate":
78
+ _run_header(cfg, args.resume)
79
+ rows = await generate_dataset(cfg, router, resume=args.resume, quiet=args.quiet)
80
+ info("")
81
+ info(f"Wrote {len(rows)} final records to {cfg.output_dir}")
82
+ return 0
83
+
84
+ if args.command == "evaluate":
85
+ report = await run_evaluation(cfg, router, quiet=args.quiet)
86
+ info("")
87
+ info(f"Wrote eval report for {report.get('count', 0)} records to {cfg.output_dir}")
88
+ return 0
89
+
90
+ if args.command == "run":
91
+ # generate_dataset loads-or-builds the taxonomy itself; building it here too would
92
+ # rebuild and overwrite an edited/earlier taxonomy on every resumed `run`.
93
+ _run_header(cfg, args.resume)
94
+ rows = await generate_dataset(cfg, router, resume=args.resume, quiet=args.quiet)
95
+ report = await run_evaluation(cfg, router, quiet=args.quiet)
96
+ info("")
97
+ info(f"Run complete: {len(rows)} final records, eval count={report.get('count', 0)}")
98
+ info(f"Artifacts: {cfg.output_dir}")
99
+ return 0
100
+ except Exception as exc:
101
+ error(str(exc))
102
+ return 1
103
+ finally:
104
+ # Flush live LLM logs and persist cost totals before the process exits.
105
+ if router is not None:
106
+ await router.flush_logs()
107
+ if cfg is not None and router is not None:
108
+ summary = summarize_cost(router.cost, time.time() - router.started)
109
+ write_json(artifact_path(cfg.output_dir, "cost"), summary)
110
+ if summary["total_calls"]:
111
+ info(
112
+ f"Cost summary: calls={summary['total_calls']} "
113
+ f"in_tokens={summary['total_input_tokens']} out_tokens={summary['total_output_tokens']}"
114
+ )
115
+
116
+ return 1
117
+
118
+
119
+ if __name__ == "__main__":
120
+ raise SystemExit(main())
simula/config.py ADDED
@@ -0,0 +1,80 @@
1
+ from __future__ import annotations
2
+
3
+ from pathlib import Path
4
+ from typing import Any
5
+
6
+ import yaml
7
+ from dotenv import dotenv_values
8
+ from jsonschema import Draft202012Validator
9
+ from pydantic import ValidationError
10
+
11
+ from . import prompts
12
+ from .console import warn
13
+ from .data_models import Config, TaskType # noqa: F401 - re-exported for the rest of the package
14
+ from .utils import ensure_dir
15
+
16
+
17
+ def resolve_api_key(api_key_env: str) -> str | None:
18
+ # The project-root .env is the ONLY source of API keys: we read it directly with dotenv_values
19
+ # (not load_dotenv + os.getenv), so a shell-exported variable is deliberately ignored. Keep the
20
+ # secret out of the config object/logs — it is read here only when a real client is built.
21
+ return dotenv_values(Path.cwd() / ".env").get(api_key_env)
22
+
23
+
24
+ def load_config(path: str | Path) -> Config:
25
+ # Load YAML, validate via the Pydantic Config model (defaults + ranges + enums live there),
26
+ # attach the prompt set, check the optional schema subset, then ensure the output dir exists.
27
+ config_path = Path(path)
28
+ raw = yaml.safe_load(config_path.read_text(encoding="utf-8")) or {}
29
+
30
+ # The prompt module is a runtime object, not validated config data, so load it separately.
31
+ prompts_ref = raw.pop("prompts", None)
32
+ try:
33
+ cfg = Config.model_validate({**raw, "path": config_path})
34
+ except ValidationError as exc:
35
+ # Present a single ValueError to callers; the field path + reason stay in the message.
36
+ raise ValueError(str(exc)) from exc
37
+
38
+ cfg.prompts = prompts.load_prompt_set(config_path, prompts_ref)
39
+ if cfg.record_schema is not None:
40
+ validate_schema_subset(cfg.record_schema)
41
+ _warn_missing_api_key(cfg)
42
+ ensure_dir(cfg.output_dir)
43
+ return cfg
44
+
45
+
46
+ def _warn_missing_api_key(cfg: Config) -> None:
47
+ # Warn (don't fail — keep `validate` offline-friendly) when a real run has no key in .env.
48
+ roles = ("strategic", "bulk", "critic")
49
+ if all(getattr(cfg.models, role).model == "fake" for role in roles):
50
+ return
51
+ if resolve_api_key(cfg.provider.api_key_env) is None:
52
+ warn(
53
+ f"no API key resolved from .env (api_key_env={cfg.provider.api_key_env}); "
54
+ "real model calls will fail. Put the key in a .env file at the project root."
55
+ )
56
+
57
+
58
+ def validate_schema_subset(schema: dict[str, Any]) -> None:
59
+ # Keep the supported JSON Schema surface deliberately small and testable.
60
+ Draft202012Validator.check_schema(schema)
61
+ allowed = {"object", "string", "number", "integer", "boolean", "array"}
62
+
63
+ def walk(node: dict[str, Any], path: str) -> None:
64
+ node_type = node.get("type")
65
+ if node_type not in allowed:
66
+ raise ValueError(f"Unsupported schema type at {path}: {node_type}")
67
+ if "enum" in node and not isinstance(node["enum"], list):
68
+ raise ValueError(f"enum must be a list at {path}")
69
+ if node_type == "object":
70
+ props = node.get("properties", {})
71
+ if not isinstance(props, dict):
72
+ raise ValueError(f"object properties must be a mapping at {path}")
73
+ for name, child in props.items():
74
+ walk(child, f"{path}.{name}")
75
+ if node_type == "array":
76
+ if "items" not in node:
77
+ raise ValueError(f"array schema requires items at {path}")
78
+ walk(node["items"], f"{path}[]")
79
+
80
+ walk(schema, "$")
simula/console.py ADDED
@@ -0,0 +1,213 @@
1
+ """Human-facing console output via rich.
2
+
3
+ This is the CLI's presentation layer (the run header, phase markers, spinners, progress bars,
4
+ warnings, and the taxonomy review prompt) — deliberately separate from the machine-readable
5
+ `llm_calls.jsonl` audit log, which stays plain JSONL. Both consoles resolve sys.stdout/stderr lazily
6
+ at print time, so they cooperate with pytest's capture.
7
+
8
+ Progress is rendered with rich (there is no tqdm dependency). Only one rich live display may run at a
9
+ time, so callers run phases sequentially: a `spinner()` or `track()` block must close before the next
10
+ one opens or before prompting for input.
11
+ """
12
+
13
+ from __future__ import annotations
14
+
15
+ from collections.abc import Callable, Iterator
16
+ from contextlib import contextmanager
17
+
18
+ from rich.console import Console
19
+ from rich.live import Live
20
+ from rich.markup import escape
21
+ from rich.progress import (
22
+ BarColumn,
23
+ MofNCompleteColumn,
24
+ Progress,
25
+ SpinnerColumn,
26
+ TextColumn,
27
+ TimeElapsedColumn,
28
+ )
29
+ from rich.tree import Tree
30
+
31
+ console = Console()
32
+ err_console = Console(stderr=True)
33
+
34
+ # Quiet mode is process-global, set once by the CLI from --quiet. It suppresses only the animated
35
+ # live elements (spinners, bars); static phase markers, the run header, warnings, and the final
36
+ # summary still print so a redirected log keeps its structure. Functions with their own `quiet`
37
+ # parameter (generate_dataset, run_evaluation) pass it through explicitly and take precedence.
38
+ _quiet = False
39
+
40
+
41
+ def set_quiet(value: bool) -> None:
42
+ global _quiet
43
+ _quiet = value
44
+
45
+
46
+ def info(message: str) -> None:
47
+ console.print(message)
48
+
49
+
50
+ def warn(message: str) -> None:
51
+ err_console.print(f"[yellow]Warning:[/yellow] {message}")
52
+
53
+
54
+ def error(message: str) -> None:
55
+ err_console.print(f"[red]Error:[/red] {message}")
56
+
57
+
58
+ def phase(title: str) -> None:
59
+ # A phase marker with a leading blank line so each section gets breathing room above it.
60
+ # Printed even under --quiet so piped logs keep their shape.
61
+ console.print("")
62
+ console.print(f"[bold cyan]›[/bold cyan] {title}")
63
+
64
+
65
+ def _live(quiet: bool | None) -> bool:
66
+ # Animated displays only make sense on a real terminal and when not silenced. Off a TTY (piped /
67
+ # CI / pytest capture) we fall back to plain lines so no escape codes land in the captured stream.
68
+ silenced = _quiet if quiet is None else quiet
69
+ return not silenced and console.is_terminal
70
+
71
+
72
+ @contextmanager
73
+ def spinner(title: str, *, quiet: bool | None = None) -> Iterator[Callable[[str], None]]:
74
+ """Indeterminate-phase status (taxonomy, strategies). Yields `update(subtitle)` to retitle it.
75
+
76
+ Falls back to one plain `title…` line when silenced or off a TTY, so the phase is still announced
77
+ without animation. Must close before `track()` opens or before prompting for input.
78
+ """
79
+ if not _live(quiet):
80
+ console.print(f" {title}…")
81
+ yield lambda _subtitle: None
82
+ return
83
+ with console.status(f"{title}…", spinner="dots") as status:
84
+ yield lambda subtitle: status.update(f"{title} · {subtitle}…")
85
+
86
+
87
+ @contextmanager
88
+ def track(total: int, description: str, *, quiet: bool | None = None) -> Iterator[Callable[..., None]]:
89
+ """Determinate progress bar (the generation loop). Yields `advance(step=1, description=None)`.
90
+
91
+ Silent when silenced or off a TTY — callers emit a `phase()` marker first, so the phase is still
92
+ visible there. Renders spinner + description + bar + N/total + elapsed. One live display at a time,
93
+ so it must not be nested inside `spinner()`.
94
+ """
95
+ if not _live(quiet):
96
+ yield lambda step=1, description=None: None
97
+ return
98
+ columns = (
99
+ SpinnerColumn(),
100
+ TextColumn("[progress.description]{task.description}"),
101
+ BarColumn(),
102
+ MofNCompleteColumn(),
103
+ TimeElapsedColumn(),
104
+ )
105
+ with Progress(*columns, console=console) as progress:
106
+ task = progress.add_task(description, total=total)
107
+
108
+ def advance(step: int = 1, description: str | None = None) -> None:
109
+ # description=None leaves the label unchanged (rich only updates fields it is given).
110
+ progress.update(task, advance=step, description=description)
111
+
112
+ yield advance
113
+
114
+
115
+ def _tree_label(name: str, description: str = "", *, bold: bool = False) -> str:
116
+ # escape() so model-generated names containing [] don't get parsed as rich markup.
117
+ label = f"[bold]{escape(name)}[/bold]" if bold else escape(name)
118
+ if description:
119
+ short = description if len(description) <= 60 else description[:59] + "…"
120
+ label += f" [dim]— {escape(short)}[/dim]"
121
+ return label
122
+
123
+
124
+ def _node_path(node: dict) -> str:
125
+ return "/".join(node.get("path", [node["name"]]))
126
+
127
+
128
+ class TaxonomyLogger:
129
+ """Surfaces taxonomy nodes as they are generated. The caller drives it with the JSON node dicts:
130
+ `add_factor(root)` when a factor starts, `add_children(parent, children)` as each node's children
131
+ are attached, `finish_factor(root)` when its subtree is done.
132
+
133
+ This no-op base is also the --quiet logger. Subclasses render the two styles:
134
+ - `tree` (TaxonomyTreeLogger): a live-growing tree on a TTY, printed once off a TTY.
135
+ - `light` (TaxonomyLightLogger): flat per-node breadcrumb lines (`+ path → k children`).
136
+ Style is chosen by `taxonomy.log_style`. Only one rich live display runs at a time, so a tree
137
+ logger must close before another live display opens or before the review prompt.
138
+ """
139
+
140
+ def start(self) -> None: ...
141
+ def add_factor(self, node: dict) -> None: ...
142
+ def add_children(self, parent: dict, children: list[dict]) -> None: ...
143
+ def finish_factor(self, node: dict) -> None: ...
144
+ def close(self) -> None: ...
145
+
146
+
147
+ class TaxonomyLightLogger(TaxonomyLogger):
148
+ def add_factor(self, node: dict) -> None:
149
+ desc = node.get("description", "")
150
+ suffix = f" [dim]— {escape(desc[:60])}[/dim]" if desc else ""
151
+ console.print(f"[bold]▸ {escape(node['name'])}[/bold]{suffix}")
152
+
153
+ def add_children(self, parent: dict, children: list[dict]) -> None:
154
+ console.print(f"[dim] + {escape(_node_path(parent))} → {len(children)} children[/dim]")
155
+
156
+
157
+ class TaxonomyTreeLogger(TaxonomyLogger):
158
+ def __init__(self, *, live_enabled: bool) -> None:
159
+ self._tree = Tree("[bold]Taxonomy[/bold]")
160
+ self._branch: dict[int, Tree] = {} # id(node) -> its rich branch; kept off the JSON node
161
+ # vertical_overflow="visible" keeps a deep tree from being cropped to the terminal height.
162
+ self._live = Live(self._tree, console=console, auto_refresh=False, vertical_overflow="visible") if live_enabled else None
163
+
164
+ def start(self) -> None:
165
+ if self._live is not None:
166
+ self._live.start()
167
+ self._live.refresh()
168
+
169
+ def add_factor(self, node: dict) -> None:
170
+ # The "(expanding…)" marker is cleared by finish_factor once the subtree is complete.
171
+ self._branch[id(node)] = self._tree.add(f"{_tree_label(node['name'], node.get('description', ''), bold=True)} [dim](expanding…)[/dim]")
172
+ self._refresh()
173
+
174
+ def add_children(self, parent: dict, children: list[dict]) -> None:
175
+ branch = self._branch.get(id(parent))
176
+ if branch is None:
177
+ return
178
+ for child in children:
179
+ self._branch[id(child)] = branch.add(_tree_label(child["name"], child.get("description", "")))
180
+ self._refresh()
181
+
182
+ def finish_factor(self, node: dict) -> None:
183
+ branch = self._branch.get(id(node))
184
+ if branch is not None:
185
+ branch.label = _tree_label(node["name"], node.get("description", ""), bold=True)
186
+ self._refresh()
187
+
188
+ def _refresh(self) -> None:
189
+ if self._live is not None:
190
+ self._live.refresh()
191
+
192
+ def close(self) -> None:
193
+ if self._live is not None:
194
+ self._live.stop() # leaves the final frame in place
195
+ else:
196
+ console.print(self._tree) # off a TTY: render the finished tree once
197
+
198
+
199
+ @contextmanager
200
+ def taxonomy_logger(*, style: str = "tree", quiet: bool | None = None) -> Iterator[TaxonomyLogger]:
201
+ """Yield the taxonomy logger for `style` (`tree`/`light`); --quiet yields the no-op base."""
202
+ silenced = _quiet if quiet is None else quiet
203
+ if silenced:
204
+ logger: TaxonomyLogger = TaxonomyLogger()
205
+ elif style == "light":
206
+ logger = TaxonomyLightLogger()
207
+ else:
208
+ logger = TaxonomyTreeLogger(live_enabled=console.is_terminal)
209
+ logger.start()
210
+ try:
211
+ yield logger
212
+ finally:
213
+ logger.close()