File size: 3,720 Bytes
8ec22c6 |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 |
<!-- ARCHITECTURE.md -->
# Shasha AI — Architecture Overview
A high‑level view of the components and data flow in the Shasha AI code‑generation platform.
## 1. Core Layers
### 1.1 Frontend (Gradio UI)
- **app.py**: Defines the Gradio Blocks UI — input panels (prompt, file, website, image), model selector, language selector, buttons, and output panes (Code, Preview, History).
- **static/**: Holds `index.html`, `index.js`, `style.css` for any transformers.js demos and custom styling.
- **assets/**: Images, logos, and other static assets.
### 1.2 Backend Services
#### 1.2.1 Inference Routing
- **hf_client.py**
- `get_inference_client(model_id, provider)`
- Wraps HF/OpenAI/Gemini/Groq providers into a unified interface.
- Automatically selects/falls back based on model prefix and available credentials.
- **inference.py**
- `chat_completion(...)` and `stream_chat_completion(...)`
- Encapsulates request/response logic, streaming vs. blocking, and error handling.
#### 1.2.2 Model Registry
- **models.py**
- `ModelInfo` dataclass & `AVAILABLE_MODELS` registry
- Central source of truth for supported models, identifiers, descriptions, and default providers.
- Helper `find_model()` for lookup by name or ID.
#### 1.2.3 Prompt & History Management
- **constants.py**
- System prompts for HTML/transformers.js modes, search/replace tokens, Gradio language support.
- **utils.py**
- `history_to_messages()`, `remove_code_block()`, multimodal image encoding, parsing transformers.js outputs, search/replace utilities.
#### 1.2.4 Deployment & Project Import
- **deploy.py**
- `send_to_sandbox()` → live HTML preview in iframe
- `load_project_from_url()` → import existing HF Spaces (app.py/index.html)
- `deploy_to_spaces*()` → create/update HF Space via Hub API
## 2. Extensions & Plugins
- **plugins.py** (future)
- Plugin discovery/loading for community‑created extensions (e.g., DB runners, snippet libraries).
- **auth.py** (future)
- OAuth flows for GitHub, Google Drive, Slack — enable private file loading.
## 3. Project Structure
.
├── app.py # Gradio application
├── constants.py # System prompts & app‑wide constants
├── hf_client.py # Inference client factory
├── models.py # Model registry & metadata
├── inference.py # Chat completion wrappers
├── utils.py # Helpers: history, code parsing, multimodal
├── deploy.py # Sandbox preview & HF Spaces import/deploy
├── plugins.py # (planned) Plugin architecture
├── auth.py # (planned) OAuth integrations
├── notebooks/ # Demo Jupyter notebooks
├── tests/ # pytest suites & UI smoke tests
├── ci.yaml # CI pipeline for lint/test/deploy
├── docs/
│ ├── QUICKSTART.md
│ ├── ARCHITECTURE.md
│ └── API_REFERENCE.md
└── static/ # transformers.js demos & CSS/JS assets
yaml
Copy
Edit
## 4. Data Flow
1. **User Interaction**: User enters prompt / uploads file / selects model & language.
2. **Preprocessing**:
- File → `extract_text_from_file()`
- Website → `extract_website_content()`
- Image → `process_image_for_model()`
3. **Message Assembly**:
- System prompt + history → OpenAI‑style message list
- Enhanced via optional web search (Tavily)
4. **Inference Call**:
- `get_inference_client()` → select provider & billing
- `chat_completion()` or streaming
5. **Postprocessing**:
- Parse code blocks / transformers.js multi‑file output
- Apply search/replace to existing code if editing
6. **UI Update**:
- Code pane
- Live preview iframe (`send_to_sandbox`)
- Chat history pane
---
|