Text Completion

class CompletionRequest:
    prompt: Prompt
    maximum_tokens: Optional[int] = None
    temperature: float = 0.0
    top_k: int = 0
    top_p: float = 0.0
    presence_penalty: float = 0.0
    frequency_penalty: float = 0.0
    stop_sequences: Optional[List[str]] = None
    n: int = 1
    best_of: Optional[int] = None
    log_probs: Optional[int] = None
    echo: bool = False
    steering_concepts: Optional[List[str]] = None
    """
    Request configuration for text completion.
    
    Attributes:
    - prompt: Input prompt (multimodal supported)
    - maximum_tokens: Maximum tokens to generate
    - temperature: Sampling temperature (0.0 = deterministic, higher = more random)
    - top_k: Top-k sampling (0 = disabled)
    - top_p: Top-p/nucleus sampling (0.0 = disabled)
    - presence_penalty: Penalty for token presence (-2.0 to 2.0)
    - frequency_penalty: Penalty for token frequency (-2.0 to 2.0)
    - stop_sequences: Sequences that stop generation
    - n: Number of completions to generate
    - best_of: Generate best_of completions, return top n
    - log_probs: Number of log probabilities to return per token
    - echo: Include prompt in response
    - steering_concepts: Concept IDs for content steering
    """

    def to_json(self) -> Mapping[str, Any]:
        """Serialize request to JSON format."""

class CompletionResponse:
    model_version: str
    completions: Sequence[CompletionResult]
    num_tokens_prompt_total: int
    num_tokens_generated: int
    optimized_prompt: Optional[Prompt] = None
    """
    Response from completion request.
    
    Attributes:
    - model_version: Version of model used for generation
    - completions: Generated completion results
    - num_tokens_prompt_total: Total tokens in prompt
    - num_tokens_generated: Total tokens generated
    - optimized_prompt: Optimized version of input prompt (if applicable)
    """

    @staticmethod
    def from_json(json: Dict[str, Any]) -> CompletionResponse:
        """Create response from JSON data."""

class CompletionResult:
    log_probs: Optional[Sequence[Mapping[str, Optional[float]]]] = None
    completion: Optional[str] = None
    completion_tokens: Optional[Sequence[str]] = None
    finish_reason: Optional[str] = None
    raw_completion: Optional[str] = None
    """
    Individual completion result.
    
    Attributes:
    - log_probs: Log probabilities for each token (if requested)
    - completion: Generated text completion
    - completion_tokens: Individual tokens in completion
    - finish_reason: Reason generation stopped ("stop", "length", etc.)
    - raw_completion: Unprocessed completion text
    """

def complete(self, request: CompletionRequest, model: str) -> CompletionResponse:
    """
    Generate text completion.
    
    Parameters:
    - request: Completion configuration
    - model: Model name to use for generation
    
    Returns:
    CompletionResponse with generated completions
    """

async def complete(self, request: CompletionRequest, model: str) -> CompletionResponse:
    """
    Generate text completion (async).
    
    Parameters:
    - request: Completion configuration  
    - model: Model name to use for generation
    
    Returns:
    CompletionResponse with generated completions
    """

async def complete_with_streaming(
    self, 
    request: CompletionRequest, 
    model: str
) -> AsyncGenerator[CompletionResponseStreamItem, None]:
    """
    Generate completion with streaming results.
    
    Parameters:
    - request: Completion configuration
    - model: Model name to use for generation
    
    Yields:
    Stream items containing partial completions and final summary
    """

class StreamChunk:
    index: int
    log_probs: Optional[Sequence[Mapping[str, Optional[float]]]]
    completion: str
    raw_completion: Optional[str]
    completion_tokens: Optional[Sequence[str]]
    """
    Chunk of streaming completion data.
    
    Attributes:
    - index: Stream index for multiple completions
    - log_probs: Log probabilities for chunk tokens
    - completion: Text chunk
    - raw_completion: Unprocessed text chunk
    - completion_tokens: Tokens in this chunk
    """

class StreamSummary:
    index: int
    model_version: str
    finish_reason: str
    """
    End-of-stream marker for individual completion.
    
    Attributes:
    - index: Stream index
    - model_version: Model version used
    - finish_reason: Why generation stopped
    """

class CompletionSummary:
    optimized_prompt: Optional[Prompt]
    num_tokens_prompt_total: int
    num_tokens_generated: int
    """
    Final summary after all streams complete.
    
    Attributes:
    - optimized_prompt: Optimized input prompt
    - num_tokens_prompt_total: Total prompt tokens
    - num_tokens_generated: Total generated tokens
    """

from aleph_alpha_client import Client, CompletionRequest, Prompt

client = Client(token="your-api-token")

# Simple completion
request = CompletionRequest(
    prompt=Prompt.from_text("The future of AI is"),
    maximum_tokens=50,
    temperature=0.7
)
response = client.complete(request, model="luminous-extended")
print(response.completions[0].completion)

# Advanced completion with multiple results
request = CompletionRequest(
    prompt=Prompt.from_text("Write a creative story about:"),
    maximum_tokens=200,
    temperature=0.8,
    top_p=0.9,
    n=3,  # Generate 3 completions
    stop_sequences=["\n\n", "THE END"],
    presence_penalty=0.1,
    frequency_penalty=0.1
)
response = client.complete(request, model="luminous-extended")

for i, completion in enumerate(response.completions):
    print(f"Completion {i+1}: {completion.completion}")
    print(f"Finish reason: {completion.finish_reason}")

# Completion with log probabilities
request = CompletionRequest(
    prompt=Prompt.from_text("The capital of France is"),
    maximum_tokens=10,
    temperature=0.0,  # Deterministic
    log_probs=5,  # Top 5 log probs per token
    echo=True  # Include prompt in response
)
response = client.complete(request, model="luminous-extended")

completion = response.completions[0]
if completion.log_probs:
    for token_logprobs in completion.log_probs:
        print(f"Token probabilities: {token_logprobs}")

# Streaming completion (async)
import asyncio

async def streaming_completion():
    async with AsyncClient(token="your-api-token") as client:
        request = CompletionRequest(
            prompt=Prompt.from_text("Write a long story about space exploration:"),
            maximum_tokens=500,
            temperature=0.7
        )
        
        async for item in client.complete_with_streaming(request, "luminous-extended"):
            if isinstance(item, StreamChunk):
                print(item.completion, end="", flush=True)
            elif isinstance(item, StreamSummary):
                print(f"\nStream {item.index} finished: {item.finish_reason}")
            elif isinstance(item, CompletionSummary):
                print(f"Total tokens generated: {item.num_tokens_generated}")

asyncio.run(streaming_completion())

# Multimodal completion
from aleph_alpha_client import Image

image = Image.from_file("image.jpg")
multimodal_prompt = Prompt([
    Text.from_text("Describe this image in detail:"),
    image
])

request = CompletionRequest(
    prompt=multimodal_prompt,
    maximum_tokens=150,
    temperature=0.5
)
response = client.complete(request, model="luminous-extended")
print(response.completions[0].completion)