10xgraph-api 0.7.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.
Files changed (203) hide show
  1. 10xgraph_api-0.7.0.dist-info/METADATA +618 -0
  2. 10xgraph_api-0.7.0.dist-info/RECORD +203 -0
  3. 10xgraph_api-0.7.0.dist-info/WHEEL +5 -0
  4. 10xgraph_api-0.7.0.dist-info/entry_points.txt +3 -0
  5. 10xgraph_api-0.7.0.dist-info/licenses/LICENSE +21 -0
  6. 10xgraph_api-0.7.0.dist-info/top_level.txt +2 -0
  7. agentflow_cli/__init__.py +69 -0
  8. tenxgraph_api/__init__.py +23 -0
  9. tenxgraph_api/cli/__init__.py +6 -0
  10. tenxgraph_api/cli/capabilities.py +127 -0
  11. tenxgraph_api/cli/commands/__init__.py +49 -0
  12. tenxgraph_api/cli/commands/api.py +262 -0
  13. tenxgraph_api/cli/commands/audit.py +213 -0
  14. tenxgraph_api/cli/commands/build.py +305 -0
  15. tenxgraph_api/cli/commands/config.py +71 -0
  16. tenxgraph_api/cli/commands/demo.py +93 -0
  17. tenxgraph_api/cli/commands/eval.py +909 -0
  18. tenxgraph_api/cli/commands/init.py +531 -0
  19. tenxgraph_api/cli/commands/skills.py +532 -0
  20. tenxgraph_api/cli/commands/test.py +113 -0
  21. tenxgraph_api/cli/commands/version.py +47 -0
  22. tenxgraph_api/cli/config_editor/__init__.py +15 -0
  23. tenxgraph_api/cli/config_editor/schema.py +566 -0
  24. tenxgraph_api/cli/config_editor/server.py +240 -0
  25. tenxgraph_api/cli/config_editor/static/app.css +2 -0
  26. tenxgraph_api/cli/config_editor/static/app.js +3 -0
  27. tenxgraph_api/cli/config_editor/static/favicon.svg +11 -0
  28. tenxgraph_api/cli/config_editor/static/index.html +20 -0
  29. tenxgraph_api/cli/config_editor/store.py +120 -0
  30. tenxgraph_api/cli/config_editor/validation.py +377 -0
  31. tenxgraph_api/cli/constants.py +112 -0
  32. tenxgraph_api/cli/context.py +46 -0
  33. tenxgraph_api/cli/core/__init__.py +0 -0
  34. tenxgraph_api/cli/core/animations.py +550 -0
  35. tenxgraph_api/cli/core/config.py +279 -0
  36. tenxgraph_api/cli/core/output.py +625 -0
  37. tenxgraph_api/cli/core/prompts.py +220 -0
  38. tenxgraph_api/cli/core/screen.py +287 -0
  39. tenxgraph_api/cli/core/steps.py +621 -0
  40. tenxgraph_api/cli/core/theme.py +242 -0
  41. tenxgraph_api/cli/core/validation.py +251 -0
  42. tenxgraph_api/cli/exceptions.py +129 -0
  43. tenxgraph_api/cli/logger.py +84 -0
  44. tenxgraph_api/cli/main.py +936 -0
  45. tenxgraph_api/cli/templates/__init__.py +0 -0
  46. tenxgraph_api/cli/templates/defaults.py +844 -0
  47. tenxgraph_api/cli/templates/dev/.env.example +1 -0
  48. tenxgraph_api/cli/templates/dev/10xgraph.json +16 -0
  49. tenxgraph_api/cli/templates/dev/graph/__init__.py +0 -0
  50. tenxgraph_api/cli/templates/dev/graph/agent.py +63 -0
  51. tenxgraph_api/cli/templates/prod/.env.example +75 -0
  52. tenxgraph_api/cli/templates/prod/.pre-commit-config.yaml +50 -0
  53. tenxgraph_api/cli/templates/prod/.python-version +1 -0
  54. tenxgraph_api/cli/templates/prod/10xgraph.json +42 -0
  55. tenxgraph_api/cli/templates/prod/auth/__init__.py +0 -0
  56. tenxgraph_api/cli/templates/prod/auth/agent_auth.py +46 -0
  57. tenxgraph_api/cli/templates/prod/evals/__init__.py +0 -0
  58. tenxgraph_api/cli/templates/prod/evals/user_simulator_eval.py +76 -0
  59. tenxgraph_api/cli/templates/prod/evals/weather_agents_eval.py +53 -0
  60. tenxgraph_api/cli/templates/prod/graph/__init__.py +0 -0
  61. tenxgraph_api/cli/templates/prod/graph/agent.py +50 -0
  62. tenxgraph_api/cli/templates/prod/graph/state.py +5 -0
  63. tenxgraph_api/cli/templates/prod/graph/thread_name_generator.py +7 -0
  64. tenxgraph_api/cli/templates/prod/graph/tools/__init__.py +0 -0
  65. tenxgraph_api/cli/templates/prod/graph/tools/weather_tool.py +43 -0
  66. tenxgraph_api/cli/templates/prod/graph/validators/__init__.py +0 -0
  67. tenxgraph_api/cli/templates/prod/graph/validators/lifecyle.py +107 -0
  68. tenxgraph_api/cli/templates/prod/graph/validators/manager.py +9 -0
  69. tenxgraph_api/cli/templates/prod/graph/validators/validators.py +21 -0
  70. tenxgraph_api/cli/templates/prod/pyproject.toml +79 -0
  71. tenxgraph_api/cli/templates/prod/tests/__init__.py +0 -0
  72. tenxgraph_api/cli/templates/prod/tests/conftest.py +6 -0
  73. tenxgraph_api/cli/templates/prod/tests/test_agent_eval.py +78 -0
  74. tenxgraph_api/cli/templates/prod/tests/test_catalog_tools.py +47 -0
  75. tenxgraph_api/cli/templates/prod/tests/test_graph_nodes.py +57 -0
  76. tenxgraph_api/cli/templates/skills/10xgraph/SKILL.md +92 -0
  77. tenxgraph_api/cli/templates/skills/10xgraph/references/agents-and-tools.md +389 -0
  78. tenxgraph_api/cli/templates/skills/10xgraph/references/api-client.md +61 -0
  79. tenxgraph_api/cli/templates/skills/10xgraph/references/api-configuration.md +75 -0
  80. tenxgraph_api/cli/templates/skills/10xgraph/references/api-settings-and-middleware.md +89 -0
  81. tenxgraph_api/cli/templates/skills/10xgraph/references/architecture.md +91 -0
  82. tenxgraph_api/cli/templates/skills/10xgraph/references/auth-and-authorization.md +149 -0
  83. tenxgraph_api/cli/templates/skills/10xgraph/references/callbacks-and-command.md +283 -0
  84. tenxgraph_api/cli/templates/skills/10xgraph/references/checkpointing-and-threads.md +63 -0
  85. tenxgraph_api/cli/templates/skills/10xgraph/references/cli-commands.md +73 -0
  86. tenxgraph_api/cli/templates/skills/10xgraph/references/client-auth-and-errors.md +94 -0
  87. tenxgraph_api/cli/templates/skills/10xgraph/references/client-messages-invoke-stream.md +115 -0
  88. tenxgraph_api/cli/templates/skills/10xgraph/references/client-threads-memory-files.md +80 -0
  89. tenxgraph_api/cli/templates/skills/10xgraph/references/context-id-background.md +80 -0
  90. tenxgraph_api/cli/templates/skills/10xgraph/references/dependency-injection.md +58 -0
  91. tenxgraph_api/cli/templates/skills/10xgraph/references/evaluation.md +500 -0
  92. tenxgraph_api/cli/templates/skills/10xgraph/references/id-and-thread-name-generators.md +69 -0
  93. tenxgraph_api/cli/templates/skills/10xgraph/references/media-and-files.md +66 -0
  94. tenxgraph_api/cli/templates/skills/10xgraph/references/memory-and-store.md +70 -0
  95. tenxgraph_api/cli/templates/skills/10xgraph/references/prebuilt-agents-and-tools.md +394 -0
  96. tenxgraph_api/cli/templates/skills/10xgraph/references/production-runtime.md +56 -0
  97. tenxgraph_api/cli/templates/skills/10xgraph/references/providers-and-adapters.md +89 -0
  98. tenxgraph_api/cli/templates/skills/10xgraph/references/publishers-and-runtime-protocols.md +84 -0
  99. tenxgraph_api/cli/templates/skills/10xgraph/references/rate-limiting.md +194 -0
  100. tenxgraph_api/cli/templates/skills/10xgraph/references/realtime.md +172 -0
  101. tenxgraph_api/cli/templates/skills/10xgraph/references/remote-tools.md +55 -0
  102. tenxgraph_api/cli/templates/skills/10xgraph/references/rest-api-and-errors.md +97 -0
  103. tenxgraph_api/cli/templates/skills/10xgraph/references/security-and-validators.md +86 -0
  104. tenxgraph_api/cli/templates/skills/10xgraph/references/state-and-messages.md +68 -0
  105. tenxgraph_api/cli/templates/skills/10xgraph/references/state-graph.md +232 -0
  106. tenxgraph_api/cli/templates/skills/10xgraph/references/stream-emitter.md +144 -0
  107. tenxgraph_api/cli/templates/skills/10xgraph/references/streaming.md +53 -0
  108. tenxgraph_api/cli/templates/skills/10xgraph/references/testing-and-evaluation.md +64 -0
  109. tenxgraph_api/cli/templates/skills/10xgraph/references/unit-testing.md +202 -0
  110. tenxgraph_api/cli/templates/skills/copilot/10xgraph.instructions.md +108 -0
  111. tenxgraph_api/py.typed +0 -0
  112. tenxgraph_api/src/__init__.py +0 -0
  113. tenxgraph_api/src/app/__init__.py +13 -0
  114. tenxgraph_api/src/app/core/__init__.py +15 -0
  115. tenxgraph_api/src/app/core/auth/__init__.py +0 -0
  116. tenxgraph_api/src/app/core/auth/auth_backend.py +38 -0
  117. tenxgraph_api/src/app/core/auth/authorization.py +379 -0
  118. tenxgraph_api/src/app/core/auth/base_auth.py +27 -0
  119. tenxgraph_api/src/app/core/auth/jwt_auth.py +122 -0
  120. tenxgraph_api/src/app/core/auth/ownership_resolver.py +170 -0
  121. tenxgraph_api/src/app/core/auth/permissions.py +354 -0
  122. tenxgraph_api/src/app/core/auth/request_config.py +130 -0
  123. tenxgraph_api/src/app/core/auth/route_guard.py +105 -0
  124. tenxgraph_api/src/app/core/config/__init__.py +0 -0
  125. tenxgraph_api/src/app/core/config/graph_config.py +532 -0
  126. tenxgraph_api/src/app/core/config/media_settings.py +72 -0
  127. tenxgraph_api/src/app/core/config/sentry_config.py +60 -0
  128. tenxgraph_api/src/app/core/config/settings.py +202 -0
  129. tenxgraph_api/src/app/core/config/setup_logs.py +65 -0
  130. tenxgraph_api/src/app/core/config/setup_middleware.py +483 -0
  131. tenxgraph_api/src/app/core/config/worker_middleware.py +99 -0
  132. tenxgraph_api/src/app/core/exceptions/__init__.py +17 -0
  133. tenxgraph_api/src/app/core/exceptions/general_exception.py +58 -0
  134. tenxgraph_api/src/app/core/exceptions/handle_errors.py +363 -0
  135. tenxgraph_api/src/app/core/exceptions/resources_exceptions.py +72 -0
  136. tenxgraph_api/src/app/core/exceptions/user_exception.py +58 -0
  137. tenxgraph_api/src/app/core/middleware/__init__.py +25 -0
  138. tenxgraph_api/src/app/core/middleware/rate_limit/__init__.py +15 -0
  139. tenxgraph_api/src/app/core/middleware/rate_limit/base.py +27 -0
  140. tenxgraph_api/src/app/core/middleware/rate_limit/factory.py +98 -0
  141. tenxgraph_api/src/app/core/middleware/rate_limit/keying.py +133 -0
  142. tenxgraph_api/src/app/core/middleware/rate_limit/memory.py +98 -0
  143. tenxgraph_api/src/app/core/middleware/rate_limit/middleware.py +90 -0
  144. tenxgraph_api/src/app/core/middleware/rate_limit/redis.py +115 -0
  145. tenxgraph_api/src/app/core/middleware/request_limits.py +154 -0
  146. tenxgraph_api/src/app/core/middleware/security_headers.py +239 -0
  147. tenxgraph_api/src/app/core/utils/__init__.py +14 -0
  148. tenxgraph_api/src/app/core/utils/log_sanitizer.py +216 -0
  149. tenxgraph_api/src/app/loader.py +516 -0
  150. tenxgraph_api/src/app/main.py +180 -0
  151. tenxgraph_api/src/app/routers/__init__.py +4 -0
  152. tenxgraph_api/src/app/routers/ag_ui/__init__.py +10 -0
  153. tenxgraph_api/src/app/routers/ag_ui/converter.py +195 -0
  154. tenxgraph_api/src/app/routers/ag_ui/event_mapper.py +353 -0
  155. tenxgraph_api/src/app/routers/ag_ui/router.py +90 -0
  156. tenxgraph_api/src/app/routers/ag_ui/service.py +193 -0
  157. tenxgraph_api/src/app/routers/checkpointer/__init__.py +1 -0
  158. tenxgraph_api/src/app/routers/checkpointer/router.py +482 -0
  159. tenxgraph_api/src/app/routers/checkpointer/schemas/__init__.py +1 -0
  160. tenxgraph_api/src/app/routers/checkpointer/schemas/checkpointer_schemas.py +121 -0
  161. tenxgraph_api/src/app/routers/checkpointer/services/__init__.py +1 -0
  162. tenxgraph_api/src/app/routers/checkpointer/services/checkpointer_service.py +300 -0
  163. tenxgraph_api/src/app/routers/evals/__init__.py +6 -0
  164. tenxgraph_api/src/app/routers/evals/router.py +38 -0
  165. tenxgraph_api/src/app/routers/evals/services/__init__.py +1 -0
  166. tenxgraph_api/src/app/routers/evals/services/eval_report_service.py +354 -0
  167. tenxgraph_api/src/app/routers/graph/__init__.py +6 -0
  168. tenxgraph_api/src/app/routers/graph/realtime_guard.py +161 -0
  169. tenxgraph_api/src/app/routers/graph/router.py +821 -0
  170. tenxgraph_api/src/app/routers/graph/schemas/__init__.py +1 -0
  171. tenxgraph_api/src/app/routers/graph/schemas/graph_schemas.py +386 -0
  172. tenxgraph_api/src/app/routers/graph/services/__init__.py +1 -0
  173. tenxgraph_api/src/app/routers/graph/services/graph_service.py +1219 -0
  174. tenxgraph_api/src/app/routers/graph/services/multimodal_preprocessor.py +164 -0
  175. tenxgraph_api/src/app/routers/media/__init__.py +506 -0
  176. tenxgraph_api/src/app/routers/media/router.py +242 -0
  177. tenxgraph_api/src/app/routers/media/schemas.py +39 -0
  178. tenxgraph_api/src/app/routers/ping/__init__.py +4 -0
  179. tenxgraph_api/src/app/routers/ping/router.py +28 -0
  180. tenxgraph_api/src/app/routers/setup_router.py +60 -0
  181. tenxgraph_api/src/app/routers/store/__init__.py +4 -0
  182. tenxgraph_api/src/app/routers/store/router.py +200 -0
  183. tenxgraph_api/src/app/routers/store/schemas/__init__.py +28 -0
  184. tenxgraph_api/src/app/routers/store/schemas/store_schemas.py +200 -0
  185. tenxgraph_api/src/app/routers/store/services/__init__.py +4 -0
  186. tenxgraph_api/src/app/routers/store/services/store_service.py +203 -0
  187. tenxgraph_api/src/app/tasks/__init__.py +0 -0
  188. tenxgraph_api/src/app/tasks/user_tasks.py +38 -0
  189. tenxgraph_api/src/app/utils/__init__.py +12 -0
  190. tenxgraph_api/src/app/utils/callable_helper.py +26 -0
  191. tenxgraph_api/src/app/utils/media/__init__.py +15 -0
  192. tenxgraph_api/src/app/utils/media/extractor.py +172 -0
  193. tenxgraph_api/src/app/utils/media/pipeline.py +83 -0
  194. tenxgraph_api/src/app/utils/parse_output.py +17 -0
  195. tenxgraph_api/src/app/utils/response_helper.py +129 -0
  196. tenxgraph_api/src/app/utils/schemas/__init__.py +11 -0
  197. tenxgraph_api/src/app/utils/schemas/output_schemas.py +28 -0
  198. tenxgraph_api/src/app/utils/schemas/user_schemas.py +13 -0
  199. tenxgraph_api/src/app/utils/snowflake_id_generator.py +90 -0
  200. tenxgraph_api/src/app/utils/swagger_helper.py +160 -0
  201. tenxgraph_api/src/app/utils/telemetry_store.py +123 -0
  202. tenxgraph_api/src/app/utils/thread_name_generator.py +304 -0
  203. tenxgraph_api/src/app/worker.py +91 -0
@@ -0,0 +1,220 @@
1
+ """Guided prompts for the 10xGraph CLI.
2
+
3
+ Every interactive question in the CLI goes through this service rather than
4
+ calling Questionary directly, so that prompts share one theme, one cancellation
5
+ contract, and one non-interactive policy. Commands describe *what* they need to
6
+ ask; how it is rendered, and what happens when there is nobody to answer, is
7
+ decided here.
8
+
9
+ Cancellation is a normal outcome, not an error: each method returns ``None`` when
10
+ the user presses Ctrl+C or Esc, and callers are expected to treat that as "the
11
+ user changed their mind" and exit cleanly.
12
+ """
13
+
14
+ from __future__ import annotations
15
+
16
+ import sys
17
+ from collections.abc import Callable, Sequence
18
+ from dataclasses import dataclass
19
+ from typing import Any
20
+
21
+ import questionary
22
+ from prompt_toolkit.styles import Style
23
+
24
+ from tenxgraph_api.cli.core.theme import ACCENT, AMBER, MUTED, PENDING, SUCCESS
25
+ from tenxgraph_api.cli.exceptions import ValidationError
26
+
27
+
28
+ # Mirrors cli.core.theme, expressed in prompt_toolkit's style syntax. Question and typed
29
+ # text use the terminal's own foreground so prompts read on light and dark themes.
30
+ PROMPT_STYLE = Style(
31
+ [
32
+ ("qmark", f"fg:{AMBER} bold"),
33
+ ("question", "bold"),
34
+ ("answer", f"fg:{ACCENT} bold"),
35
+ ("pointer", f"fg:{AMBER} bold"),
36
+ ("highlighted", f"fg:{ACCENT} bold"),
37
+ ("selected", f"fg:{SUCCESS} bold"),
38
+ ("separator", f"fg:{PENDING}"),
39
+ ("instruction", f"fg:{MUTED}"),
40
+ ("text", ""),
41
+ ("disabled", f"fg:{PENDING} italic"),
42
+ ]
43
+ )
44
+
45
+ MULTI_SELECT_HINT = "space to toggle · a all · i invert · enter to confirm"
46
+ SINGLE_SELECT_HINT = "arrows to move · enter to select"
47
+
48
+ _UNPROMPTABLE = (
49
+ "Could not open an interactive prompt on this terminal. "
50
+ "Pass the value as a command-line flag instead."
51
+ )
52
+
53
+
54
+ def prompt_toolkit_available() -> bool:
55
+ """Whether a full-screen-capable prompt can actually be driven here.
56
+
57
+ ``stdin.isatty()`` is not sufficient on Windows: a stdin that reports as a
58
+ TTY under an MSYS/Cygwin shell still leaves prompt-toolkit unable to attach
59
+ to a console, and it raises rather than degrading. Probing once up front
60
+ turns that into an ordinary "cannot prompt" answer.
61
+ """
62
+ try:
63
+ from prompt_toolkit.input.defaults import create_input
64
+ from prompt_toolkit.output.defaults import create_output
65
+
66
+ create_input()
67
+ create_output()
68
+ except Exception:
69
+ return False
70
+ return True
71
+
72
+
73
+ def _accept_any(_selected: list[str]) -> bool:
74
+ return True
75
+
76
+
77
+ @dataclass(frozen=True)
78
+ class Choice:
79
+ """One option in a select or multi-select prompt."""
80
+
81
+ value: str
82
+ title: str
83
+ description: str | None = None
84
+ checked: bool = False
85
+ disabled: str | None = None
86
+
87
+ def to_questionary(self) -> questionary.Choice:
88
+ """Render the option, keeping its description visually secondary."""
89
+ label: list[tuple[str, str]] = [("class:text", self.title)]
90
+ if self.description:
91
+ label.append(("class:instruction", f" {self.description}"))
92
+ return questionary.Choice(
93
+ title=label,
94
+ value=self.value,
95
+ checked=self.checked,
96
+ disabled=self.disabled,
97
+ )
98
+
99
+
100
+ class PromptService:
101
+ """Ask the user questions, or explain why they cannot be asked."""
102
+
103
+ def __init__(
104
+ self,
105
+ *,
106
+ interactive: bool | None = None,
107
+ on_answered: Callable[[], None] | None = None,
108
+ ) -> None:
109
+ if interactive is None:
110
+ interactive = sys.stdin.isatty() and prompt_toolkit_available()
111
+ self._interactive = interactive
112
+ # Prompt-toolkit erases from the cursor to the end of the screen, which
113
+ # reaches past a scrolling region and takes the pinned footer with it.
114
+ # The owner of that chrome redraws it here once each prompt is done.
115
+ self._on_answered = on_answered
116
+
117
+ @property
118
+ def interactive(self) -> bool:
119
+ """Whether there is a user on the other end who can answer."""
120
+ return self._interactive
121
+
122
+ def require_interactive(self, *, field: str, alternatives: str) -> None:
123
+ """Fail with a recoverable message when a prompt is impossible."""
124
+ if self._interactive:
125
+ return
126
+ raise ValidationError(
127
+ f"{field} is required and stdin is not interactive. {alternatives}",
128
+ field=field,
129
+ )
130
+
131
+ def select(
132
+ self,
133
+ message: str,
134
+ choices: Sequence[Choice],
135
+ *,
136
+ default: str | None = None,
137
+ instruction: str | None = SINGLE_SELECT_HINT,
138
+ ) -> str | None:
139
+ """Pick exactly one option. Returns None if cancelled."""
140
+ options = [choice.to_questionary() for choice in choices]
141
+ default_option = next((o for o in options if o.value == default), None)
142
+ return self._ask(
143
+ lambda: questionary.select(
144
+ message,
145
+ choices=options,
146
+ default=default_option,
147
+ instruction=instruction,
148
+ style=PROMPT_STYLE,
149
+ qmark="?",
150
+ use_shortcuts=False,
151
+ use_indicator=False,
152
+ )
153
+ )
154
+
155
+ def checkbox(
156
+ self,
157
+ message: str,
158
+ choices: Sequence[Choice],
159
+ *,
160
+ instruction: str | None = MULTI_SELECT_HINT,
161
+ validate: Callable[[list[str]], bool | str] | None = None,
162
+ ) -> list[str] | None:
163
+ """Toggle any number of options with space. Returns None if cancelled."""
164
+ return self._ask(
165
+ lambda: questionary.checkbox(
166
+ message,
167
+ choices=[choice.to_questionary() for choice in choices],
168
+ instruction=instruction,
169
+ style=PROMPT_STYLE,
170
+ qmark="?",
171
+ # Questionary requires a validator; accept anything by default.
172
+ validate=validate or _accept_any,
173
+ )
174
+ )
175
+
176
+ def confirm(self, message: str, *, default: bool = False) -> bool | None:
177
+ """Ask a yes/no question. Returns None if cancelled."""
178
+ return self._ask(
179
+ lambda: questionary.confirm(message, default=default, style=PROMPT_STYLE, qmark="?")
180
+ )
181
+
182
+ def text(
183
+ self,
184
+ message: str,
185
+ *,
186
+ default: str = "",
187
+ validate: Callable[[str], bool | str] | None = None,
188
+ ) -> str | None:
189
+ """Ask for a free-text value. Returns None if cancelled."""
190
+ return self._ask(
191
+ lambda: questionary.text(
192
+ message,
193
+ default=default,
194
+ validate=validate,
195
+ style=PROMPT_STYLE,
196
+ qmark="?",
197
+ )
198
+ )
199
+
200
+ def _ask(self, build: Callable[[], questionary.Question]) -> Any:
201
+ """Build and run one question, restoring chrome it may have erased.
202
+
203
+ The question is constructed inside the guard, not passed in ready-made:
204
+ questionary builds its prompt-toolkit application eagerly, so a terminal
205
+ it cannot drive raises during construction rather than during ``ask``.
206
+
207
+ The answer type depends on the question, so each caller narrows it in
208
+ its own return annotation.
209
+ """
210
+ try:
211
+ return build().ask()
212
+ except ValidationError:
213
+ raise
214
+ except Exception as exc:
215
+ # A terminal that cannot host a prompt is a usage problem with a
216
+ # clear fix, not an internal error — report it as one.
217
+ raise ValidationError(_UNPROMPTABLE, field="input") from exc
218
+ finally:
219
+ if self._on_answered is not None:
220
+ self._on_answered()
@@ -0,0 +1,287 @@
1
+ """Persistent full-screen application frame for the 10xGraph CLI.
2
+
3
+ The frame claims the terminal's alternate screen for the whole command and keeps
4
+ branded chrome pinned while the command's output scrolls between it:
5
+
6
+ row 1..4 header — gradient rule, identity, subtitle, divider
7
+ row 5..H-2 body — everything the command prints, scrolling
8
+ row H-1..H footer — divider and status/hint bar
9
+
10
+ Pinning is done with a DEC scrolling region (``CSI top;bottom r``) rather than a
11
+ Rich ``Layout``. That matters: a layout would require every line of output to be
12
+ routed through one renderable, which breaks the moment a command shells out to
13
+ pytest, streams Uvicorn logs, or hands the terminal to a Questionary prompt. A
14
+ scrolling region is enforced by the terminal itself, so ordinary writes — from
15
+ this process or a child — simply scroll inside the body and leave the chrome
16
+ untouched.
17
+
18
+ The frame is opt-in (``--fullscreen``). Because an alternate screen is discarded when
19
+ released, ``close()`` pauses on a "press Enter" footer after a normal finish, so a fast
20
+ command cannot erase its own result. Ctrl+C never waits: it releases the screen at once.
21
+ """
22
+
23
+ from __future__ import annotations
24
+
25
+ import io
26
+ import sys
27
+
28
+ from rich.console import Console
29
+ from rich.text import Text
30
+
31
+ from tenxgraph_api.cli.core.theme import (
32
+ BACKGROUND,
33
+ INK_ON_DARK,
34
+ TENXGRAPH_THEME,
35
+ Glyphs,
36
+ gradient_rule,
37
+ wordmark,
38
+ )
39
+
40
+
41
+ # BACKGROUND (the docs dark --bg) is painted across the alternate screen, so the frame
42
+ # reads as its own surface rather than a cleared prompt.
43
+ _BACKGROUND_RGB = tuple(int(BACKGROUND[index : index + 2], 16) for index in (1, 3, 5))
44
+ _PAINT = "\x1b[48;2;{};{};{}m".format(*_BACKGROUND_RGB)
45
+
46
+ _SAVE_CURSOR = "\x1b7"
47
+ _RESTORE_CURSOR = "\x1b8"
48
+ _CLEAR_SCREEN = "\x1b[2J"
49
+ _RESET_REGION = "\x1b[r"
50
+ _RESET_SGR = "\x1b[0m"
51
+
52
+ _HEADER_ROWS = 4
53
+ _FOOTER_ROWS = 2
54
+ # Below this there is not enough room left for a usable body between the chrome.
55
+ _MIN_FRAME_HEIGHT = 14
56
+ _MIN_FRAME_WIDTH = 50
57
+
58
+
59
+ def _at(row: int, column: int = 1) -> str:
60
+ return f"\x1b[{row};{column}H"
61
+
62
+
63
+ def _scroll_region(top: int, bottom: int) -> str:
64
+ return f"\x1b[{top};{bottom}r"
65
+
66
+
67
+ class AppFrame:
68
+ """Own the alternate screen and keep header/footer chrome pinned to it."""
69
+
70
+ def __init__(self, console: Console, *, glyphs: Glyphs, color: bool) -> None:
71
+ self._console = console
72
+ self._glyphs = glyphs
73
+ self._color = color
74
+ self._open = False
75
+ self._chrome = False
76
+ self._command = ""
77
+ self._subtitle: str | None = None
78
+ self._version: str | None = None
79
+ self._hint = ""
80
+ self._height = 0
81
+ self._width = 0
82
+
83
+ @property
84
+ def active(self) -> bool:
85
+ """Whether this frame currently owns the alternate screen."""
86
+ return self._open
87
+
88
+ @property
89
+ def chrome_installed(self) -> bool:
90
+ """Whether pinned header/footer chrome is currently drawn."""
91
+ return self._chrome
92
+
93
+ # ------------------------------------------------------------------
94
+ # Lifecycle
95
+ # ------------------------------------------------------------------
96
+
97
+ def open(self) -> bool:
98
+ """Enter and paint the alternate screen. Returns False if unsupported."""
99
+ if self._open or not self._console.is_terminal or not self._color:
100
+ return False
101
+
102
+ self._height = self._console.height
103
+ self._width = self._console.width
104
+ if self._height < _MIN_FRAME_HEIGHT or self._width < _MIN_FRAME_WIDTH:
105
+ return False
106
+
107
+ # A legacy console reports itself as a terminal but refuses the alternate
108
+ # buffer. Bail before painting, or the scrolling region below would be
109
+ # applied to the user's real scrollback and outlive the process.
110
+ if not self._console.set_alt_screen(True):
111
+ return False
112
+
113
+ self._write(_PAINT + _CLEAR_SCREEN + _at(1))
114
+ self._open = True
115
+ return True
116
+
117
+ def install_chrome(
118
+ self,
119
+ *,
120
+ command: str,
121
+ subtitle: str | None,
122
+ version: str | None = None,
123
+ hint: str | None = None,
124
+ ) -> None:
125
+ """Draw the pinned header and footer and confine output to the body."""
126
+ if not self._open:
127
+ return
128
+
129
+ self._command = command
130
+ self._subtitle = subtitle
131
+ self._version = version
132
+ self._hint = hint or "Ctrl+C to cancel"
133
+
134
+ self._write(_CLEAR_SCREEN)
135
+ self._draw_header()
136
+ self._draw_footer(self._hint)
137
+ # Confine scrolling to the body, then park the cursor at its top so the
138
+ # first line of output lands directly under the header.
139
+ self._write(_scroll_region(*self._body_bounds()) + _at(_HEADER_ROWS + 1))
140
+ self._chrome = True
141
+
142
+ def redraw_chrome(self) -> None:
143
+ """Repaint the chrome after something else wrote outside the body.
144
+
145
+ Prompt-toolkit erases from the cursor to the end of the *screen*, which
146
+ a scrolling region does not contain — so a prompt takes the footer with
147
+ it and can clear the region itself. Both are re-asserted here.
148
+ """
149
+ if not self._open or not self._chrome:
150
+ return
151
+ self._draw_header()
152
+ self._draw_footer(self._hint)
153
+ # Setting a scrolling region homes the cursor, so bracket it.
154
+ self._write(_SAVE_CURSOR + _scroll_region(*self._body_bounds()) + _RESTORE_CURSOR)
155
+
156
+ def _body_bounds(self) -> tuple[int, int]:
157
+ return _HEADER_ROWS + 1, self._height - _FOOTER_ROWS
158
+
159
+ def close(self, *, hold: bool = True) -> None:
160
+ """Pause on a closing hint, then release the screen and restore the terminal."""
161
+ if not self._open:
162
+ return
163
+ self._open = False
164
+
165
+ if self._chrome:
166
+ self._draw_header()
167
+ self._draw_footer(
168
+ "Press Enter or Ctrl+C to close",
169
+ anchored=True,
170
+ style="tenxgraph.brand",
171
+ )
172
+ self._chrome = False
173
+
174
+ if hold:
175
+ self._wait_for_enter()
176
+
177
+ self._write(_RESET_REGION + _RESET_SGR)
178
+ self._console.set_alt_screen(False)
179
+ self._console.show_cursor(True)
180
+
181
+ # ------------------------------------------------------------------
182
+ # Chrome rendering
183
+ # ------------------------------------------------------------------
184
+
185
+ def _draw_header(self) -> None:
186
+ glyphs = self._glyphs
187
+ width = self._width
188
+
189
+ identity = Text(" ", style="tenxgraph.header")
190
+ identity.append(f"{glyphs.diamond} ", style="tenxgraph.brand")
191
+ # The frame paints a dark surface, so its chrome uses light ink explicitly.
192
+ identity.append_text(wordmark(INK_ON_DARK))
193
+ identity.append(f" {glyphs.caret} ", style="tenxgraph.muted")
194
+ identity.append(self._command, style=f"bold {INK_ON_DARK}")
195
+ if self._version:
196
+ identity.append(" " * max(width - identity.cell_len - len(self._version) - 1, 1))
197
+ identity.append(self._version, style="tenxgraph.muted")
198
+ _pad(identity, width)
199
+
200
+ caption = Text(" ", style="tenxgraph.header")
201
+ caption.append(self._subtitle or "", style="tenxgraph.muted")
202
+ _pad(caption, width)
203
+
204
+ rows = (
205
+ gradient_rule(width, glyphs=glyphs),
206
+ identity,
207
+ caption,
208
+ gradient_rule(width, glyphs=glyphs, thin=True, offset=0.35),
209
+ )
210
+ buffer = _SAVE_CURSOR
211
+ for offset, row in enumerate(rows, start=1):
212
+ buffer += _at(offset) + self._to_ansi(row)
213
+ self._write(buffer + _RESTORE_CURSOR)
214
+
215
+ def _draw_footer(
216
+ self,
217
+ hint: str,
218
+ *,
219
+ anchored: bool = False,
220
+ style: str = "tenxgraph.muted",
221
+ ) -> None:
222
+ glyphs = self._glyphs
223
+ width = self._width
224
+
225
+ status = Text(" ", style="tenxgraph.header")
226
+ status.append(f"{glyphs.caret} ", style="tenxgraph.accent")
227
+ status.append(hint, style=style)
228
+ if self._command:
229
+ label = f"10xgraph {self._command}"
230
+ status.append(" " * max(width - status.cell_len - len(label) - 1, 1))
231
+ status.append(label, style="tenxgraph.muted")
232
+ _pad(status, width)
233
+
234
+ # An anchored footer keeps the cursor parked on it, so there is nothing
235
+ # to save and restore around the write.
236
+ buffer = "" if anchored else _SAVE_CURSOR
237
+ buffer += _at(self._height - 1) + self._to_ansi(
238
+ gradient_rule(width, glyphs=glyphs, thin=True, offset=0.6)
239
+ )
240
+ buffer += _at(self._height) + self._to_ansi(status)
241
+ self._write(buffer + (_at(self._height, width) if anchored else _RESTORE_CURSOR))
242
+
243
+ def _to_ansi(self, renderable: Text) -> str:
244
+ """Render one chrome row to a positioned, self-contained escape string.
245
+
246
+ Chrome is written directly rather than printed, because printing would
247
+ scroll the body region; a standalone console keeps that rendering from
248
+ disturbing the main console's cursor state.
249
+ """
250
+ target = Console(
251
+ file=io.StringIO(),
252
+ theme=TENXGRAPH_THEME,
253
+ force_terminal=True,
254
+ color_system="truecolor",
255
+ width=self._width,
256
+ highlight=False,
257
+ soft_wrap=True,
258
+ )
259
+ with target.capture() as captured:
260
+ target.print(renderable, end="")
261
+ return captured.get()
262
+
263
+ # ------------------------------------------------------------------
264
+ # Terminal plumbing
265
+ # ------------------------------------------------------------------
266
+
267
+ def _write(self, payload: str) -> None:
268
+ if not self._color:
269
+ # Without color the terminal is not trusted with cursor control either.
270
+ return
271
+ self._console.file.write(payload)
272
+ self._console.file.flush()
273
+
274
+ @staticmethod
275
+ def _wait_for_enter() -> None:
276
+ if not sys.stdin.isatty():
277
+ return
278
+ try:
279
+ sys.stdin.readline()
280
+ except (OSError, ValueError, KeyboardInterrupt):
281
+ return
282
+
283
+
284
+ def _pad(text: Text, width: int) -> None:
285
+ padding = width - text.cell_len
286
+ if padding > 0:
287
+ text.append(" " * padding)