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,550 @@
1
+ """Terminal-native animation engine for the 10xGraph CLI.
2
+
3
+ The intro is short (under a second), any key skips it, and Ctrl+C quits at once.
4
+ Its colors come from the logo: ink letters, the amber entry node, the docs accent.
5
+
6
+ The intro always plays on the full canvas; what differs is who owns that canvas.
7
+ Inside an :class:`~tenxgraph_api.cli.core.screen.AppFrame` the frame already
8
+ holds the alternate screen and keeps it, so the sequence renders in place and
9
+ collapses into the frame's pinned chrome. Without a frame the intro claims a
10
+ temporary screen of its own and hands the terminal back, then prints a durable
11
+ header — because a released alternate screen is discarded, and everything the
12
+ command goes on to print has to survive in the normal buffer.
13
+
14
+ Frames are generated from a normalized ``0.0 -> 1.0`` timeline rather than a
15
+ fixed frame list so the same choreography adapts to terminal width, refresh
16
+ rate, and the reduced-motion budget without being re-authored.
17
+ """
18
+
19
+ from __future__ import annotations
20
+
21
+ import math
22
+ import os
23
+ import platform
24
+ import sys
25
+ import time
26
+ from collections.abc import Callable, Iterator
27
+ from contextlib import contextmanager, nullcontext, suppress
28
+ from functools import lru_cache
29
+ from importlib.metadata import PackageNotFoundError
30
+ from importlib.metadata import version as package_version
31
+
32
+ from rich.align import Align
33
+ from rich.console import Console, Group, RenderableType
34
+ from rich.live import Live
35
+ from rich.text import Text
36
+
37
+ from tenxgraph_api.cli.constants import CLI_VERSION
38
+ from tenxgraph_api.cli.core.theme import (
39
+ ACCENT,
40
+ AMBER,
41
+ BACKGROUND,
42
+ BRAND_RAMP,
43
+ INK_ON_DARK,
44
+ LINE,
45
+ LINE_ON_DARK,
46
+ MUTED,
47
+ PENDING,
48
+ SURFACE_RAISED,
49
+ Glyphs,
50
+ dim_hex,
51
+ glyphs_for,
52
+ gradient_rule,
53
+ gradient_text,
54
+ sample_ramp,
55
+ wordmark,
56
+ )
57
+
58
+
59
+ INTRO_DURATION_SECONDS = 0.9
60
+ INTRO_FPS = 30
61
+ _MIN_CINEMATIC_HEIGHT = 16
62
+ # Column distance over which the reveal front and the shimmer stay lit.
63
+ _REVEAL_FRONT_WIDTH = 1.6
64
+ _SHIMMER_WIDTH = 2.5
65
+ _MIN_CINEMATIC_WIDTH = 62
66
+
67
+ # 5x5 block glyphs. Only the characters in "10XGRAPH" are needed; anything else
68
+ # falls back to the compact wordmark.
69
+ _BLOCK_FONT: dict[str, tuple[str, ...]] = {
70
+ "1": (" █ ", " ██ ", " █ ", " █ ", " ███ "),
71
+ "0": (" ███ ", "█ ██", "█ █ █", "██ █", " ███ "),
72
+ "X": ("█ █", " █ █ ", " █ ", " █ █ ", "█ █"),
73
+ "G": (" ████", "█ ", "█ ██", "█ █", " ████"),
74
+ "R": ("████ ", "█ █", "████ ", "█ █ ", "█ █"),
75
+ "A": (" ███ ", "█ █", "█████", "█ █", "█ █"),
76
+ "P": ("████ ", "█ █", "████ ", "█ ", "█ "),
77
+ "H": ("█ █", "█ █", "█████", "█ █", "█ █"),
78
+ }
79
+ _WORDMARK = "10XGRAPH"
80
+ _BLOCK_ROWS = 5
81
+
82
+ # Each command reveals its own pipeline during the intro, so the animation
83
+ # doubles as a preview of what the command is about to do.
84
+ _SIGNATURES: dict[str, tuple[str, ...]] = {
85
+ "api": ("config", "runtime", "server", "ready"),
86
+ "dev": ("config", "runtime", "server", "playground"),
87
+ "play": ("config", "runtime", "server", "playground"),
88
+ "init": ("template", "graph", "config", "project"),
89
+ "build": ("source", "deps", "image", "ship"),
90
+ "test": ("collect", "run", "assert", "report"),
91
+ "eval": ("discover", "load", "score", "report"),
92
+ "audit": ("python", "core", "config", "port"),
93
+ "skills": ("detect", "resolve", "install", "activate"),
94
+ }
95
+ _DEFAULT_SIGNATURE = ("boot", "load", "ready")
96
+
97
+ _TAGLINES: dict[str, str] = {
98
+ "api": "Serving your agent over REST and WebSocket.",
99
+ "dev": "Local agent runtime with live reload.",
100
+ "play": "Local agent runtime, wired to the playground.",
101
+ "init": "Scaffolding a production-shaped agent project.",
102
+ "build": "Packaging your agent for deployment.",
103
+ "test": "Exercising your agent's test suite.",
104
+ "eval": "Scoring your agent against evaluation sets.",
105
+ "audit": "Auditing your 10xGraph environment.",
106
+ }
107
+ _DEFAULT_TAGLINE = "Build, run, and inspect intelligent agent systems."
108
+
109
+
110
+ def render_command_intro(
111
+ console: Console,
112
+ *,
113
+ command: str,
114
+ subtitle: str | None,
115
+ unicode: bool,
116
+ persistent_screen: bool = False,
117
+ ) -> None:
118
+ """Play the command intro on the full canvas.
119
+
120
+ ``persistent_screen`` means the caller already owns an alternate screen that
121
+ it intends to keep. The sequence then plays in place and skips the durable
122
+ header, because the caller pins its own chrome once the intro finishes.
123
+ """
124
+ glyphs = glyphs_for(unicode)
125
+ if _can_play_cinematic(console):
126
+ _play_cinematic(
127
+ console,
128
+ command=command,
129
+ subtitle=subtitle,
130
+ glyphs=glyphs,
131
+ own_screen=not persistent_screen,
132
+ )
133
+ else:
134
+ _play_inline(console, command=command, glyphs=glyphs)
135
+
136
+ if persistent_screen:
137
+ return
138
+
139
+ render_session_header(
140
+ console,
141
+ command=command,
142
+ subtitle=subtitle,
143
+ glyphs=glyphs,
144
+ version=CLI_VERSION,
145
+ )
146
+
147
+
148
+ def render_session_header(
149
+ console: Console,
150
+ *,
151
+ command: str,
152
+ subtitle: str | None,
153
+ glyphs: Glyphs,
154
+ version: str | None = None,
155
+ ) -> None:
156
+ """Print the persistent branded band that identifies the running command."""
157
+ width = _usable_width(console)
158
+ console.print(gradient_rule(width, glyphs=glyphs))
159
+
160
+ # Printed into the user's own terminal, so no background band: it must read on
161
+ # light and dark themes alike.
162
+ identity = Text(" ")
163
+ identity.append(f"{glyphs.diamond} ", style="tenxgraph.brand")
164
+ identity.append_text(wordmark())
165
+ identity.append(f" {glyphs.caret} ", style="tenxgraph.muted")
166
+ identity.append(command, style="tenxgraph.command")
167
+ if version:
168
+ identity.append(" " * max(width - identity.cell_len - len(version) - 1, 1))
169
+ identity.append(version, style="tenxgraph.muted")
170
+ _pad_to_width(identity, width)
171
+ console.print(identity)
172
+
173
+ if subtitle:
174
+ caption = Text(" ")
175
+ caption.append(subtitle, style="tenxgraph.muted")
176
+ _pad_to_width(caption, width)
177
+ console.print(caption)
178
+
179
+ console.print(gradient_rule(width, glyphs=glyphs, thin=True, offset=0.35))
180
+ console.print()
181
+
182
+
183
+ def _can_play_cinematic(console: Console) -> bool:
184
+ return (
185
+ console.is_terminal
186
+ and console.height >= _MIN_CINEMATIC_HEIGHT
187
+ and console.width >= _MIN_CINEMATIC_WIDTH
188
+ )
189
+
190
+
191
+ def _play_cinematic(
192
+ console: Console,
193
+ *,
194
+ command: str,
195
+ subtitle: str | None,
196
+ glyphs: Glyphs,
197
+ own_screen: bool = True,
198
+ ) -> None:
199
+ """Run the full-canvas reveal, optionally claiming a screen of its own."""
200
+ frame_interval = 1.0 / INTRO_FPS
201
+ frame_count = max(int(INTRO_DURATION_SECONDS * INTRO_FPS), 1)
202
+ tagline = _TAGLINES.get(command.lower(), subtitle or _DEFAULT_TAGLINE)
203
+
204
+ with (
205
+ console.screen(style=f"on {BACKGROUND}", hide_cursor=True) if own_screen else nullcontext(),
206
+ Live(
207
+ console=console,
208
+ auto_refresh=False,
209
+ transient=True,
210
+ redirect_stdout=False,
211
+ redirect_stderr=False,
212
+ ) as live,
213
+ _skip_on_keypress() as skipped,
214
+ ):
215
+ started = time.monotonic()
216
+ for frame in range(frame_count + 1):
217
+ if skipped():
218
+ break
219
+ progress = frame / frame_count
220
+ live.update(
221
+ _cinematic_frame(
222
+ console,
223
+ command=command,
224
+ tagline=tagline,
225
+ glyphs=glyphs,
226
+ progress=progress,
227
+ can_skip=skipped is not _never,
228
+ ),
229
+ refresh=True,
230
+ )
231
+ # Sleep against the wall clock so a slow terminal shortens the
232
+ # sequence instead of stretching it past its motion budget.
233
+ target = started + (frame + 1) * frame_interval
234
+ remaining = target - time.monotonic()
235
+ if remaining > 0:
236
+ time.sleep(remaining)
237
+
238
+
239
+ def _play_inline(console: Console, *, command: str, glyphs: Glyphs) -> None:
240
+ """Short in-buffer reveal for short terminals and nested screens."""
241
+ frame_count = 12
242
+ with (
243
+ Live(
244
+ console=console,
245
+ auto_refresh=False,
246
+ transient=True,
247
+ redirect_stdout=False,
248
+ redirect_stderr=False,
249
+ ) as live,
250
+ _skip_on_keypress() as skipped,
251
+ ):
252
+ for frame in range(frame_count + 1):
253
+ if skipped():
254
+ break
255
+ progress = frame / frame_count
256
+ # Inline frames land on the user's own background, so ink follows the
257
+ # terminal's foreground instead of the dark-surface ink.
258
+ live.update(
259
+ Group(
260
+ Align.center(_compact_wordmark(progress, glyphs)),
261
+ Align.center(_signature_nodes(command, progress, glyphs, on_dark=False)),
262
+ ),
263
+ refresh=True,
264
+ )
265
+ time.sleep(0.04)
266
+
267
+
268
+ def _cinematic_frame(
269
+ console: Console,
270
+ *,
271
+ command: str,
272
+ tagline: str,
273
+ glyphs: Glyphs,
274
+ progress: float,
275
+ can_skip: bool = False,
276
+ ) -> RenderableType:
277
+ """Compose one frame of the intro from its independently timed layers."""
278
+ width = _usable_width(console)
279
+ reveal = _ease_out(_phase(progress, 0.05, 0.55))
280
+ shimmer = _phase(progress, 0.45, 0.9)
281
+ chrome = _phase(progress, 0.55, 0.85)
282
+ typing = _phase(progress, 0.6, 0.95)
283
+ pipeline = _phase(progress, 0.25, 1.0)
284
+
285
+ layers: list[RenderableType] = [
286
+ Align.center(_aurora(width, progress, glyphs, rows=2)),
287
+ Text(""),
288
+ ]
289
+ layers.extend(Align.center(line) for line in _block_wordmark(reveal, shimmer, glyphs))
290
+ layers.append(Text(""))
291
+
292
+ if chrome > 0:
293
+ layers.append(Align.center(_command_chip(command, chrome, glyphs)))
294
+ layers.append(Text(""))
295
+ if typing > 0:
296
+ layers.append(Align.center(_typed(tagline, typing, glyphs)))
297
+ layers.append(Text(""))
298
+ if chrome > 0:
299
+ layers.append(Align.center(_version_line(chrome, glyphs)))
300
+ layers.append(Text(""))
301
+
302
+ layers.append(Align.center(_signature_nodes(command, pipeline, glyphs)))
303
+ layers.append(Align.center(_signature_labels(command, pipeline)))
304
+ layers.append(Text(""))
305
+ layers.append(Align.center(_load_bar(progress, glyphs, width=min(width - 8, 44))))
306
+ if can_skip:
307
+ hint = f"any key to skip {glyphs.bullet} Ctrl+C to quit"
308
+ layers.append(Align.center(Text(hint, style=LINE)))
309
+
310
+ return Align.center(
311
+ Group(*layers),
312
+ vertical="middle",
313
+ height=max(console.height - 1, 12),
314
+ style=f"on {BACKGROUND}",
315
+ )
316
+
317
+
318
+ def _block_wordmark(reveal: float, shimmer: float, glyphs: Glyphs) -> list[Text]:
319
+ """Render 10XGRAPH as block letters swept in by a moving light front."""
320
+ if glyphs.block != "█":
321
+ return [_compact_wordmark(reveal, glyphs)]
322
+
323
+ columns = _wordmark_columns()
324
+ total = len(columns[0])
325
+ front = reveal * (total + 6) - 3
326
+ shimmer_front = shimmer * (total + 10) - 5
327
+
328
+ lines: list[Text] = []
329
+ for row in range(_BLOCK_ROWS):
330
+ line = Text()
331
+ for index in range(total):
332
+ character = columns[row][index]
333
+ if character == " " or index > front:
334
+ line.append(" ")
335
+ continue
336
+ distance = front - index
337
+ shimmer_distance = abs(shimmer_front - index)
338
+ # Letters settle in the logo's ink; the reveal front is the amber entry
339
+ # node and the shimmer the docs accent.
340
+ if distance < _REVEAL_FRONT_WIDTH:
341
+ line.append(character, style=f"bold {AMBER}")
342
+ elif shimmer > 0 and shimmer_distance < _SHIMMER_WIDTH:
343
+ line.append(character, style=f"bold {ACCENT}")
344
+ else:
345
+ line.append(character, style=f"bold {INK_ON_DARK}")
346
+ lines.append(line)
347
+ return lines
348
+
349
+
350
+ def _wordmark_columns() -> tuple[str, ...]:
351
+ """Lay the block font out once per row, letters separated by a column."""
352
+ rows: list[str] = []
353
+ for row in range(_BLOCK_ROWS):
354
+ rows.append(" ".join(_BLOCK_FONT[letter][row] for letter in _WORDMARK))
355
+ return tuple(rows)
356
+
357
+
358
+ def _compact_wordmark(reveal: float, glyphs: Glyphs) -> Text:
359
+ """Spaced wordmark used when block letters do not fit or render."""
360
+ visible = max(int(reveal * len(_WORDMARK)), 0)
361
+ text = Text()
362
+ text.append_text(gradient_text(" ".join(_WORDMARK[:visible]), bold=True))
363
+ if visible < len(_WORDMARK):
364
+ text.append(glyphs.cursor, style=f"bold {AMBER}")
365
+ return text
366
+
367
+
368
+ def _command_chip(command: str, intensity: float, glyphs: Glyphs) -> Text:
369
+ """Pill showing which command the intro belongs to."""
370
+ color = dim_hex(SURFACE_RAISED, 0.35 + 0.65 * intensity)
371
+ chip = Text(style=f"on {color}")
372
+ chip.append(f" {glyphs.diamond} ", style=AMBER)
373
+ chip.append(command.lower(), style=f"bold {INK_ON_DARK}")
374
+ chip.append(" ")
375
+ return chip
376
+
377
+
378
+ def _typed(value: str, progress: float, glyphs: Glyphs) -> Text:
379
+ """Type ``value`` out one character at a time with a blinking caret."""
380
+ visible = int(_ease_out(progress) * len(value))
381
+ text = Text(value[:visible], style="#c6ceda")
382
+ if visible < len(value) or int(progress * 12) % 2 == 0:
383
+ text.append(glyphs.cursor, style=AMBER)
384
+ return text
385
+
386
+
387
+ def _aurora(width: int, progress: float, glyphs: Glyphs, *, rows: int) -> Text:
388
+ """Soft moving shade field that gives the canvas depth behind the logo."""
389
+ span = min(width, 56)
390
+ # Skip the blank shade: the band should read as one flowing ribbon rather
391
+ # than a dotted line with holes punched through it.
392
+ tiers = glyphs.shades[1:]
393
+ text = Text()
394
+ for row in range(rows):
395
+ for column in range(span):
396
+ wave = math.sin((column / 7.0) + progress * 6.0 + row * 1.3)
397
+ level = int((wave + 1.0) / 2.0 * (len(tiers) - 1))
398
+ tint = dim_hex(sample_ramp(column / span), 0.30 + 0.20 * row)
399
+ text.append(tiers[level], style=tint)
400
+ if row < rows - 1:
401
+ text.append("\n")
402
+ return text
403
+
404
+
405
+ def _version_line(intensity: float, glyphs: Glyphs) -> Text:
406
+ """What is running: CLI, core and Python versions, fading in with the chrome."""
407
+ color = INK_ON_DARK if intensity >= 1 else MUTED
408
+ text = Text()
409
+ for index, (label, value) in enumerate(_runtime_versions()):
410
+ if index:
411
+ text.append(f" {glyphs.bullet} ", style=LINE_ON_DARK)
412
+ text.append(f"{label} ", style=MUTED)
413
+ text.append(value, style=f"bold {color}" if index == 0 else color)
414
+ return text
415
+
416
+
417
+ @lru_cache(maxsize=1)
418
+ def _runtime_versions() -> tuple[tuple[str, str], ...]:
419
+ """``(label, version)`` pairs for the CLI, the core framework, and Python."""
420
+ versions = [("10xgraph-api", CLI_VERSION)]
421
+ with suppress(PackageNotFoundError):
422
+ versions.append(("core", package_version("10xgraph")))
423
+ versions.append(("python", platform.python_version()))
424
+ return tuple(versions)
425
+
426
+
427
+ def _never() -> bool:
428
+ return False
429
+
430
+
431
+ @contextmanager
432
+ def _skip_on_keypress() -> Iterator[Callable[[], bool]]:
433
+ """Yield a poll that turns True once the user presses a key.
434
+
435
+ POSIX terminals only: stdin goes into cbreak mode for the length of the intro (so a
436
+ key arrives without Enter, and Ctrl+C still raises), and is restored afterwards. The
437
+ key that skips is consumed. Elsewhere the poll is always False.
438
+ """
439
+ try:
440
+ import select
441
+ import termios
442
+ import tty
443
+ except ImportError:
444
+ yield _never
445
+ return
446
+ try:
447
+ fd = sys.stdin.fileno()
448
+ if not os.isatty(fd):
449
+ raise OSError
450
+ saved = termios.tcgetattr(fd)
451
+ except (OSError, ValueError, termios.error):
452
+ yield _never
453
+ return
454
+
455
+ pressed = False
456
+
457
+ def poll() -> bool:
458
+ nonlocal pressed
459
+ if not pressed and select.select([fd], [], [], 0)[0]:
460
+ os.read(fd, 1024)
461
+ pressed = True
462
+ return pressed
463
+
464
+ try:
465
+ tty.setcbreak(fd)
466
+ yield poll
467
+ finally:
468
+ termios.tcsetattr(fd, termios.TCSADRAIN, saved)
469
+
470
+
471
+ def _signature_for(command: str) -> tuple[str, ...]:
472
+ return _SIGNATURES.get(command.lower(), _DEFAULT_SIGNATURE)
473
+
474
+
475
+ def _signature_nodes(
476
+ command: str, progress: float, glyphs: Glyphs, *, on_dark: bool = True
477
+ ) -> Text:
478
+ """Node-and-link chain that fills in as the intro advances.
479
+
480
+ Drawn like the logo's graph: the first node is the amber entry node, the others
481
+ are ink, and the links between them carry the docs accent.
482
+ """
483
+ stages = _signature_for(command)
484
+ segments = len(stages) * 2 - 1
485
+ filled = progress * segments
486
+ ink = f"bold {INK_ON_DARK}" if on_dark else "bold"
487
+ idle = LINE_ON_DARK if on_dark else PENDING
488
+ text = Text()
489
+ for index in range(segments):
490
+ active = index < filled
491
+ if index % 2 == 0:
492
+ style = (f"bold {AMBER}" if index == 0 else ink) if active else idle
493
+ text.append(glyphs.node if active else glyphs.pending, style=style)
494
+ else:
495
+ rule = glyphs.rule * 3 if active else glyphs.thin_rule * 3
496
+ text.append(rule, style=ACCENT if active else idle)
497
+ return text
498
+
499
+
500
+ def _signature_labels(command: str, progress: float) -> Text:
501
+ """Stage names under the chain, brightening in step with their node."""
502
+ stages = _signature_for(command)
503
+ reached = progress * len(stages)
504
+ text = Text()
505
+ for index, stage in enumerate(stages):
506
+ if index:
507
+ text.append(" ")
508
+ if index < reached:
509
+ text.append(stage, style=f"bold {AMBER}" if index == 0 else "#c6ceda")
510
+ else:
511
+ text.append(stage, style=LINE_ON_DARK)
512
+ return text
513
+
514
+
515
+ def _load_bar(progress: float, glyphs: Glyphs, *, width: int) -> Text:
516
+ """Hairline meter showing how much of the intro remains."""
517
+ span = max(width, 10)
518
+ filled = int(progress * span)
519
+ text = Text()
520
+ for index in range(span):
521
+ if index < filled:
522
+ text.append(glyphs.thin_rule, style=sample_ramp(index / span, BRAND_RAMP))
523
+ else:
524
+ text.append(glyphs.thin_rule, style="#222b3a")
525
+ return text
526
+
527
+
528
+ def _phase(progress: float, start: float, end: float) -> float:
529
+ """Map a global timeline position into one layer's local ``0..1`` window."""
530
+ if progress <= start:
531
+ return 0.0
532
+ if progress >= end:
533
+ return 1.0
534
+ return (progress - start) / (end - start)
535
+
536
+
537
+ def _ease_out(value: float) -> float:
538
+ """Cubic ease-out; motion decelerates instead of stopping abruptly."""
539
+ clamped = min(max(value, 0.0), 1.0)
540
+ return 1.0 - (1.0 - clamped) ** 3
541
+
542
+
543
+ def _usable_width(console: Console) -> int:
544
+ return max(min(console.width, 100) - 1, 20)
545
+
546
+
547
+ def _pad_to_width(text: Text, width: int) -> None:
548
+ padding = width - text.cell_len
549
+ if padding > 0:
550
+ text.append(" " * padding)