spriteforge 0.1.1__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.
- spriteforge/__init__.py +1 -0
- spriteforge/__main__.py +3 -0
- spriteforge/agents/__init__.py +0 -0
- spriteforge/agents/assets.py +109 -0
- spriteforge/agents/cancellation.py +12 -0
- spriteforge/agents/director.py +50 -0
- spriteforge/agents/models.py +63 -0
- spriteforge/agents/roles/art-director.md +15 -0
- spriteforge/agents/roles/art-reviewer.md +14 -0
- spriteforge/agents/roles/director.md +14 -0
- spriteforge/agents/roles/game-designer.md +15 -0
- spriteforge/agents/roles/level-tile-designer.md +16 -0
- spriteforge/agents/roles/librarian.md +13 -0
- spriteforge/agents/roles/menu-designer.md +15 -0
- spriteforge/agents/roles/pixel-artist.md +14 -0
- spriteforge/agents/roles/programmer.md +14 -0
- spriteforge/agents/roles/qa-playtester.md +13 -0
- spriteforge/agents/roles/sound-director.md +14 -0
- spriteforge/agents/roles.py +39 -0
- spriteforge/agents/router.py +233 -0
- spriteforge/agents/router_eval.py +145 -0
- spriteforge/agents/routing_state.py +133 -0
- spriteforge/agents/runtime.py +430 -0
- spriteforge/agents/workflow.py +389 -0
- spriteforge/app/__init__.py +0 -0
- spriteforge/app/agents_view.py +248 -0
- spriteforge/app/chat.py +114 -0
- spriteforge/app/extensions.py +115 -0
- spriteforge/app/index.html +279 -0
- spriteforge/app/local_only.py +49 -0
- spriteforge/app/server.py +358 -0
- spriteforge/app/static/assets/index-L2s1wlcp.css +1 -0
- spriteforge/app/static/assets/index-aBfzgLQl.js +71 -0
- spriteforge/app/static/assets/press-start-2p-latin-400-normal-BKfmdmKK.woff +0 -0
- spriteforge/app/static/assets/press-start-2p-latin-400-normal-xj9lRvVs.woff2 +0 -0
- spriteforge/app/static/index.html +13 -0
- spriteforge/app/static/press-start-2p-LICENSE.txt +93 -0
- spriteforge/app/studio.py +278 -0
- spriteforge/app/workers.py +73 -0
- spriteforge/cli.py +241 -0
- spriteforge/config.py +193 -0
- spriteforge/config.yaml +157 -0
- spriteforge/core/__init__.py +0 -0
- spriteforge/core/acting.py +16 -0
- spriteforge/core/cost.py +236 -0
- spriteforge/core/credentials.py +24 -0
- spriteforge/core/demo.py +79 -0
- spriteforge/core/forms.py +20 -0
- spriteforge/core/gates.py +175 -0
- spriteforge/core/security.py +42 -0
- spriteforge/core/state.py +222 -0
- spriteforge/core/team.py +15 -0
- spriteforge/core/usage.py +68 -0
- spriteforge/game/__init__.py +0 -0
- spriteforge/game/actors.py +377 -0
- spriteforge/game/agent_tools.py +178 -0
- spriteforge/game/art.py +2097 -0
- spriteforge/game/art_checks.py +190 -0
- spriteforge/game/art_review.py +518 -0
- spriteforge/game/build.py +134 -0
- spriteforge/game/bundle.py +1178 -0
- spriteforge/game/cli.py +119 -0
- spriteforge/game/codegen.py +433 -0
- spriteforge/game/codeinfo.py +154 -0
- spriteforge/game/dbsource.py +137 -0
- spriteforge/game/design.py +342 -0
- spriteforge/game/export.py +62 -0
- spriteforge/game/gamedb.py +191 -0
- spriteforge/game/image_cache.py +61 -0
- spriteforge/game/lessons.py +259 -0
- spriteforge/game/level_gen.py +118 -0
- spriteforge/game/level_preview.py +97 -0
- spriteforge/game/levels.py +934 -0
- spriteforge/game/loops.py +38 -0
- spriteforge/game/menus.py +712 -0
- spriteforge/game/mock_game.js +109 -0
- spriteforge/game/mock_platformer.js +58 -0
- spriteforge/game/motion.py +881 -0
- spriteforge/game/pipeline.py +1768 -0
- spriteforge/game/plan.py +502 -0
- spriteforge/game/playtest.py +318 -0
- spriteforge/game/qa.py +664 -0
- spriteforge/game/qa_checks.py +223 -0
- spriteforge/game/qa_runtime.py +565 -0
- spriteforge/game/reach.py +807 -0
- spriteforge/game/record.py +138 -0
- spriteforge/game/research.py +262 -0
- spriteforge/game/revision.py +225 -0
- spriteforge/game/sdk/API.md +104 -0
- spriteforge/game/sdk/FLOW.md +19 -0
- spriteforge/game/sdk/LEVELS.md +65 -0
- spriteforge/game/sdk/sf.js +418 -0
- spriteforge/game/sdk/sfflow.js +442 -0
- spriteforge/game/sdk/sflevel.js +683 -0
- spriteforge/game/sdk/sfsound-editor.js +225 -0
- spriteforge/game/sdk/sfsound.js +260 -0
- spriteforge/game/sdk/sounds.html +67 -0
- spriteforge/game/sounds.py +793 -0
- spriteforge/game/story.py +188 -0
- spriteforge/game/structure.py +98 -0
- spriteforge/game/team_reports.py +394 -0
- spriteforge/game/tilesets.py +70 -0
- spriteforge/game/title_art.py +186 -0
- spriteforge/genres/__init__.py +0 -0
- spriteforge/library/__init__.py +15 -0
- spriteforge/library/cli.py +126 -0
- spriteforge/library/describe.py +242 -0
- spriteforge/library/looks.py +154 -0
- spriteforge/library/models.py +79 -0
- spriteforge/library/store.py +422 -0
- spriteforge/library/tilesets/README.md +32 -0
- spriteforge/library/tilesets/gandalf-seasons.json +111 -0
- spriteforge/library/tilesets/pixel-crawler-dungeon.json +66 -0
- spriteforge/mcp/__init__.py +0 -0
- spriteforge/mcp/cli.py +58 -0
- spriteforge/mcp/client.py +57 -0
- spriteforge/mcp/filesystem_read.py +32 -0
- spriteforge/mcp/gamedb.py +56 -0
- spriteforge/mcp/library.py +179 -0
- spriteforge/mcp/memory.py +37 -0
- spriteforge/mcp/pixel_tools.py +145 -0
- spriteforge/mcp/registry.py +145 -0
- spriteforge/mcp/service.py +224 -0
- spriteforge/mcp/templates/context7.json +6 -0
- spriteforge/mcp/templates/fetch.json +6 -0
- spriteforge/mcp/templates/filesystem-read.json +6 -0
- spriteforge/mcp/templates/pixel-tools.json +6 -0
- spriteforge/memory/README.md +10 -0
- spriteforge/memory/__init__.py +0 -0
- spriteforge/memory/cli.py +131 -0
- spriteforge/memory/okf/__init__.py +1 -0
- spriteforge/memory/okf/catalog.py +331 -0
- spriteforge/memory/okf/codec.py +63 -0
- spriteforge/memory/okf/git.py +104 -0
- spriteforge/memory/okf/indexes.py +50 -0
- spriteforge/memory/okf/models.py +114 -0
- spriteforge/memory/okf/search.py +53 -0
- spriteforge/memory/okf/seed.py +81 -0
- spriteforge/memory/okf/seeds/genres.yaml +121 -0
- spriteforge/memory/okf/seeds/other.yaml +150 -0
- spriteforge/memory/okf/store.py +402 -0
- spriteforge/memory/okf/validate.py +115 -0
- spriteforge/pixel/__init__.py +17 -0
- spriteforge/pixel/atlas.py +110 -0
- spriteforge/pixel/grid.py +174 -0
- spriteforge/pixel/palette.py +156 -0
- spriteforge/pixel/palettes/dungeon.json +9 -0
- spriteforge/pixel/postprocess.py +170 -0
- spriteforge/pixel/preview.py +40 -0
- spriteforge/pixel/schemas.py +139 -0
- spriteforge/pixel/source.py +237 -0
- spriteforge/pixel/terrain.py +48 -0
- spriteforge/pixel/validate.py +138 -0
- spriteforge/prompts/anim_frame.txt +1 -0
- spriteforge/prompts/character.txt +1 -0
- spriteforge/prompts/item.txt +1 -0
- spriteforge/prompts/tile.txt +1 -0
- spriteforge/prompts/ui.txt +1 -0
- spriteforge/providers/__init__.py +0 -0
- spriteforge/providers/base.py +97 -0
- spriteforge/providers/http.py +38 -0
- spriteforge/providers/mock.py +111 -0
- spriteforge/providers/muse_image.py +60 -0
- spriteforge/providers/muse_search.py +91 -0
- spriteforge/providers/muse_spark.py +66 -0
- spriteforge/skills/__init__.py +0 -0
- spriteforge/skills/builtin/LICENSE-awesome-gamedev-agent-skills.txt +201 -0
- spriteforge/skills/builtin/NOTICE-awesome-gamedev-agent-skills.txt +15 -0
- spriteforge/skills/builtin/THIRD_PARTY.md +21 -0
- spriteforge/skills/builtin/audio-design/SKILL.md +190 -0
- spriteforge/skills/builtin/game-feel/SKILL.md +174 -0
- spriteforge/skills/builtin/game-ui-ux/SKILL.md +167 -0
- spriteforge/skills/builtin/level-design/SKILL.md +169 -0
- spriteforge/skills/builtin/phaser-arcade-physics/SKILL.md +17 -0
- spriteforge/skills/builtin/physics-tuning/SKILL.md +164 -0
- spriteforge/skills/builtin/pixel-art-prompting/SKILL.md +12 -0
- spriteforge/skills/builtin/platformer/SKILL.md +153 -0
- spriteforge/skills/builtin/puzzle/SKILL.md +143 -0
- spriteforge/skills/builtin/sprite-animation-frames/SKILL.md +11 -0
- spriteforge/skills/builtin/tileset-design/SKILL.md +10 -0
- spriteforge/skills/catalog.py +200 -0
- spriteforge/skills/cli.py +41 -0
- spriteforge/stages/__init__.py +0 -0
- spriteforge/stages/asset_context.py +301 -0
- spriteforge/stages/asset_models.py +192 -0
- spriteforge/stages/asset_render.py +366 -0
- spriteforge/stages/asset_review.py +140 -0
- spriteforge/stages/asset_store.py +94 -0
- spriteforge/stages/chat_changes.py +236 -0
- spriteforge/stages/concept.py +42 -0
- spriteforge/stages/game.py +1699 -0
- spriteforge/stages/game_confirm.py +112 -0
- spriteforge/stages/game_final.py +220 -0
- spriteforge/stages/game_record.py +246 -0
- spriteforge/stages/gameplay.py +218 -0
- spriteforge/stages/intake.py +372 -0
- spriteforge/stages/preview_assets.py +212 -0
- spriteforge/stages/preview_models.py +167 -0
- spriteforge/stages/preview_render.py +169 -0
- spriteforge/stages/preview_repair.py +61 -0
- spriteforge/stages/preview_review.py +169 -0
- spriteforge/stages/production.py +170 -0
- spriteforge/stages/references.py +105 -0
- spriteforge/stages/rewind.py +128 -0
- spriteforge/stages/workflow.py +440 -0
- spriteforge/templates/phaser/audit.js +45 -0
- spriteforge/templates/phaser/font.png +0 -0
- spriteforge/templates/phaser/font.xml +1 -0
- spriteforge/templates/phaser/preview.html +9 -0
- spriteforge/templates/phaser/room.js +49 -0
- spriteforge/templates/phaser/vendor/LICENSE.md +20 -0
- spriteforge/templates/phaser/vendor/phaser.min.js +1 -0
- spriteforge-0.1.1.dist-info/METADATA +364 -0
- spriteforge-0.1.1.dist-info/RECORD +218 -0
- spriteforge-0.1.1.dist-info/WHEEL +5 -0
- spriteforge-0.1.1.dist-info/entry_points.txt +2 -0
- spriteforge-0.1.1.dist-info/licenses/LICENSE +27 -0
- spriteforge-0.1.1.dist-info/top_level.txt +1 -0
|
@@ -0,0 +1,139 @@
|
|
|
1
|
+
"""Pixel contracts shared by processing, checks, and saved palettes."""
|
|
2
|
+
|
|
3
|
+
from typing import Annotated, Literal
|
|
4
|
+
|
|
5
|
+
from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
|
|
6
|
+
|
|
7
|
+
Dimension = Annotated[int, Field(ge=1, le=4096)]
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
def hex_color(value: str) -> str:
|
|
11
|
+
if (
|
|
12
|
+
len(value) != 7
|
|
13
|
+
or not value.startswith("#")
|
|
14
|
+
or any(c not in "0123456789abcdefABCDEF" for c in value[1:])
|
|
15
|
+
):
|
|
16
|
+
raise ValueError("Colors must use #RRGGBB")
|
|
17
|
+
return value.upper()
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
class Schema(BaseModel):
|
|
21
|
+
model_config = ConfigDict(extra="forbid")
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
class Palette(Schema):
|
|
25
|
+
name: str = "custom"
|
|
26
|
+
colors: list[str] = Field(min_length=1, max_length=256)
|
|
27
|
+
|
|
28
|
+
@field_validator("colors")
|
|
29
|
+
@classmethod
|
|
30
|
+
def normalize(cls, colors):
|
|
31
|
+
return list(dict.fromkeys(hex_color(c) for c in colors))
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
class Style(Schema):
|
|
35
|
+
palette: list[str] = Field(min_length=1, max_length=256)
|
|
36
|
+
background: str = "#FF00FF"
|
|
37
|
+
chroma_tolerance: float = Field(default=45, ge=0, le=442)
|
|
38
|
+
alpha_threshold: int = Field(default=128, ge=1, le=255)
|
|
39
|
+
min_cluster_size: int = Field(default=2, ge=0)
|
|
40
|
+
outline: bool = False
|
|
41
|
+
outline_color: str | None = None
|
|
42
|
+
max_colors: int = Field(default=16, ge=1, le=256)
|
|
43
|
+
character_canvas: tuple[Dimension, Dimension] = (48, 48)
|
|
44
|
+
character_logical_limit: tuple[Dimension, Dimension] = (40, 40)
|
|
45
|
+
tile_canvas: tuple[Dimension, Dimension] = (16, 16)
|
|
46
|
+
outline_dark_lightness: float = Field(default=35, ge=0, le=100)
|
|
47
|
+
outline_dark_tolerance: float = Field(default=12, ge=0)
|
|
48
|
+
|
|
49
|
+
@field_validator("palette")
|
|
50
|
+
@classmethod
|
|
51
|
+
def normalize(cls, colors):
|
|
52
|
+
return list(dict.fromkeys(hex_color(c) for c in colors))
|
|
53
|
+
|
|
54
|
+
@field_validator("background", "outline_color")
|
|
55
|
+
@classmethod
|
|
56
|
+
def normalize_color(cls, color):
|
|
57
|
+
return hex_color(color) if color is not None else None
|
|
58
|
+
|
|
59
|
+
@model_validator(mode="after")
|
|
60
|
+
def outline_is_in_palette(self):
|
|
61
|
+
if self.outline_color and self.outline_color not in self.palette:
|
|
62
|
+
raise ValueError("outline_color must belong to the palette")
|
|
63
|
+
return self
|
|
64
|
+
|
|
65
|
+
|
|
66
|
+
class AssetSpec(Schema):
|
|
67
|
+
id: str = "sprite"
|
|
68
|
+
type: Literal["sprite", "character", "tile", "item", "ui"] = "sprite"
|
|
69
|
+
size: tuple[Dimension, Dimension] = (32, 32)
|
|
70
|
+
padding: int | None = Field(default=None, ge=0)
|
|
71
|
+
allow_edge_touch: bool | None = None
|
|
72
|
+
max_colors: int | None = Field(default=None, ge=1, le=256)
|
|
73
|
+
min_fill_ratio: float = Field(default=0.05, ge=0, le=1)
|
|
74
|
+
seam_threshold: float = Field(default=0.05, ge=0, le=1)
|
|
75
|
+
|
|
76
|
+
@model_validator(mode="before")
|
|
77
|
+
@classmethod
|
|
78
|
+
def canvas_defaults(cls, values):
|
|
79
|
+
if isinstance(values, dict) and "size" not in values:
|
|
80
|
+
if values.get("type") == "character":
|
|
81
|
+
return {**values, "size": (48, 48)}
|
|
82
|
+
if values.get("type") == "tile":
|
|
83
|
+
return {**values, "size": (16, 16)}
|
|
84
|
+
return values
|
|
85
|
+
|
|
86
|
+
@property
|
|
87
|
+
def margin(self) -> int:
|
|
88
|
+
return self.padding if self.padding is not None else (0 if self.type == "tile" else 1)
|
|
89
|
+
|
|
90
|
+
@property
|
|
91
|
+
def edges_allowed(self) -> bool:
|
|
92
|
+
return self.allow_edge_touch if self.allow_edge_touch is not None else self.type == "tile"
|
|
93
|
+
|
|
94
|
+
@model_validator(mode="after")
|
|
95
|
+
def usable_canvas(self):
|
|
96
|
+
if min(self.size) <= 2 * self.margin:
|
|
97
|
+
raise ValueError("padding leaves no usable canvas")
|
|
98
|
+
return self
|
|
99
|
+
|
|
100
|
+
|
|
101
|
+
class Failure(Schema):
|
|
102
|
+
code: str
|
|
103
|
+
message: str
|
|
104
|
+
fix_hint: str
|
|
105
|
+
|
|
106
|
+
|
|
107
|
+
class ProcessingOptions(Schema):
|
|
108
|
+
"""Real-output cleanup; omitted options preserve the original low-level API behavior."""
|
|
109
|
+
|
|
110
|
+
background_tolerance: float = Field(default=18, ge=0, le=200)
|
|
111
|
+
despill_tolerance: float = Field(default=45, ge=0, le=200)
|
|
112
|
+
keep_detached: bool = False
|
|
113
|
+
detached_min_area_ratio: float = Field(default=0.02, ge=0, le=1)
|
|
114
|
+
detect_grid: bool = True
|
|
115
|
+
scale_mode: Literal["auto", "native", "fit"] = "auto"
|
|
116
|
+
baseline: Literal["bottom", "center"] = "center"
|
|
117
|
+
native_grid_confidence: float = Field(default=0.35, ge=0, le=1)
|
|
118
|
+
|
|
119
|
+
|
|
120
|
+
class DroppedComponent(Schema):
|
|
121
|
+
area: int
|
|
122
|
+
bbox: tuple[int, int, int, int]
|
|
123
|
+
area_ratio: float
|
|
124
|
+
|
|
125
|
+
|
|
126
|
+
class ProcessingReport(Schema):
|
|
127
|
+
background: str | None = None
|
|
128
|
+
dropped: list[DroppedComponent] = Field(default_factory=list)
|
|
129
|
+
grid_size: int | None = None
|
|
130
|
+
grid_offset: tuple[int, int] = (0, 0)
|
|
131
|
+
despilled_pixels: int = 0
|
|
132
|
+
grid_confidence: float = 0
|
|
133
|
+
logical_subject_size: tuple[int, int] | None = None
|
|
134
|
+
scale_mode: str = "fit"
|
|
135
|
+
scale_factor: float | None = None
|
|
136
|
+
palette_size: int = 0
|
|
137
|
+
palette_usage: dict[str, int] = Field(default_factory=dict)
|
|
138
|
+
tinted_dark_colors: list[str] = Field(default_factory=list)
|
|
139
|
+
warnings: list[str] = Field(default_factory=list)
|
|
@@ -0,0 +1,237 @@
|
|
|
1
|
+
"""Source-image cleanup before final pixel sizing. No provider dependencies."""
|
|
2
|
+
|
|
3
|
+
import numpy as np
|
|
4
|
+
from PIL import Image
|
|
5
|
+
|
|
6
|
+
from .palette import rgb_to_lab
|
|
7
|
+
from .schemas import DroppedComponent, ProcessingOptions, ProcessingReport
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
def components(
|
|
11
|
+
mask: np.ndarray,
|
|
12
|
+
) -> tuple[np.ndarray, list[tuple[int, int, tuple[int, int, int, int]]]]:
|
|
13
|
+
"""4-connected components using scanline runs (avoids per-source-pixel Python objects)."""
|
|
14
|
+
labels = np.zeros(mask.shape, dtype=np.int32)
|
|
15
|
+
parents = [0]
|
|
16
|
+
records = []
|
|
17
|
+
previous = []
|
|
18
|
+
|
|
19
|
+
def root(i):
|
|
20
|
+
while parents[i] != i:
|
|
21
|
+
parents[i] = parents[parents[i]]
|
|
22
|
+
i = parents[i]
|
|
23
|
+
return i
|
|
24
|
+
|
|
25
|
+
for y, row in enumerate(mask):
|
|
26
|
+
changes = np.diff(np.pad(row.astype(np.int8), 1))
|
|
27
|
+
starts, ends = np.flatnonzero(changes == 1), np.flatnonzero(changes == -1)
|
|
28
|
+
current = []
|
|
29
|
+
before = 0
|
|
30
|
+
for left, right in zip(starts, ends, strict=True):
|
|
31
|
+
label = len(parents)
|
|
32
|
+
parents.append(label)
|
|
33
|
+
while before < len(previous) and previous[before][1] <= left:
|
|
34
|
+
before += 1
|
|
35
|
+
j = before
|
|
36
|
+
while j < len(previous) and previous[j][0] < right:
|
|
37
|
+
a, b = root(label), root(previous[j][2])
|
|
38
|
+
parents[max(a, b)] = min(a, b)
|
|
39
|
+
j += 1
|
|
40
|
+
labels[y, left:right] = label
|
|
41
|
+
current.append((int(left), int(right), label))
|
|
42
|
+
records.append((label, y, int(left), int(right)))
|
|
43
|
+
previous = current
|
|
44
|
+
lookup = np.array([root(i) for i in range(len(parents))], dtype=np.int32)
|
|
45
|
+
labels = lookup[labels]
|
|
46
|
+
groups = {}
|
|
47
|
+
for label, y, left, right in records:
|
|
48
|
+
ident = int(lookup[label])
|
|
49
|
+
if ident not in groups:
|
|
50
|
+
groups[ident] = [0, left, y, right, y + 1]
|
|
51
|
+
group = groups[ident]
|
|
52
|
+
group[0] += right - left
|
|
53
|
+
group[1:] = [
|
|
54
|
+
min(group[1], left),
|
|
55
|
+
min(group[2], y),
|
|
56
|
+
max(group[3], right),
|
|
57
|
+
max(group[4], y + 1),
|
|
58
|
+
]
|
|
59
|
+
return labels, sorted(
|
|
60
|
+
[(ident, data[0], tuple(data[1:])) for ident, data in groups.items()],
|
|
61
|
+
key=lambda c: (-c[1], c[0]),
|
|
62
|
+
)
|
|
63
|
+
|
|
64
|
+
|
|
65
|
+
def estimate_background(image: Image.Image) -> np.ndarray | None:
|
|
66
|
+
rgba = np.asarray(image.convert("RGBA"))
|
|
67
|
+
band = max(1, min(image.size) // 100)
|
|
68
|
+
border = np.concatenate(
|
|
69
|
+
[
|
|
70
|
+
rgba[:band].reshape(-1, 4),
|
|
71
|
+
rgba[-band:].reshape(-1, 4),
|
|
72
|
+
rgba[:, :band].reshape(-1, 4),
|
|
73
|
+
rgba[:, -band:].reshape(-1, 4),
|
|
74
|
+
]
|
|
75
|
+
)
|
|
76
|
+
# An already transparent border is not a chroma background.
|
|
77
|
+
if np.count_nonzero(border[:, 3] > 0) < len(border) // 2:
|
|
78
|
+
return None
|
|
79
|
+
return np.median(border[border[:, 3] > 0, :3], axis=0).round().astype(np.uint8)
|
|
80
|
+
|
|
81
|
+
|
|
82
|
+
def key_background(
|
|
83
|
+
raw: Image.Image, options: ProcessingOptions, report: ProcessingReport
|
|
84
|
+
) -> Image.Image:
|
|
85
|
+
pixels = np.array(raw.convert("RGBA"))
|
|
86
|
+
background = estimate_background(raw)
|
|
87
|
+
if background is None:
|
|
88
|
+
return Image.fromarray(pixels)
|
|
89
|
+
report.background = "#" + "".join(f"{v:02X}" for v in background)
|
|
90
|
+
reference = rgb_to_lab(background)
|
|
91
|
+
distances = np.empty(pixels.shape[:2], dtype=np.float32)
|
|
92
|
+
for y in range(0, len(pixels), 128):
|
|
93
|
+
distances[y : y + 128] = np.linalg.norm(
|
|
94
|
+
rgb_to_lab(pixels[y : y + 128, :, :3]) - reference, axis=-1
|
|
95
|
+
)
|
|
96
|
+
pixels[distances <= options.background_tolerance, 3] = 0
|
|
97
|
+
# Decontaminate only background-like pixels adjoining removed background. Iterate
|
|
98
|
+
# a narrow band so a genuine purple accent inside the subject is never globally erased.
|
|
99
|
+
for _ in range(3):
|
|
100
|
+
transparent = pixels[..., 3] == 0
|
|
101
|
+
p = np.pad(transparent, 1, constant_values=True)
|
|
102
|
+
edge = p[:-2, 1:-1] | p[2:, 1:-1] | p[1:-1, :-2] | p[1:-1, 2:]
|
|
103
|
+
spill = edge & ~transparent & (distances <= options.despill_tolerance)
|
|
104
|
+
report.despilled_pixels += int(spill.sum())
|
|
105
|
+
pixels[spill, 3] = 0
|
|
106
|
+
pixels[pixels[..., 3] == 0] = 0
|
|
107
|
+
return Image.fromarray(pixels)
|
|
108
|
+
|
|
109
|
+
|
|
110
|
+
def isolate_subject(
|
|
111
|
+
image: Image.Image, options: ProcessingOptions, report: ProcessingReport
|
|
112
|
+
) -> Image.Image:
|
|
113
|
+
pixels = np.array(image.convert("RGBA"))
|
|
114
|
+
labels, groups = components(pixels[..., 3] > 0)
|
|
115
|
+
if not groups:
|
|
116
|
+
return image.copy()
|
|
117
|
+
largest = groups[0][1]
|
|
118
|
+
keep = [groups[0][0]]
|
|
119
|
+
for ident, area, bbox in groups[1:]:
|
|
120
|
+
ratio = area / largest
|
|
121
|
+
if options.keep_detached and ratio >= options.detached_min_area_ratio:
|
|
122
|
+
keep.append(ident)
|
|
123
|
+
else:
|
|
124
|
+
report.dropped.append(DroppedComponent(area=area, bbox=bbox, area_ratio=ratio))
|
|
125
|
+
pixels[~np.isin(labels, keep)] = 0
|
|
126
|
+
return Image.fromarray(pixels)
|
|
127
|
+
|
|
128
|
+
|
|
129
|
+
def mode_resize(image: Image.Image, size: tuple[int, int]) -> Image.Image:
|
|
130
|
+
"""Area-footprint mode, with transparent coverage voting and deterministic RGB ties.
|
|
131
|
+
|
|
132
|
+
Upscaling is nearest-neighbor. Shrinking chooses a source color, never an average.
|
|
133
|
+
"""
|
|
134
|
+
rgba = np.asarray(image.convert("RGBA"))
|
|
135
|
+
width, height = size
|
|
136
|
+
if width >= image.width and height >= image.height:
|
|
137
|
+
return image.resize(size, Image.Resampling.NEAREST)
|
|
138
|
+
output = np.zeros((height, width, 4), dtype=np.uint8)
|
|
139
|
+
for y in range(height):
|
|
140
|
+
top, bottom = (
|
|
141
|
+
y * image.height // height,
|
|
142
|
+
max(y * image.height // height + 1, (y + 1) * image.height // height),
|
|
143
|
+
)
|
|
144
|
+
for x in range(width):
|
|
145
|
+
left, right = (
|
|
146
|
+
x * image.width // width,
|
|
147
|
+
max(x * image.width // width + 1, (x + 1) * image.width // width),
|
|
148
|
+
)
|
|
149
|
+
block = rgba[top:bottom, left:right].reshape(-1, 4)
|
|
150
|
+
visible = block[block[:, 3] > 0]
|
|
151
|
+
if len(visible) * 2 < len(block) or not len(visible):
|
|
152
|
+
continue
|
|
153
|
+
colors, counts = np.unique(visible, axis=0, return_counts=True)
|
|
154
|
+
output[y, x] = colors[counts.argmax()]
|
|
155
|
+
return Image.fromarray(output)
|
|
156
|
+
|
|
157
|
+
|
|
158
|
+
def detect_grid(
|
|
159
|
+
image: Image.Image, report: ProcessingReport | None = None
|
|
160
|
+
) -> tuple[int | None, tuple[int, int]]:
|
|
161
|
+
"""Estimate repeated horizontal/vertical color-run lengths, ignoring low-level texture."""
|
|
162
|
+
rgba = np.asarray(image.convert("RGBA"))
|
|
163
|
+
rgb = rgba[..., :3].astype(np.int16)
|
|
164
|
+
candidates = []
|
|
165
|
+
positions_by_axis = []
|
|
166
|
+
confidence = []
|
|
167
|
+
for axis in (1, 0):
|
|
168
|
+
delta = np.linalg.norm(np.diff(rgb, axis=axis), axis=-1)
|
|
169
|
+
alpha = rgba[..., 3] > 0
|
|
170
|
+
valid = (alpha[:, 1:] & alpha[:, :-1]) if axis == 1 else (alpha[1:] & alpha[:-1])
|
|
171
|
+
edges = (delta >= 30) & valid
|
|
172
|
+
lines = edges if axis == 1 else edges.T
|
|
173
|
+
gaps, positions = [], []
|
|
174
|
+
# Sample bounded, evenly-spaced scanlines through the source.
|
|
175
|
+
for row in lines[np.linspace(0, len(lines) - 1, min(128, len(lines)), dtype=int)]:
|
|
176
|
+
found = np.flatnonzero(row)
|
|
177
|
+
if len(found):
|
|
178
|
+
found = found[np.r_[True, np.diff(found) > 1]] + 1
|
|
179
|
+
positions.extend(found.tolist())
|
|
180
|
+
gaps.extend(np.diff(found).tolist())
|
|
181
|
+
gaps = np.array(gaps)
|
|
182
|
+
useful = gaps[(gaps >= 2) & (gaps <= 64)]
|
|
183
|
+
if len(useful) < 12:
|
|
184
|
+
return None, (0, 0)
|
|
185
|
+
histogram = np.bincount(useful, minlength=66)
|
|
186
|
+
scores = histogram[2:65] + 0.4 * (histogram[1:64] + histogram[3:66])
|
|
187
|
+
block = int(scores.argmax() + 2)
|
|
188
|
+
nearby = useful[np.abs(useful - block) <= 1]
|
|
189
|
+
block = int(np.median(nearby).round())
|
|
190
|
+
# A grid needs a repeated fundamental, not just one long rectangle edge.
|
|
191
|
+
if len(nearby) < 8 or len(nearby) / len(useful) < 0.2:
|
|
192
|
+
return None, (0, 0)
|
|
193
|
+
candidates.append(block)
|
|
194
|
+
confidence.append(len(nearby) / len(useful))
|
|
195
|
+
positions_by_axis.append(positions)
|
|
196
|
+
if abs(candidates[0] - candidates[1]) > 1:
|
|
197
|
+
return None, (0, 0)
|
|
198
|
+
block = round(sum(candidates) / 2)
|
|
199
|
+
if report is not None:
|
|
200
|
+
report.grid_confidence = min(confidence)
|
|
201
|
+
offsets = tuple(
|
|
202
|
+
int(np.bincount(np.array(p) % block, minlength=block).argmax()) for p in positions_by_axis
|
|
203
|
+
)
|
|
204
|
+
return block, offsets
|
|
205
|
+
|
|
206
|
+
|
|
207
|
+
def snap_grid(image: Image.Image, block: int, offset: tuple[int, int]) -> Image.Image:
|
|
208
|
+
"""Pad to the detected lattice, then take the mode in each source grid cell."""
|
|
209
|
+
x, y = offset
|
|
210
|
+
left, top = (-x) % block, (-y) % block
|
|
211
|
+
width = (image.width + left + block - 1) // block
|
|
212
|
+
height = (image.height + top + block - 1) // block
|
|
213
|
+
canvas = Image.new("RGBA", (width * block, height * block))
|
|
214
|
+
canvas.paste(image, (left, top))
|
|
215
|
+
return mode_resize(canvas, (width, height))
|
|
216
|
+
|
|
217
|
+
|
|
218
|
+
def prepare_source(
|
|
219
|
+
raw: Image.Image, options: ProcessingOptions, report: ProcessingReport
|
|
220
|
+
) -> Image.Image:
|
|
221
|
+
image = isolate_subject(key_background(raw, options, report), options, report)
|
|
222
|
+
bbox = image.getbbox()
|
|
223
|
+
if bbox:
|
|
224
|
+
image = image.crop(bbox)
|
|
225
|
+
if options.detect_grid and bbox:
|
|
226
|
+
report.grid_size, report.grid_offset = detect_grid(image, report)
|
|
227
|
+
if report.grid_size and report.grid_confidence >= options.native_grid_confidence:
|
|
228
|
+
image = snap_grid(image, report.grid_size, report.grid_offset)
|
|
229
|
+
logical_bbox = image.getbbox()
|
|
230
|
+
if logical_bbox:
|
|
231
|
+
image = image.crop(logical_bbox)
|
|
232
|
+
report.logical_subject_size = image.size
|
|
233
|
+
elif report.grid_size:
|
|
234
|
+
report.warnings.append(
|
|
235
|
+
f"Source grid confidence {report.grid_confidence:.2f} is too low; using unsnapped fit."
|
|
236
|
+
)
|
|
237
|
+
return image
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
"""Deterministic seam cleanup and measured terrain/actor visual hierarchy."""
|
|
2
|
+
|
|
3
|
+
import numpy as np
|
|
4
|
+
from PIL import Image
|
|
5
|
+
from pydantic import BaseModel
|
|
6
|
+
|
|
7
|
+
from .palette import quantize
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
class VisualWeight(BaseModel):
|
|
11
|
+
local_contrast: float
|
|
12
|
+
distinct_colors: int
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
def visual_weight(image):
|
|
16
|
+
rgba = np.asarray(image.convert("RGBA"))
|
|
17
|
+
visible = rgba[..., 3] > 0
|
|
18
|
+
luminance = rgba[..., :3] @ np.array([0.2126, 0.7152, 0.0722]) / 255
|
|
19
|
+
deltas = []
|
|
20
|
+
for axis in (0, 1):
|
|
21
|
+
pairs = np.take(visible, range(visible.shape[axis] - 1), axis=axis) & np.take(
|
|
22
|
+
visible, range(1, visible.shape[axis]), axis=axis
|
|
23
|
+
)
|
|
24
|
+
deltas.extend(np.abs(np.diff(luminance, axis=axis))[pairs].tolist())
|
|
25
|
+
return VisualWeight(
|
|
26
|
+
local_contrast=float(np.mean(deltas)) if deltas else 0,
|
|
27
|
+
distinct_colors=len(set(map(tuple, rgba[..., :3][visible]))),
|
|
28
|
+
)
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
def repair_seams(image, palette):
|
|
32
|
+
"""Blend opposing edges symmetrically, then snap to the approved palette."""
|
|
33
|
+
pixels = np.asarray(image.convert("RGBA")).copy()
|
|
34
|
+
rgb = pixels[..., :3].astype(float)
|
|
35
|
+
edge = (rgb[:, 0] + rgb[:, -1]) / 2
|
|
36
|
+
rgb[:, 0] = rgb[:, -1] = edge
|
|
37
|
+
if rgb.shape[1] > 3:
|
|
38
|
+
rgb[:, 1] = (3 * rgb[:, 1] + edge) / 4
|
|
39
|
+
rgb[:, -2] = (3 * rgb[:, -2] + edge) / 4
|
|
40
|
+
edge = (rgb[0] + rgb[-1]) / 2
|
|
41
|
+
rgb[0] = rgb[-1] = edge
|
|
42
|
+
if rgb.shape[0] > 3:
|
|
43
|
+
rgb[1] = (3 * rgb[1] + edge) / 4
|
|
44
|
+
rgb[-2] = (3 * rgb[-2] + edge) / 4
|
|
45
|
+
pixels[..., :3] = quantize(np.rint(rgb).astype(np.uint8), palette)
|
|
46
|
+
pixels[:, -1, 3] = pixels[:, 0, 3]
|
|
47
|
+
pixels[-1, :, 3] = pixels[0, :, 3]
|
|
48
|
+
return Image.fromarray(pixels)
|
|
@@ -0,0 +1,138 @@
|
|
|
1
|
+
from collections.abc import Mapping
|
|
2
|
+
|
|
3
|
+
import numpy as np
|
|
4
|
+
from PIL import Image
|
|
5
|
+
|
|
6
|
+
from .palette import palette_rgb
|
|
7
|
+
from .schemas import AssetSpec, Failure, Style
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
def seam_scores(img: Image.Image) -> tuple[float, float]:
|
|
11
|
+
"""Normalized premultiplied RGBA differences (0..1).
|
|
12
|
+
|
|
13
|
+
Edge score measures opposite edges. Wrap score moves the original seam to
|
|
14
|
+
the middle with a half-offset roll and measures the join there. Both use
|
|
15
|
+
the maximum channel difference along the seam, so isolated defects count.
|
|
16
|
+
"""
|
|
17
|
+
rgba = np.asarray(img.convert("RGBA"), dtype=float) / 255
|
|
18
|
+
rgba[..., :3] *= rgba[..., 3:4]
|
|
19
|
+
height, width = rgba.shape[:2]
|
|
20
|
+
edge = max(np.abs(rgba[:, 0] - rgba[:, -1]).max(), np.abs(rgba[0] - rgba[-1]).max())
|
|
21
|
+
wrapped = np.roll(rgba, (height // 2, width // 2), axis=(0, 1))
|
|
22
|
+
scores = [0.0]
|
|
23
|
+
if width > 1:
|
|
24
|
+
middle = width // 2
|
|
25
|
+
scores.append(np.abs(wrapped[:, middle - 1] - wrapped[:, middle]).max())
|
|
26
|
+
if height > 1:
|
|
27
|
+
middle = height // 2
|
|
28
|
+
scores.append(np.abs(wrapped[middle - 1] - wrapped[middle]).max())
|
|
29
|
+
return float(edge), float(max(scores))
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
def validate(img: Image.Image, spec: AssetSpec, style: Style) -> list[Failure]:
|
|
33
|
+
failures = []
|
|
34
|
+
|
|
35
|
+
def fail(code, message, fix_hint):
|
|
36
|
+
failures.append(Failure(code=code, message=message, fix_hint=fix_hint))
|
|
37
|
+
|
|
38
|
+
if img.size != spec.size:
|
|
39
|
+
fail(
|
|
40
|
+
"dimensions",
|
|
41
|
+
f"Expected {spec.size}, got {img.size}.",
|
|
42
|
+
"Fit and pad to the target canvas.",
|
|
43
|
+
)
|
|
44
|
+
rgba = np.asarray(img.convert("RGBA"))
|
|
45
|
+
alpha = rgba[..., 3]
|
|
46
|
+
visible = alpha > 0
|
|
47
|
+
colors = set(map(tuple, rgba[..., :3][visible]))
|
|
48
|
+
allowed = set(map(tuple, palette_rgb(style.palette)))
|
|
49
|
+
if colors - allowed:
|
|
50
|
+
fail(
|
|
51
|
+
"palette",
|
|
52
|
+
f"{len(colors - allowed)} off-palette colors.",
|
|
53
|
+
"Quantize visible RGB to the style palette without dithering.",
|
|
54
|
+
)
|
|
55
|
+
if np.any((alpha != 0) & (alpha != 255)):
|
|
56
|
+
fail("alpha", "Alpha contains intermediate values.", "Snap alpha to 0 or 255.")
|
|
57
|
+
limit = spec.max_colors or style.max_colors
|
|
58
|
+
if len(colors) > limit:
|
|
59
|
+
fail(
|
|
60
|
+
"max_colors",
|
|
61
|
+
f"Uses {len(colors)} colors; limit is {limit}.",
|
|
62
|
+
"Use a smaller approved palette or simplify the sprite shading.",
|
|
63
|
+
)
|
|
64
|
+
if not spec.edges_allowed and (
|
|
65
|
+
visible[0].any() or visible[-1].any() or visible[:, 0].any() or visible[:, -1].any()
|
|
66
|
+
):
|
|
67
|
+
fail(
|
|
68
|
+
"clipped",
|
|
69
|
+
"Silhouette touches the canvas edge.",
|
|
70
|
+
"Add transparent padding and leave room for the outline.",
|
|
71
|
+
)
|
|
72
|
+
fill = float(visible.mean())
|
|
73
|
+
if fill < spec.min_fill_ratio:
|
|
74
|
+
fail(
|
|
75
|
+
"fill_ratio",
|
|
76
|
+
f"Fill ratio {fill:.3f} is below {spec.min_fill_ratio:.3f}.",
|
|
77
|
+
"Enlarge the subject or remove excess transparent space.",
|
|
78
|
+
)
|
|
79
|
+
if spec.type == "tile":
|
|
80
|
+
edge, wrap = seam_scores(img)
|
|
81
|
+
if edge > spec.seam_threshold:
|
|
82
|
+
fail(
|
|
83
|
+
"tile_edges",
|
|
84
|
+
f"Opposite-edge difference {edge:.3f} exceeds threshold.",
|
|
85
|
+
"Make opposite tile edges match in RGB and alpha.",
|
|
86
|
+
)
|
|
87
|
+
if wrap > spec.seam_threshold:
|
|
88
|
+
fail(
|
|
89
|
+
"tile_wrap",
|
|
90
|
+
f"Half-offset join difference {wrap:.3f} exceeds threshold.",
|
|
91
|
+
"Repair the central horizontal and vertical joins in the half-offset tile.",
|
|
92
|
+
)
|
|
93
|
+
return failures
|
|
94
|
+
|
|
95
|
+
|
|
96
|
+
def validate_animation(
|
|
97
|
+
frames: Mapping[str, Image.Image], spec: AssetSpec, style: Style
|
|
98
|
+
) -> list[Failure]:
|
|
99
|
+
"""Check every frame, consistent canvases and a common approved palette.
|
|
100
|
+
|
|
101
|
+
Frames may use different subsets of the style palette. An animation need not
|
|
102
|
+
show every color in every pose; a new unapproved color is palette drift.
|
|
103
|
+
"""
|
|
104
|
+
if not frames:
|
|
105
|
+
return [
|
|
106
|
+
Failure(
|
|
107
|
+
code="animation_empty",
|
|
108
|
+
message="Animation has no frames.",
|
|
109
|
+
fix_hint="Supply at least one named frame.",
|
|
110
|
+
)
|
|
111
|
+
]
|
|
112
|
+
failures = []
|
|
113
|
+
for name, frame in frames.items():
|
|
114
|
+
failures.extend(
|
|
115
|
+
f.model_copy(update={"message": f"{name}: {f.message}"})
|
|
116
|
+
for f in validate(frame, spec, style)
|
|
117
|
+
)
|
|
118
|
+
if len({frame.size for frame in frames.values()}) > 1:
|
|
119
|
+
failures.append(
|
|
120
|
+
Failure(
|
|
121
|
+
code="animation_size",
|
|
122
|
+
message="Frame canvases differ.",
|
|
123
|
+
fix_hint="Fit every frame to the same spec.size canvas.",
|
|
124
|
+
)
|
|
125
|
+
)
|
|
126
|
+
allowed = set(map(tuple, palette_rgb(style.palette)))
|
|
127
|
+
for frame in frames.values():
|
|
128
|
+
rgba = np.asarray(frame.convert("RGBA"))
|
|
129
|
+
if set(map(tuple, rgba[..., :3][rgba[..., 3] > 0])) - allowed:
|
|
130
|
+
failures.append(
|
|
131
|
+
Failure(
|
|
132
|
+
code="animation_palette",
|
|
133
|
+
message="Frame palette drift detected.",
|
|
134
|
+
fix_hint="Quantize every frame to the same style palette.",
|
|
135
|
+
)
|
|
136
|
+
)
|
|
137
|
+
break
|
|
138
|
+
return failures
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
EDIT the first reference (the accepted idle base sprite), changing ONLY its pose to the requested animation state/frame. Preserve identity, outfit, proportions, colors, outline, camera, top-left lighting and foot baseline. The second reference is the style anchor. Flat solid #FF00FF magenta background, chunky pixels, one centered subject, no text or watermark. Do not introduce props or redesign the character.
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
Create one idle base sprite. Flat solid #FF00FF magenta background, chunky logical pixels, one centered subject, no text, watermark, scenery or HUD. Keep the complete silhouette inside the requested logical bounds. Use the anchor only for style, never copy its scene. Use the game's camera and consistent top-left lighting.
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
Create one centered collectible or effect sprite. Flat solid #FF00FF magenta background, chunky pixels, strong readable silhouette and simple shading. No scenery, lettering, watermark or HUD. Leave clear padding around the complete subject. Match the anchor's style and top-left lighting.
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
Create one square repeating terrain tile, viewed in the game's camera. Chunky pixels; no objects, text, watermark or perspective distortion. The material must fill the tile completely. Opposite edges must match exactly and repeat seamlessly in both axes. If any exterior background is needed, use flat solid #FF00FF magenta outside the single centered tile only. Use the anchor only for material style and lighting.
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
Create one centered UI icon, flat solid #FF00FF magenta background, chunky pixels, simple high-contrast silhouette. No baked-in text, numerals, watermark, panel or scene. Preserve padding and match the approved palette. Use the anchor as a style reference only.
|
|
File without changes
|
|
@@ -0,0 +1,97 @@
|
|
|
1
|
+
from typing import Literal, Protocol
|
|
2
|
+
|
|
3
|
+
from pydantic import BaseModel, Field
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
class ImageRequest(BaseModel):
|
|
7
|
+
prompt: str
|
|
8
|
+
size: tuple[int, int] = (1024, 1024)
|
|
9
|
+
reasoning_strength: Literal["low", "high"] = "low"
|
|
10
|
+
references: list[bytes] = Field(default_factory=list, max_length=10)
|
|
11
|
+
|
|
12
|
+
|
|
13
|
+
class ImageResult(BaseModel):
|
|
14
|
+
data: bytes
|
|
15
|
+
mime: str = "image/png"
|
|
16
|
+
metadata: dict = Field(default_factory=dict)
|
|
17
|
+
|
|
18
|
+
|
|
19
|
+
class Message(BaseModel):
|
|
20
|
+
role: Literal["system", "user", "assistant", "tool"]
|
|
21
|
+
content: str | None = None
|
|
22
|
+
images: list[bytes] = Field(default_factory=list)
|
|
23
|
+
tool_calls: list[dict] = Field(default_factory=list)
|
|
24
|
+
tool_call_id: str | None = None
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
class ChatRequest(BaseModel):
|
|
28
|
+
messages: list[Message]
|
|
29
|
+
tools: list[dict] = Field(default_factory=list)
|
|
30
|
+
json_schema: dict | None = None
|
|
31
|
+
# Spark `reasoning_effort` (None: the model chooses) and `prompt_cache_key`, which routes
|
|
32
|
+
# requests sharing a prefix to the same cache.
|
|
33
|
+
reasoning_effort: str | None = None
|
|
34
|
+
cache_key: str | None = None
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
class ChatResult(BaseModel):
|
|
38
|
+
content: str | None = None
|
|
39
|
+
tool_calls: list[dict] = Field(default_factory=list)
|
|
40
|
+
metadata: dict = Field(default_factory=dict)
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
class SearchRequest(BaseModel):
|
|
44
|
+
"""A research question answered with live web search (Responses API, `web_search`)."""
|
|
45
|
+
|
|
46
|
+
instructions: str # the role prompt
|
|
47
|
+
prompt: str
|
|
48
|
+
json_schema: dict | None = None
|
|
49
|
+
max_searches: int = Field(default=8, ge=1)
|
|
50
|
+
reasoning_effort: str | None = None
|
|
51
|
+
cache_key: str | None = None
|
|
52
|
+
|
|
53
|
+
|
|
54
|
+
class WebSource(BaseModel):
|
|
55
|
+
url: str
|
|
56
|
+
title: str = ""
|
|
57
|
+
|
|
58
|
+
|
|
59
|
+
class SearchResult(BaseModel):
|
|
60
|
+
content: str | None = None # the last message's text (the structured answer)
|
|
61
|
+
text: str = "" # every message's text, in order
|
|
62
|
+
queries: list[str] = Field(default_factory=list) # what the model searched for
|
|
63
|
+
sources: list[WebSource] = Field(default_factory=list) # pages the searches returned
|
|
64
|
+
cited: list[WebSource] = Field(default_factory=list) # url_citation annotations
|
|
65
|
+
searches: int = 0 # web_search_call items (searches and page opens)
|
|
66
|
+
metadata: dict = Field(default_factory=dict)
|
|
67
|
+
|
|
68
|
+
|
|
69
|
+
class ImageProvider(Protocol):
|
|
70
|
+
def generate(self, request: ImageRequest) -> ImageResult: ...
|
|
71
|
+
def edit(self, request: ImageRequest) -> ImageResult: ...
|
|
72
|
+
|
|
73
|
+
|
|
74
|
+
class LLMProvider(Protocol):
|
|
75
|
+
def chat(self, request: ChatRequest) -> ChatResult: ...
|
|
76
|
+
|
|
77
|
+
|
|
78
|
+
class SearchProvider(Protocol):
|
|
79
|
+
def research(self, request: SearchRequest) -> SearchResult: ...
|
|
80
|
+
|
|
81
|
+
|
|
82
|
+
def chat_json(provider: LLMProvider, request: ChatRequest, schema: type[BaseModel]) -> BaseModel:
|
|
83
|
+
"""Validate every structured answer; one corrective retry only."""
|
|
84
|
+
from pydantic import ValidationError
|
|
85
|
+
|
|
86
|
+
request = request.model_copy(deep=True)
|
|
87
|
+
request.json_schema = schema.model_json_schema()
|
|
88
|
+
for attempt in range(2):
|
|
89
|
+
result = provider.chat(request)
|
|
90
|
+
try:
|
|
91
|
+
return schema.model_validate_json(result.content or "")
|
|
92
|
+
except ValidationError as exc:
|
|
93
|
+
if attempt:
|
|
94
|
+
raise
|
|
95
|
+
request.messages.append(Message(role="assistant", content=result.content or ""))
|
|
96
|
+
request.messages.append(Message(role="user", content=f"Correct JSON errors: {exc}"))
|
|
97
|
+
raise AssertionError("unreachable")
|