docs/API_REFERENCE.md

<!-- API_REFERENCE.md -->

# Shasha AI — API Reference

This document describes the public interfaces provided by each module.

---

## `hf_client.py`

### `get_inference_client(model_id: str, provider: str = "auto") → InferenceClient`
Creates and configures a Hugging Face Hub client for chat completions.

- **model_id**: HF model ID or external provider prefix (e.g. `"openai/gpt-4"`, `"gemini/pro"`, `"moonshotai/Kimi-K2-Instruct"`).
- **provider**: Override provider; one of `auto`, `groq`, `openai`, `gemini`, `fireworks`.
- **Returns**: `InferenceClient` instance with proper API key & billing target.

---

## `models.py`

### `ModelInfo`
Dataclass representing model metadata.

- **name**: Human‑readable model name.
- **id**: Model identifier for API calls.
- **description**: Short description.
- **default_provider**: Preferred inference provider.

### `AVAILABLE_MODELS: List[ModelInfo]`
Registry of all supported models.

### `find_model(identifier: str) → Optional[ModelInfo]`
Lookup model by name (case‑insensitive) or ID.

---

## `inference.py`

### `chat_completion(model_id: str, messages: List[Dict[str, str]], provider: str = None, max_tokens: int = 4096) → str`
Synchronously sends a chat completion request.

- **messages**: List of `{"role": "...", "content": "..."}`  
- **provider**: Optional override; defaults to model’s `default_provider`.
- **Returns**: Response content string.

### `stream_chat_completion(model_id: str, messages: List[Dict[str, str]], provider: str = None, max_tokens: int = 4096) → Generator[str]`
Streams a chat completion, yielding incremental content chunks.

---

## `utils.py`

### `history_to_messages(history: History, system: str) → List[Dict]`
Converts internal history list to OpenAI‑style messages.

### `remove_code_block(text: str) → str`
Strips markdown code fences from AI output and returns raw code.

### `parse_transformers_js_output(text: str) → Dict[str, str]`
Extracts `index.html`, `index.js`, `style.css` from a multi‑file markdown output.

### `format_transformers_js_output(files: Dict[str, str]) → str`
Formats a dict of file contents into a single combined string with section headers.

*(Other utilities: multimodal image processing, search/replace, history rendering)*

---

## `deploy.py`

### `send_to_sandbox(code: str) → str`
Wraps HTML code in a base64 data‑URI iframe for live preview.

### `load_project_from_url(url: str) → Tuple[str, str]`
Fetches `app.py` or `index.html` from a public HF Space URL.

*(Also: HF Spaces deploy helpers: `deploy_to_spaces()`, `deploy_to_spaces_static()`, `deploy_to_user_space()`)*

---

## `app.py`

### `generation_code(query, image, file, website_url, _setting, _history, _current_model, enable_search, language, provider) → Tuple[str, History, str, List[Dict]]`
Main generation handler bound to the “Generate” button.

- **Returns**:  
  1. `code_str`: Generated (or edited) source code  
  2. `new_history`: Updated prompt/response history  
  3. `sandbox_html`: Live preview HTML iframe string  
  4. `chat_msgs`: Chatbot‑style history for the UI  

---

_For more examples, see the Jupyter notebooks in_ `notebooks/` and the quick‑start guide in `QUICKSTART.md`.