API reference¶
Generated from the apogee-ai-ui source with mkdocstrings. Every symbol below is exported from apogee_ai_ui, so it is part of the supported public surface.
Application · DTOs¶
dataclass
¶
dataclass
¶
dataclass
¶
Application · Use cases¶
Renders a moderately complex tree N times and reports throughput.
async
¶
Source code in apogee_ai_ui/application/use_cases/bench_render_use_case.py
Python
async def execute(self, frames: int) -> dict[str, float]:
if frames <= 0:
raise ValueError("frames must be positive")
tree = Container(children=[
Heading(text="bench"),
Markdown(source="**bold** demo " * 5),
List(items=tuple(f"item-{i}" for i in range(20))),
Table(
headers=("a", "b", "c"),
rows=tuple(("x", str(i), "y") for i in range(20)),
),
])
renderer = PlainTextRenderer()
start = time.perf_counter()
for _ in range(frames):
renderer.render(tree)
elapsed = (time.perf_counter() - start) * 1000.0
return {
"frames": float(frames),
"elapsed_ms": elapsed,
"frames_per_second": (frames / elapsed * 1000.0) if elapsed > 0 else 0.0,
}
Constructs a representative tree using all major component kinds.
async
¶
Python
execute() -> UiComponent
Source code in apogee_ai_ui/application/use_cases/build_demo_use_case.py
Python
async def execute(self) -> UiComponent:
return Container(children=[
Heading(text="apogee-ai-ui — demo", level=1),
Markdown(source="UI **declarativa** para AI agents."),
Panel(title="Resultado", children=[
Card(title="Score", body="0.87"),
ProgressBar(value=0.87, label="confidence"),
]),
List(items=["Text", "Heading", "Markdown", "Table", "Code"]),
Table(
headers=("Engine", "Status"),
rows=(("echo", "ok"), ("vllm", "lazy")),
),
Code(source='print("hi")', language="python"),
ChatMessage(role="assistant", content="Olá! Posso ajudar?"),
Spinner(label="Pensando..."),
])
async
¶
Python
execute(component: UiComponent, renderer: str = 'plain') -> str
Domain¶
dataclass
¶
Python
UiComponent(kind: ComponentKind, id: str = (lambda: f'c-{hex[:8]}')(), text: str = '', props: dict[str, str] = dict(), children: tuple['UiComponent', ...] = ())
dataclass
¶
Python
UiEvent(kind: UiEventKind, component_id: str | None = None, payload: dict[str, str] = dict(), sequence: int = 0)
class-attribute
instance-attribute
¶
dataclass
¶
Python
UiSession(id: str, events: list[UiEvent] = list(), state: dict[str, str] = dict())
dataclass
¶
Domain · Enums¶
Bases: str, Enum
Bases: str, Enum
Domain · Exceptions¶
Bases: Exception
Base for apogee-ai-ui errors.
Domain · Protocols (ports)¶
Bases: Protocol
Python
render(component: UiComponent) -> str
Infrastructure¶
Python
Card(title: str, body: str, *, id: str | None = None) -> UiComponent
Python
ChatMessage(role: str, content: str, *, id: str | None = None) -> UiComponent
Source code in apogee_ai_ui/infrastructure/components/factories.py
Python
def ChatMessage(role: str, content: str, *, id: str | None = None) -> UiComponent:
if role not in {"user", "assistant", "system", "tool"}:
raise ValueError(f"unknown chat role: {role!r}")
return UiComponent(
kind=ComponentKind.CHAT_MESSAGE, text=content,
props={"role": role},
**({"id": id} if id else {}),
)
Python
Code(source: str, *, language: str = '', id: str | None = None) -> UiComponent
Python
Container(children: Iterable[UiComponent], *, id: str | None = None) -> UiComponent
Python
Heading(text: str, *, level: int = 1, id: str | None = None) -> UiComponent
Source code in apogee_ai_ui/infrastructure/components/factories.py
Pure-stdlib HTML renderer. Output is escaped for safety.
Python
render(component: UiComponent) -> str
Serialises the component tree as JSON for transport / debugging.
Python
render(component: UiComponent) -> str
Python
List(items: Iterable[str], *, ordered: bool = False, id: str | None = None) -> UiComponent
Source code in apogee_ai_ui/infrastructure/components/factories.py
Python
def List(items: Iterable[str], *, ordered: bool = False, id: str | None = None) -> UiComponent:
children = tuple(UiComponent(kind=ComponentKind.TEXT, text=item) for item in items)
return UiComponent(
kind=ComponentKind.LIST,
props={"ordered": str(ordered).lower()},
children=children,
**({"id": id} if id else {}),
)
Python
Markdown(source: str, *, id: str | None = None) -> UiComponent
Python
Panel(title: str, children: Iterable[UiComponent], *, id: str | None = None) -> UiComponent
Python
render(component: UiComponent) -> str
Python
ProgressBar(value: float, total: float = 1.0, *, label: str = '', id: str | None = None) -> UiComponent
Source code in apogee_ai_ui/infrastructure/components/factories.py
Python
def ProgressBar(value: float, total: float = 1.0, *, label: str = "", id: str | None = None) -> UiComponent:
if total <= 0:
raise ValueError("total must be positive")
if not 0.0 <= value <= total:
raise ValueError(f"value must be in [0, {total}]")
return UiComponent(
kind=ComponentKind.PROGRESS, text=label,
props={"value": str(value), "total": str(total)},
**({"id": id} if id else {}),
)
Python
Spinner(label: str = '', *, id: str | None = None) -> UiComponent
Python
Table(headers: tuple[str, ...], rows: tuple[tuple[str, ...], ...], *, id: str | None = None) -> UiComponent
Source code in apogee_ai_ui/infrastructure/components/factories.py
Python
def Table(headers: tuple[str, ...], rows: tuple[tuple[str, ...], ...], *, id: str | None = None) -> UiComponent:
if not headers:
raise ValueError("headers cannot be empty")
if any(len(r) != len(headers) for r in rows):
raise ValueError("all rows must match headers length")
children = (
UiComponent(
kind=ComponentKind.TEXT,
text="\t".join(headers),
props={"role": "header"},
),
*(
UiComponent(
kind=ComponentKind.TEXT,
text="\t".join(row),
props={"role": "row"},
)
for row in rows
),
)
return UiComponent(
kind=ComponentKind.TABLE,
children=children,
**({"id": id} if id else {}),
)
Adds ANSI styling on top of the plain layout.
Python
render(component: UiComponent) -> str
Python
Text(text: str, *, id: str | None = None) -> UiComponent