docs/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.