| <!-- 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`. |