Update docs/API_REFERENCE.md

docs/API_REFERENCE.md

@@ -1,68 +1,95 @@
-# API Reference
+<!-- API_REFERENCE.md -->
 
-This document describes the public Python modules and functions available in AnyCoder.
+# Shasha AI — API Reference
+
+This document describes the public interfaces provided by each module.
 
 ---
 
-## `models.py`
+## `hf_client.py`
 
-### `ModelInfo` dataclass
+### `get_inference_client(model_id: str, provider: str = "auto") → InferenceClient`
+Creates and configures a Hugging Face Hub client for chat completions.
 
-```python
-@dataclass
-class ModelInfo:
-    name: str
-    id: str
-    description: str
-    default_provider: str = "auto"
-```
+- **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.
 
-### `AVAILABLE_MODELS: List[ModelInfo]`
+---
 
-A list of supported models with metadata.
+## `models.py`
+
+### `ModelInfo`
+Dataclass representing model metadata.
 
-### `find_model(identifier: str) -> Optional[ModelInfo]`
+- **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.
 
-Lookup a model by name or ID. Returns a `ModelInfo` or `None`.
+### `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: Optional[str]=None, max_tokens: int=4096) -> str`
+### `chat_completion(model_id: str, messages: List[Dict[str, str]], provider: str = None, max_tokens: int = 4096) → str`
+Synchronously sends a chat completion request.
 
-Send a one-shot chat completion request. Returns the assistant response as a string.
+- **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: Optional[str]=None, max_tokens: int=4096) -> Generator[str]`
-
-Stream partial generation results, yielding content chunks.
+### `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.
 
 ---
 
-## `hf_client.py`
+## `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.
 
-### `get_inference_client(model_id: str, provider: str="auto") -> InferenceClient`
+### `format_transformers_js_output(files: Dict[str, str]) → str`
+Formats a dict of file contents into a single combined string with section headers.
 
-Create and return a configured `InferenceClient`, routing to Groq, OpenAI, Gemini, Fireworks, or HF as needed.
+*(Other utilities: multimodal image processing, search/replace, history rendering)*
 
 ---
 
 ## `deploy.py`
 
-### `send_to_sandbox(code: str) -> str`
+### `send_to_sandbox(code: str) → str`
+Wraps HTML code in a base64 data‑URI iframe for live preview.
 
-Wrap HTML code in a sandboxed iframe via a data URI for live preview.
+### `load_project_from_url(url: str) → Tuple[str, str]`
+Fetches `app.py` or `index.html` from a public HF Space URL.
 
-### `load_project_from_url(url: str) -> Tuple[str, str]`
-
-Import a Hugging Face Space by URL, returning status message and code content.
+*(Also: HF Spaces deploy helpers: `deploy_to_spaces()`, `deploy_to_spaces_static()`, `deploy_to_user_space()`)*
 
 ---
 
-## `plugins.py`
+## `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.
 
-### `PluginManager`
+- **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  
+
+---
 
-* `discover()`: auto-discovers plugins in the `plugins/` namespace.
-* `list_plugins() -> List[str]`: return registered plugin names.
-* `run_plugin(name: str, payload: Dict) -> Any`: execute a plugin action.
+_For more examples, see the Jupyter notebooks in_ `notebooks/` and the quick‑start guide in `QUICKSTART.md`.