tessl/pypi-aleph-alpha-client
Python client to interact with Aleph Alpha API endpoints
—
Pending
Quality
Pending
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
prompt-construction.mddocs/
Prompt Construction
Flexible multimodal prompt system supporting text, images, and tokens with advanced attention control mechanisms. Enables fine-grained control over model attention through various control types and supports rich multimodal input combinations.
Capabilities
Core Prompt Container
Main container class for organizing multimodal prompt content with support for text, images, and token sequences.
class Prompt:
def __init__(self, items: Union[str, Sequence[PromptItem]]):
"""
Create prompt from items or single string.
Parameters:
- items: Single string or sequence of PromptItem objects (Text, Image, Tokens)
"""
@staticmethod
def from_text(text: str, controls: Optional[Sequence[TextControl]] = None) -> Prompt:
"""Create prompt from plain text with optional attention controls."""
@staticmethod
def from_image(image: Image) -> Prompt:
"""Create prompt from single image."""
@staticmethod
def from_tokens(tokens: Sequence[int], controls: Optional[Sequence[TokenControl]] = None) -> Prompt:
"""Create prompt from token sequence with optional attention controls."""
@staticmethod
def from_json(items_json: Sequence[Mapping[str, Any]]) -> Prompt:
"""Create prompt from JSON representation."""
def to_json(self) -> Sequence[Mapping[str, Any]]:
"""Serialize prompt to JSON format."""Text Prompt Items
Text content with optional attention manipulation controls for fine-tuning model focus.
class Text:
text: str
controls: Sequence[TextControl]
"""
Text prompt item with attention controls.
Attributes:
- text: The text content
- controls: Sequence of TextControl objects for attention manipulation
"""
@staticmethod
def from_text(text: str) -> Text:
"""Create Text item from plain string."""
@staticmethod
def from_json(json: Mapping[str, Any]) -> Text:
"""Create Text item from JSON representation."""
def to_json(self) -> Mapping[str, Any]:
"""Serialize to JSON format."""Image Prompt Items
Image content with support for cropping, attention controls, and multiple input formats.
class Image:
base_64: str
cropping: Optional[Cropping]
controls: Sequence[ImageControl]
"""
Image prompt item with cropping and attention controls.
Attributes:
- base_64: Base64 encoded image data
- cropping: Optional image cropping specification
- controls: Sequence of ImageControl objects for attention manipulation
"""
@classmethod
def from_image_source(
cls,
image_source: Union[str, Path, bytes],
controls: Optional[Sequence[ImageControl]] = None
) -> Image:
"""Create from various image sources (file path, URL, or bytes)."""
@classmethod
def from_bytes(
cls,
bytes: bytes,
cropping: Optional[Cropping] = None,
controls: Optional[Sequence[ImageControl]] = None
) -> Image:
"""Create from raw image bytes."""
@classmethod
def from_url(
cls,
url: str,
controls: Optional[Sequence[ImageControl]] = None
) -> Image:
"""Create from image URL."""
@classmethod
def from_file(
cls,
path: Union[str, Path],
controls: Optional[Sequence[ImageControl]] = None
) -> Image:
"""Create from local file path."""
@classmethod
def from_file_with_cropping(
cls,
path: str,
upper_left_x: int,
upper_left_y: int,
crop_size: int,
controls: Optional[Sequence[ImageControl]] = None
) -> Image:
"""Create from file with square cropping."""
@classmethod
def from_json(cls, json: Mapping[str, Any]) -> Image:
"""Create from JSON representation."""
def to_json(self) -> Mapping[str, Any]:
"""Serialize to JSON format."""
def to_image(self) -> PILImage:
"""Convert to PIL Image object."""
def dimensions(self) -> Tuple[int, int]:
"""Get image dimensions as (width, height)."""Token Prompt Items
Direct token sequence input with attention controls for low-level prompt manipulation.
class Tokens:
tokens: Sequence[int]
controls: Sequence[TokenControl]
"""
Token sequence prompt item with attention controls.
Attributes:
- tokens: Sequence of token IDs
- controls: Sequence of TokenControl objects for attention manipulation
"""
@staticmethod
def from_token_ids(token_ids: Sequence[int]) -> Tokens:
"""Create from sequence of token IDs."""
@staticmethod
def from_json(json: Mapping[str, Any]) -> Tokens:
"""Create from JSON representation."""
def to_json(self) -> Mapping[str, Any]:
"""Serialize to JSON format."""Attention Control Systems
Text Control
Fine-grained attention manipulation for text content based on character positions.
class TextControl:
start: int
length: int
factor: float
token_overlap: Optional[ControlTokenOverlap] = None
"""
Attention control for text prompts.
Attributes:
- start: Starting character index
- length: Number of characters to affect
- factor: Attention adjustment factor (>1 increases, <1 decreases)
- token_overlap: How to handle partial token overlap
"""Image Control
Spatial attention control for image regions using normalized coordinates.
class ImageControl:
left: float
top: float
width: float
height: float
factor: float
token_overlap: Optional[ControlTokenOverlap] = None
"""
Spatial attention control for images.
Attributes:
- left: Left coordinate (0-1, normalized)
- top: Top coordinate (0-1, normalized)
- width: Width (0-1, normalized)
- height: Height (0-1, normalized)
- factor: Attention adjustment factor
- token_overlap: How to handle partial token overlap
"""Token Control
Direct attention manipulation for specific token positions.
class TokenControl:
pos: int
factor: float
"""
Direct attention control for tokens.
Attributes:
- pos: Token position index
- factor: Attention adjustment factor
"""Control Token Overlap
Enumeration controlling how attention factors are applied when they partially overlap with tokens.
class ControlTokenOverlap(Enum):
Partial = "partial" # Proportional factor adjustment
Complete = "complete" # Full factor applicationImage Cropping
Square cropping specification for image preprocessing.
class Cropping:
upper_left_x: int
upper_left_y: int
size: int
"""
Square image cropping specification.
Attributes:
- upper_left_x: X coordinate of upper left corner
- upper_left_y: Y coordinate of upper left corner
- size: Size of the square crop in pixels
"""Usage Examples
from aleph_alpha_client import (
Prompt, Text, Image, Tokens,
TextControl, ImageControl, TokenControl,
ControlTokenOverlap
)
# Simple text prompt
prompt = Prompt.from_text("What is artificial intelligence?")
# Text with attention control
text_with_control = Text(
text="Please focus on this important part of the text.",
controls=[
TextControl(
start=17, # Start at "important"
length=9, # Length of "important"
factor=2.0, # Double attention
token_overlap=ControlTokenOverlap.Complete
)
]
)
prompt = Prompt([text_with_control])
# Image from file
image = Image.from_file("path/to/image.jpg")
prompt = Prompt.from_image(image)
# Image with cropping and attention control
image = Image.from_file_with_cropping(
"path/to/image.jpg",
upper_left_x=100,
upper_left_y=100,
crop_size=200,
controls=[
ImageControl(
left=0.2, top=0.2, width=0.6, height=0.6,
factor=1.5 # Increase attention on center region
)
]
)
# Multimodal prompt
multimodal_prompt = Prompt([
Text.from_text("Describe this image:"),
Image.from_file("image.jpg"),
Text.from_text("Focus on the colors and composition.")
])
# Token-level control
tokens = Tokens.from_token_ids([1, 2, 3, 4, 5])
tokens_with_control = Tokens(
tokens=[1, 2, 3, 4, 5],
controls=[
TokenControl(pos=2, factor=3.0) # Emphasize token at position 2
]
)Install with Tessl CLI
npx tessl i tessl/pypi-aleph-alpha-client