# Gumawa ng Chat Assistant gamit ang AI
Naalala mo ba sa Star Trek kung paano nakikipag-usap ang crew sa computer ng barko, nagtatanong ng mga kumplikadong tanong at nakakatanggap ng mga makabuluhang sagot? Ang tila isang purong science fiction noong 1960s ay ngayon ay kaya mo nang gawin gamit ang mga teknolohiyang web na alam mo na.
Sa araling ito, gagawa tayo ng AI chat assistant gamit ang HTML, CSS, JavaScript, at ilang backend integration. Matutuklasan mo kung paano ang parehong mga kasanayan na natutunan mo ay maaaring kumonekta sa mga makapangyarihang serbisyo ng AI na nakakaunawa ng konteksto at bumubuo ng makabuluhang mga sagot.
Isipin ang AI na parang may access ka sa isang napakalaking library na hindi lang naghahanap ng impormasyon kundi nagbubuo rin ng malinaw na mga sagot na naaayon sa iyong mga tanong. Sa halip na maghanap sa libu-libong pahina, makakakuha ka ng direktang sagot na may konteksto.
Ang integration ay nangyayari sa pamamagitan ng mga pamilyar na teknolohiyang web na nagtutulungan. Ang HTML ang gumagawa ng chat interface, ang CSS ang nag-aayos ng disenyo, ang JavaScript ang namamahala sa mga interaksyon ng user, at ang backend API ang nagkokonekta sa lahat ng ito sa mga serbisyo ng AI. Katulad ito ng kung paano nagtutulungan ang iba't ibang seksyon ng orchestra upang makabuo ng isang sinfonya.
Sa esensya, gumagawa tayo ng tulay sa pagitan ng natural na komunikasyon ng tao at pagproseso ng makina. Matutunan mo ang parehong teknikal na implementasyon ng AI service integration at ang mga disenyo na nagpapadali sa pakikipag-ugnayan.
Sa pagtatapos ng araling ito, ang AI integration ay magiging mas pamilyar sa iyo, parang isa pang API na kaya mong gamitin. Maiintindihan mo ang mga pundasyong pattern na nagpapagana sa mga aplikasyon tulad ng ChatGPT at Claude, gamit ang parehong mga prinsipyo ng web development na natutunan mo.
Ganito ang magiging hitsura ng iyong natapos na proyekto:
## Pag-unawa sa AI: Mula sa Misteryo patungo sa Mastery
Bago sumabak sa code, unawain muna natin kung ano ang ating ginagawa. Kung nakagamit ka na ng mga API dati, alam mo ang pangunahing pattern: magpadala ng request, tumanggap ng response.
Ang mga AI API ay sumusunod sa parehong istruktura, ngunit sa halip na kumuha ng pre-stored na data mula sa database, bumubuo sila ng mga bagong sagot batay sa mga pattern na natutunan mula sa napakalaking dami ng teksto. Isipin ito na parang pagkakaiba ng sistema ng katalogo ng library at isang librarian na marunong mag-synthesize ng impormasyon mula sa maraming mapagkukunan.
### Ano ba Talaga ang "Generative AI"?
Isipin kung paano ang Rosetta Stone ay nagbigay-daan sa mga iskolar na maunawaan ang mga hieroglyphics ng Egypt sa pamamagitan ng paghahanap ng mga pattern sa pagitan ng mga kilala at hindi kilalang wika. Ganito rin ang ginagawa ng mga AI model – hinahanap nila ang mga pattern sa napakalaking dami ng teksto upang maunawaan kung paano gumagana ang wika, at ginagamit ang mga pattern na ito upang bumuo ng angkop na mga sagot sa mga bagong tanong.
**Hayaan kong ipaliwanag ito sa isang simpleng paghahambing:**
- **Tradisyunal na database**: Parang humihingi ng birth certificate – palaging pareho ang dokumento na makukuha mo
- **Search engine**: Parang humihingi sa librarian na maghanap ng mga libro tungkol sa pusa – ipapakita nila kung ano ang available
- **Generative AI**: Parang nagtatanong sa isang matalinong kaibigan tungkol sa pusa – sasabihin nila ang mga kawili-wiling bagay sa kanilang sariling mga salita, naaayon sa gusto mong malaman
```mermaid
graph LR
A[Your Question] --> B[AI Model]
B --> C[Pattern Recognition]
C --> D[Content Generation]
D --> E[Contextual Response]
F[Training Data
Books, Articles, Web] --> B
```
### Paano Natututo ang AI Models (Simpleng Bersyon)
Ang mga AI model ay natututo sa pamamagitan ng exposure sa napakalaking dataset na naglalaman ng teksto mula sa mga libro, artikulo, at usapan. Sa prosesong ito, natutukoy nila ang mga pattern sa:
- Paano binubuo ang mga ideya sa nakasulat na komunikasyon
- Aling mga salita ang karaniwang magkasama
- Paano karaniwang dumadaloy ang mga usapan
- Mga pagkakaiba sa konteksto sa pagitan ng pormal at impormal na komunikasyon
**Katulad ito ng kung paano binibigyang-kahulugan ng mga archaeologist ang mga sinaunang wika**: sinusuri nila ang libu-libong halimbawa upang maunawaan ang grammar, bokabularyo, at konteksto ng kultura, hanggang sa kaya na nilang bigyang-kahulugan ang mga bagong teksto gamit ang mga natutunang pattern.
### Bakit GitHub Models?
Ginagamit natin ang GitHub Models para sa isang praktikal na dahilan – nagbibigay ito ng access sa enterprise-level AI nang hindi kinakailangang mag-set up ng sarili nating AI infrastructure (na, maniwala ka, hindi mo gugustuhing gawin ngayon!). Isipin ito na parang paggamit ng weather API sa halip na subukang hulaan ang panahon sa pamamagitan ng pag-set up ng mga weather station sa lahat ng lugar.
Ito ay "AI-as-a-Service," at ang pinakamagandang bahagi? Libre itong simulan, kaya maaari kang mag-eksperimento nang hindi nag-aalala tungkol sa malaking gastos.
```mermaid
graph LR
A[Frontend Chat UI] --> B[Your Backend API]
B --> C[GitHub Models API]
C --> D[AI Model Processing]
D --> C
C --> B
B --> A
```
Gagamitin natin ang GitHub Models para sa ating backend integration, na nagbibigay ng access sa mga propesyonal na AI capabilities sa pamamagitan ng isang developer-friendly interface. Ang [GitHub Models Playground](https://github.com/marketplace/models/azure-openai/gpt-4o-mini/playground) ay nagsisilbing testing environment kung saan maaari kang mag-eksperimento sa iba't ibang AI models at maunawaan ang kanilang kakayahan bago ito i-implement sa code.
**Narito kung bakit kapaki-pakinabang ang playground:**
- **Subukan** ang iba't ibang AI models tulad ng GPT-4o-mini, Claude, at iba pa (lahat libre!)
- **I-test** ang iyong mga ideya at prompts bago ka magsulat ng code
- **Kumuha** ng ready-to-use code snippets sa iyong paboritong programming language
- **I-tweak** ang mga setting tulad ng creativity level at response length upang makita kung paano ito nakakaapekto sa output
Kapag nakapaglaro ka na nang kaunti, i-click lang ang "Code" tab at piliin ang iyong programming language upang makuha ang implementation code na kakailanganin mo.
## Pag-set Up ng Python Backend Integration
Ngayon, i-implement natin ang AI integration gamit ang Python. Ang Python ay mahusay para sa AI applications dahil sa simpleng syntax nito at makapangyarihang mga library. Magsisimula tayo sa code mula sa GitHub Models playground at pagkatapos ay i-refactor ito sa isang reusable, production-ready function.
### Pag-unawa sa Base Implementation
Kapag kinuha mo ang Python code mula sa playground, makakakuha ka ng ganito. Huwag mag-alala kung mukhang marami ito sa simula – talakayin natin ito nang paisa-isa:
```python
"""Run this model in Python
> pip install openai
"""
import os
from openai import OpenAI
# To authenticate with the model you will need to generate a personal access token (PAT) in your GitHub settings.
# Create your PAT token by following instructions here: https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens
client = OpenAI(
base_url="https://models.github.ai/inference",
api_key=os.environ["GITHUB_TOKEN"],
)
```python
response = client.chat.completions.create(
messages=[
{
"role": "system",
"content": "",
},
{
"role": "user",
"content": "What is the capital of France?",
}
],
model="openai/gpt-4o-mini",
temperature=1,
max_tokens=4096,
top_p=1
)
print(response.choices[0].message.content)
```
**Narito ang nangyayari sa code na ito:**
- **Nag-i-import** tayo ng mga tools na kailangan: `os` para sa pagbabasa ng environment variables at `OpenAI` para sa pakikipag-usap sa AI
- **Inaayos** natin ang OpenAI client upang ituro sa GitHub's AI servers sa halip na direktang OpenAI
- **Nag-aauthenticate** gamit ang isang espesyal na GitHub token (higit pa tungkol dito mamaya!)
- **Istruktura** natin ang usapan gamit ang iba't ibang "roles" – isipin ito na parang pag-set ng eksena para sa isang play
- **Nagpapadala** tayo ng request sa AI na may ilang fine-tuning parameters
- **Kinukuha** natin ang aktwal na response text mula sa lahat ng data na bumalik
### Pag-unawa sa Message Roles: Ang AI Conversation Framework
Ang mga usapan sa AI ay gumagamit ng isang partikular na istruktura na may iba't ibang "roles" na may natatanging layunin:
```python
messages=[
{
"role": "system",
"content": "You are a helpful assistant who explains things simply."
},
{
"role": "user",
"content": "What is machine learning?"
}
]
```
**Isipin ito na parang pagdidirekta ng isang play:**
- **System role**: Parang stage directions para sa isang aktor – sinasabi nito sa AI kung paano kumilos, anong personalidad ang dapat mayroon, at kung paano sumagot
- **User role**: Ang aktwal na tanong o mensahe mula sa taong gumagamit ng iyong aplikasyon
- **Assistant role**: Ang sagot ng AI (hindi mo ito ipinapadala, ngunit lumalabas ito sa history ng usapan)
**Real-world analogy**: Isipin na ipinakikilala mo ang isang kaibigan sa isang tao sa party:
- **System message**: "Ito ang kaibigan kong si Sarah, isa siyang doktor na mahusay magpaliwanag ng mga konsepto sa medisina sa simpleng paraan"
- **User message**: "Paano gumagana ang mga bakuna?"
- **Assistant response**: Sumagot si Sarah bilang isang magiliw na doktor, hindi bilang abogado o chef
### Pag-unawa sa AI Parameters: Fine-Tuning Response Behavior
Ang mga numerical parameters sa AI API calls ay kumokontrol kung paano bumubuo ng mga sagot ang model. Ang mga setting na ito ay nagbibigay-daan sa iyo na i-adjust ang ugali ng AI para sa iba't ibang use cases:
#### Temperature (0.0 hanggang 2.0): Ang Creativity Dial
**Ano ang ginagawa nito**: Kinokontrol kung gaano ka-creative o predictable ang mga sagot ng AI.
**Isipin ito na parang antas ng improvisation ng isang jazz musician:**
- **Temperature = 0.1**: Tumutugtog ng eksaktong parehong melody sa bawat pagkakataon (sobrang predictable)
- **Temperature = 0.7**: Nagdadagdag ng ilang tasteful na variation habang nananatiling pamilyar (balanced creativity)
- **Temperature = 1.5**: Buong experimental jazz na may mga hindi inaasahang liko (sobrang unpredictable)
```python
# Very predictable responses (good for factual questions)
response = client.chat.completions.create(
messages=[{"role": "user", "content": "What is 2+2?"}],
temperature=0.1 # Will almost always say "4"
)
# Creative responses (good for brainstorming)
response = client.chat.completions.create(
messages=[{"role": "user", "content": "Write a creative story opening"}],
temperature=1.2 # Will generate unique, unexpected stories
)
```
#### Max Tokens (1 hanggang 4096+): Ang Response Length Controller
**Ano ang ginagawa nito**: Naglalagay ng limitasyon sa haba ng sagot ng AI.
**Isipin ang tokens na halos katumbas ng mga salita** (mga 1 token = 0.75 na salita sa Ingles):
- **max_tokens=50**: Maikli at direkta (parang text message)
- **max_tokens=500**: Isang magandang talata o dalawa
- **max_tokens=2000**: Isang detalyadong paliwanag na may mga halimbawa
```python
# Short, concise answers
response = client.chat.completions.create(
messages=[{"role": "user", "content": "Explain JavaScript"}],
max_tokens=100 # Forces a brief explanation
)
# Detailed, comprehensive answers
response = client.chat.completions.create(
messages=[{"role": "user", "content": "Explain JavaScript"}],
max_tokens=1500 # Allows for detailed explanations with examples
)
```
#### Top_p (0.0 hanggang 1.0): Ang Focus Parameter
**Ano ang ginagawa nito**: Kinokontrol kung gaano ka-focus ang AI sa mga pinaka-malamang na sagot.
**Isipin ang AI na may napakalaking bokabularyo, niraranggo batay sa kung gaano ka-malamang ang bawat salita:**
- **top_p=0.1**: Tanging isinasaalang-alang ang top 10% na pinaka-malamang na mga salita (sobrang focus)
- **top_p=0.9**: Isinasaalang-alang ang 90% ng mga posibleng salita (mas creative)
- **top_p=1.0**: Isinasaalang-alang ang lahat (maximum variety)
**Halimbawa**: Kung tatanungin mo "Ang langit ay karaniwang..."
- **Mababang top_p**: Halos tiyak na sasabihin "asul"
- **Mataas na top_p**: Maaaring sabihin "asul", "maulap", "malawak", "nagbabago", "maganda", atbp.
### Pagsasama-sama: Mga Kombinasyon ng Parameter para sa Iba't ibang Use Cases
```python
# For factual, consistent answers (like a documentation bot)
factual_params = {
"temperature": 0.2,
"max_tokens": 300,
"top_p": 0.3
}
# For creative writing assistance
creative_params = {
"temperature": 1.1,
"max_tokens": 1000,
"top_p": 0.9
}
# For conversational, helpful responses (balanced)
conversational_params = {
"temperature": 0.7,
"max_tokens": 500,
"top_p": 0.8
}
```
**Pag-unawa kung bakit mahalaga ang mga parameter na ito**: Ang iba't ibang aplikasyon ay nangangailangan ng iba't ibang uri ng sagot. Ang customer service bot ay dapat na consistent at factual (mababang temperature), habang ang creative writing assistant ay dapat na imaginative at varied (mataas na temperature). Ang pag-unawa sa mga parameter na ito ay nagbibigay sa iyo ng kontrol sa personalidad at istilo ng sagot ng iyong AI.
```
**Here's what's happening in this code:**
- **We import** the tools we need: `os` for reading environment variables and `OpenAI` for talking to the AI
- **We set up** the OpenAI client to point to GitHub's AI servers instead of OpenAI directly
- **We authenticate** using a special GitHub token (more on that in a minute!)
- **We structure** our conversation with different "roles" – think of it like setting the scene for a play
- **We send** our request to the AI with some fine-tuning parameters
- **We extract** the actual response text from all the data that comes back
> 🔐 **Security Note**: Never hardcode API keys in your source code! Always use environment variables to store sensitive credentials like your `GITHUB_TOKEN`.
### Creating a Reusable AI Function
Let's refactor this code into a clean, reusable function that we can easily integrate into our web application:
```python
import asyncio
from openai import AsyncOpenAI
# Use AsyncOpenAI for better performance
client = AsyncOpenAI(
base_url="https://models.github.ai/inference",
api_key=os.environ["GITHUB_TOKEN"],
)
async def call_llm_async(prompt: str, system_message: str = "You are a helpful assistant."):
"""
Sends a prompt to the AI model asynchronously and returns the response.
Args:
prompt: The user's question or message
system_message: Instructions that define the AI's behavior and personality
Returns:
str: The AI's response to the prompt
"""
try:
response = await client.chat.completions.create(
messages=[
{
"role": "system",
"content": system_message,
},
{
"role": "user",
"content": prompt,
}
],
model="openai/gpt-4o-mini",
temperature=1,
max_tokens=4096,
top_p=1
)
return response.choices[0].message.content
except Exception as e:
logger.error(f"AI API error: {str(e)}")
return "I'm sorry, I'm having trouble processing your request right now."
# Backward compatibility function for synchronous calls
def call_llm(prompt: str, system_message: str = "You are a helpful assistant."):
"""Synchronous wrapper for async AI calls."""
return asyncio.run(call_llm_async(prompt, system_message))
```
**Pag-unawa sa pinahusay na function na ito:**
- **Tumatanggap** ng dalawang parameter: ang prompt ng user at isang optional na system message
- **Nagbibigay** ng default na system message para sa pangkalahatang assistant behavior
- **Gumagamit** ng tamang Python type hints para sa mas mahusay na dokumentasyon ng code
- **Nagbabalik** ng response content lamang, na ginagawang madali itong gamitin sa ating web API
- **Pinapanatili** ang parehong model parameters para sa consistent na AI behavior
### Ang Magic ng System Prompts: Pag-program ng AI Personality
Kung ang mga parameter ang kumokontrol kung paano mag-isip ang AI, ang system prompts ang kumokontrol kung sino ang iniisip ng AI na siya. Isa ito sa mga pinakakapanapanabik na bahagi ng pagtatrabaho sa AI – parang binibigyan mo ang AI ng kumpletong personalidad, antas ng expertise, at istilo ng komunikasyon.
**Isipin ang system prompts na parang pag-cast ng iba't ibang aktor para sa iba't ibang role**: Sa halip na magkaroon ng isang generic na assistant, maaari kang lumikha ng mga espesyal na eksperto para sa iba't ibang sitwasyon. Kailangan mo ba ng pasensyosong guro? Isang creative brainstorming partner? Isang no-nonsense na business advisor? Palitan lang ang system prompt!
#### Bakit Napakalakas ng System Prompts
Narito ang kamangha-manghang bahagi: Ang mga AI model ay na-train sa napakaraming usapan kung saan ang mga tao ay nag-a-adopt ng iba't ibang role at antas ng expertise. Kapag binigyan mo ang AI ng isang partikular na role, parang pinipindot mo ang isang switch na nag-a-activate sa lahat ng natutunang pattern.
**Parang method acting para sa AI**: Sabihin sa isang aktor "ikaw ay isang matalinong propesor" at panoorin kung paano nila awtomatikong ina-adjust ang kanilang postura, bokabularyo, at kilos. Ang AI ay gumagawa ng isang bagay na kahanga-hanga na katulad nito gamit ang mga pattern ng wika.
#### Paggawa ng Epektibong System Prompts: Ang Art at Science
**Ang anatomy ng isang mahusay na system prompt:**
1. **Role/Identity**: Sino ang AI?
2. **Expertise**: Ano ang alam nila?
3. **Communication style**: Paano sila magsalita?
4. **Specific instructions**: Ano ang dapat nilang pagtuunan?
```python
# ❌ Vague system prompt
"You are helpful."
# ✅ Detailed, effective system prompt
"You are Dr. Sarah Chen, a senior software engineer with 15 years of experience at major tech companies. You explain programming concepts using real-world analogies and always provide practical examples. You're patient with beginners and enthusiastic about helping them understand complex topics."
```
#### Mga Halimbawa ng System Prompt na may Konteksto
Tingnan natin kung paano ang iba't ibang system prompts ay lumilikha ng ganap na magkakaibang personalidad ng AI:
```python
# Example 1: The Patient Teacher
teacher_prompt = """
You are an experienced programming instructor who has taught thousands of students.
You break down complex concepts into simple steps, use analogies from everyday life,
and always check if the student understands before moving on. You're encouraging
and never make students feel bad for not knowing something.
"""
# Example 2: The Creative Collaborator
creative_prompt = """
You are a creative writing partner who loves brainstorming wild ideas. You're
enthusiastic, imaginative, and always build on the user's ideas rather than
replacing them. You ask thought-provoking questions to spark creativity and
offer unexpected perspectives that make stories more interesting.
"""
# Example 3: The Strategic Business Advisor
business_prompt = """
You are a strategic business consultant with an MBA and 20 years of experience
helping startups scale. You think in frameworks, provide structured advice,
and always consider both short-term tactics and long-term strategy. You ask
probing questions to understand the full business context before giving advice.
"""
```
#### Pagkakita ng System Prompts sa Aksyon
Subukan natin ang parehong tanong gamit ang iba't ibang system prompts upang makita ang dramatikong pagkakaiba:
**Tanong**: "Paano ko hahawakan ang user authentication sa aking web app?"
```python
# With teacher prompt:
teacher_response = call_llm(
"How do I handle user authentication in my web app?",
teacher_prompt
)
# Typical response: "Great question! Let's break authentication down into simple steps.
# Think of it like a nightclub bouncer checking IDs..."
# With business prompt:
business_response = call_llm(
"How do I handle user authentication in my web app?",
business_prompt
)
# Typical response: "From a strategic perspective, authentication is crucial for user
# trust and regulatory compliance. Let me outline a framework considering security,
# user experience, and scalability..."
```
#### Advanced System Prompt Techniques
**1. Context Setting**: Bigyan ang AI ng background information
```python
system_prompt = """
You are helping a junior developer who just started their first job at a startup.
They know basic HTML/CSS/JavaScript but are new to backend development and databases.
Be encouraging and explain things step-by-step without being condescending.
"""
```
**2. Output Formatting**: Sabihin sa AI kung paano istrukturahin ang mga sagot
```python
system_prompt = """
You are a technical mentor. Always structure your responses as:
1. Quick Answer (1-2 sentences)
2. Detailed Explanation
3. Code Example
4. Common Pitfalls to Avoid
5. Next Steps for Learning
"""
```
**3. Constraint Setting**: Tukuyin kung ano ang hindi dapat gawin ng AI
```python
system_prompt = """
You are a coding tutor focused on teaching best practices. Never write complete
solutions for the user - instead, guide them with hints and questions so they
learn by doing. Always explain the 'why' behind coding decisions.
"""
```
#### Bakit Mahalaga Ito para sa Iyong Chat Assistant
Ang pag-unawa sa system prompts ay nagbibigay sa iyo ng kamangha-manghang kapangyarihan upang lumikha ng mga espesyal na AI assistants:
- **Customer service bot**: Matulungin, pasensyoso, may alam sa mga polisiya
- **Learning tutor**: Nakaka-encourage, step-by-step, sinusuri ang pag-unawa
- **Creative partner**: Imaginative, nagbuo ng mga ideya, nagtatanong ng "paano kung?"
- **Technical expert**: Precise, detalyado, may kamalayan sa seguridad
**Ang pangunahing insight**: Hindi ka lang tumatawag sa isang AI API – lumilikha ka ng custom na AI personality na nagsisilbi sa iyong partikular na use case. Ito ang nagpaparamdam sa mga modernong AI application na tailored at kapaki-pakinabang sa halip na generic.
## Pagbuo ng Web API gamit ang FastAPI: Ang Iyong High-Performance AI Communication Hub
Ngayon, gawin natin ang backend na kumokonekta sa iyong frontend sa mga AI services. Gagamit tayo ng FastAPI, isang modernong Python framework na mahusay sa paggawa ng mga API para sa AI applications.
Ang FastAPI ay nag-aalok ng ilang mga benepisyo para sa ganitong uri ng proyekto: built-in async support para sa paghawak ng sabay-sabay na mga request, automatic API documentation generation, at mahusay na performance. Ang iyong FastAPI server ay nagsisilbing tagapamagitan na tumatanggap ng mga request mula sa frontend, nakikipag-usap sa mga AI services, at nagbabalik ng mga formatted na sagot.
### Bakit FastAPI para sa AI Applications?
Maaaring iniisip mo: "Hindi ba pwedeng direktang tumawag sa AI mula sa aking frontend JavaScript?" o "Bakit FastAPI sa halip na Flask o Django?" Magandang tanong!
**Narito kung bakit perpekto ang FastAPI para sa ginagawa natin:**
- **Async by default**: Kayang mag-handle ng maraming AI requests nang sabay-sabay nang hindi natatambakan
- **Automatic docs**: Bisitahin ang `/docs` para sa maganda at interactive na API documentation page nang libre
- **Built-in validation**: Nahuhuli ang mga error bago pa ito magdulot ng problema
- **Napakabilis**: Isa sa pinakamabilis na Python frameworks
- **Modern Python**: Ginagamit ang pinakabagong features ng Python
**At narito kung bakit kailangan natin ng backend:**
**Seguridad**: Ang iyong AI API key ay parang password – kung ilalagay mo ito sa frontend JavaScript, maaaring makita ito ng sinuman na tumingin sa source code ng iyong website at gamitin ang iyong AI credits. Ang backend ang nagtatago ng mga sensitibong credentials.
**Rate Limiting & Control**: Sa backend, makokontrol mo kung gaano kadalas maaaring mag-request ang mga user, mag-implement ng user authentication, at magdagdag ng logging para sa pagsubaybay sa paggamit.
**Data Processing**: Maaaring gusto mong i-save ang mga pag-uusap, i-filter ang hindi angkop na content, o pagsamahin ang iba't ibang AI services. Sa backend ginagawa ang ganitong logic.
**Ang arkitektura ay kahalintulad ng client-server model:**
- **Frontend**: Layer para sa user interface at interaksyon
- **Backend API**: Layer para sa pagproseso ng request at routing
- **AI Service**: Panlabas na computation at response generation
- **Environment Variables**: Secure na storage para sa configuration at credentials
### Pag-unawa sa Request-Response Flow
Sundan natin ang nangyayari kapag nagpadala ng mensahe ang isang user:
```mermaid
sequenceDiagram
participant User as 👤 User
participant Frontend as 🌐 Frontend
participant API as 🔧 FastAPI Server
participant AI as 🤖 AI Service
User->>Frontend: Types "Hello AI!"
Frontend->>API: POST /hello {"message": "Hello AI!"}
Note over API: Validates request
Adds system prompt
API->>AI: Sends formatted request
AI->>API: Returns AI response
Note over API: Processes response
Logs conversation
API->>Frontend: {"response": "Hello! How can I help?"}
Frontend->>User: Displays AI message
```
**Pag-unawa sa bawat hakbang:**
1. **User interaction**: Nagta-type ang tao sa chat interface
2. **Frontend processing**: Kinukuha ng JavaScript ang input at inaayos ito bilang JSON
3. **API validation**: Awtomatikong sine-check ng FastAPI ang request gamit ang Pydantic models
4. **AI integration**: Idinadagdag ng backend ang context (system prompt) at tinatawag ang AI service
5. **Response handling**: Tinatanggap ng API ang AI response at maaaring baguhin ito kung kinakailangan
6. **Frontend display**: Ipinapakita ng JavaScript ang response sa chat interface
### Pag-unawa sa API Architecture
```mermaid
sequenceDiagram
participant Frontend
participant FastAPI
participant AI Function
participant GitHub Models
Frontend->>FastAPI: POST /hello {"message": "Hello AI!"}
FastAPI->>AI Function: call_llm(message, system_prompt)
AI Function->>GitHub Models: API request
GitHub Models->>AI Function: AI response
AI Function->>FastAPI: response text
FastAPI->>Frontend: {"response": "Hello! How can I help?"}
```
### Paglikha ng FastAPI Application
Gawin natin ang API step by step. Gumawa ng file na tinatawag na `api.py` gamit ang sumusunod na FastAPI code:
```python
# api.py
from fastapi import FastAPI, HTTPException
from fastapi.middleware.cors import CORSMiddleware
from pydantic import BaseModel
from llm import call_llm
import logging
# Configure logging
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)
# Create FastAPI application
app = FastAPI(
title="AI Chat API",
description="A high-performance API for AI-powered chat applications",
version="1.0.0"
)
# Configure CORS
app.add_middleware(
CORSMiddleware,
allow_origins=["*"], # Configure appropriately for production
allow_credentials=True,
allow_methods=["*"],
allow_headers=["*"],
)
# Pydantic models for request/response validation
class ChatMessage(BaseModel):
message: str
class ChatResponse(BaseModel):
response: str
@app.get("/")
async def root():
"""Root endpoint providing API information."""
return {
"message": "Welcome to the AI Chat API",
"docs": "/docs",
"health": "/health"
}
@app.get("/health")
async def health_check():
"""Health check endpoint."""
return {"status": "healthy", "service": "ai-chat-api"}
@app.post("/hello", response_model=ChatResponse)
async def chat_endpoint(chat_message: ChatMessage):
"""Main chat endpoint that processes messages and returns AI responses."""
try:
# Extract and validate message
message = chat_message.message.strip()
if not message:
raise HTTPException(status_code=400, detail="Message cannot be empty")
logger.info(f"Processing message: {message[:50]}...")
# Call AI service (note: call_llm should be made async for better performance)
ai_response = await call_llm_async(message, "You are a helpful and friendly assistant.")
logger.info("AI response generated successfully")
return ChatResponse(response=ai_response)
except HTTPException:
raise
except Exception as e:
logger.error(f"Error processing chat message: {str(e)}")
raise HTTPException(status_code=500, detail="Internal server error")
if __name__ == "__main__":
import uvicorn
uvicorn.run(app, host="0.0.0.0", port=5000, reload=True)
```
**Pag-unawa sa FastAPI implementation:**
- **Imports** FastAPI para sa modernong web framework functionality at Pydantic para sa data validation
- **Nagbibigay** ng awtomatikong API documentation (makikita sa `/docs` kapag tumatakbo ang server)
- **Nag-enable** ng CORS middleware para payagan ang frontend requests mula sa iba't ibang origins
- **Nagde-define** ng Pydantic models para sa awtomatikong request/response validation at documentation
- **Gumagamit** ng async endpoints para sa mas mahusay na performance sa sabay-sabay na requests
- **Nag-iimplement** ng tamang HTTP status codes at error handling gamit ang HTTPException
- **Naglalaman** ng structured logging para sa monitoring at debugging
- **Nagbibigay** ng health check endpoint para sa pagsubaybay sa status ng serbisyo
**Mga pangunahing bentahe ng FastAPI kumpara sa tradisyunal na frameworks:**
- **Awtomatikong validation**: Tinitiyak ng Pydantic models ang integridad ng data bago ito iproseso
- **Interactive docs**: Bisitahin ang `/docs` para sa auto-generated, testable API documentation
- **Type safety**: Ang Python type hints ay nakakaiwas sa runtime errors at nagpapabuti sa kalidad ng code
- **Async support**: Kayang mag-handle ng maraming AI requests nang sabay-sabay
- **Performance**: Mas mabilis ang request processing para sa real-time applications
### Pag-unawa sa CORS: Ang Security Guard ng Web
Ang CORS (Cross-Origin Resource Sharing) ay parang security guard sa isang gusali na nagche-check kung pinapayagan ang mga bisita na pumasok. Alamin natin kung bakit ito mahalaga at paano ito nakakaapekto sa iyong application.
#### Ano ang CORS at Bakit Ito Umiiral?
**Ang Problema**: Isipin kung ang anumang website ay maaaring mag-request sa website ng iyong bangko nang walang pahintulot mo. Isang malaking security issue iyon! Pinipigilan ito ng mga browser sa pamamagitan ng "Same-Origin Policy."
**Same-Origin Policy**: Pinapayagan lamang ng mga browser ang mga web page na mag-request sa parehong domain, port, at protocol kung saan sila na-load.
**Real-world analogy**: Parang security sa apartment building – ang mga residente (same origin) lang ang maaaring pumasok sa gusali nang default. Kung gusto mong papasukin ang kaibigan (different origin), kailangan mong sabihin sa security na okay lang.
#### CORS sa Iyong Development Environment
Sa development, ang iyong frontend at backend ay tumatakbo sa iba't ibang ports:
- Frontend: `http://localhost:3000` (o file:// kung direktang binuksan ang HTML)
- Backend: `http://localhost:5000`
Ang mga ito ay itinuturing na "different origins" kahit na nasa parehong computer!
```python
from fastapi.middleware.cors import CORSMiddleware
app = FastAPI(__name__)
CORS(app) # This tells browsers: "It's okay for other origins to make requests to this API"
```
**Ano ang ginagawa ng CORS configuration sa praktika:**
- **Nagdadagdag** ng espesyal na HTTP headers sa API responses na nagsasabi sa mga browser "pinapayagan ang cross-origin request na ito"
- **Nagha-handle** ng "preflight" requests (minsan sine-check ng mga browser ang permissions bago magpadala ng aktwal na request)
- **Pinipigilan** ang nakakainis na "blocked by CORS policy" error sa iyong browser console
#### CORS Security: Development vs Production
```python
# 🚨 Development: Allows ALL origins (convenient but insecure)
CORS(app)
# ✅ Production: Only allow your specific frontend domain
CORS(app, origins=["https://yourdomain.com", "https://www.yourdomain.com"])
# 🔒 Advanced: Different origins for different environments
if app.debug: # Development mode
CORS(app, origins=["http://localhost:3000", "http://127.0.0.1:3000"])
else: # Production mode
CORS(app, origins=["https://yourdomain.com"])
```
**Bakit ito mahalaga**: Sa development, ang `CORS(app)` ay parang iniwan mong bukas ang pintuan – maginhawa pero hindi secure. Sa production, gusto mong tukuyin kung aling mga website lang ang maaaring makipag-usap sa iyong API.
#### Karaniwang CORS Scenarios at Solusyon
| Scenario | Problema | Solusyon |
|----------|----------|----------|
| **Local Development** | Hindi maabot ng frontend ang backend | Magdagdag ng CORSMiddleware sa FastAPI |
| **GitHub Pages + Heroku** | Hindi maabot ng deployed frontend ang API | Idagdag ang URL ng GitHub Pages sa CORS origins |
| **Custom Domain** | CORS errors sa production | I-update ang CORS origins para tumugma sa iyong domain |
| **Mobile App** | Hindi maabot ng app ang web API | Idagdag ang domain ng iyong app o gamitin ang `*` nang maingat |
**Pro tip**: Maaari mong i-check ang CORS headers sa Developer Tools ng iyong browser sa ilalim ng Network tab. Hanapin ang headers tulad ng `Access-Control-Allow-Origin` sa response.
### Error Handling at Validation
Pansinin kung paano ang API natin ay may tamang error handling:
```python
# Validate that we received a message
if not message:
return jsonify({"error": "Message field is required"}), 400
```
**Mga pangunahing prinsipyo ng validation:**
- **Sine-check** ang mga kinakailangang field bago iproseso ang requests
- **Nagbabalik** ng makabuluhang error messages sa JSON format
- **Gumagamit** ng tamang HTTP status codes (400 para sa bad requests)
- **Nagbibigay** ng malinaw na feedback para matulungan ang mga frontend developers na mag-debug ng issues
## Pag-setup at Pagpapatakbo ng Iyong Backend
Ngayon na mayroon na tayong AI integration at FastAPI server, simulan na natin ang lahat. Ang proseso ng setup ay kinabibilangan ng pag-install ng Python dependencies, pag-configure ng environment variables, at pagsisimula ng development server.
### Python Environment Setup
I-setup natin ang iyong Python development environment. Ang virtual environments ay parang compartmentalized approach ng Manhattan Project – bawat proyekto ay may sariling isolated space na may partikular na tools at dependencies, na pumipigil sa conflicts sa pagitan ng iba't ibang proyekto.
```bash
# Navigate to your backend directory
cd backend
# Create a virtual environment (like creating a clean room for your project)
python -m venv venv
# Activate it (Linux/Mac)
source ./venv/bin/activate
# On Windows, use:
# venv\Scripts\activate
# Install the good stuff
pip install openai fastapi uvicorn python-dotenv
```
**Ano ang ginawa natin:**
- **Gumawa** ng sarili nating Python bubble kung saan maaari tayong mag-install ng packages nang hindi naaapektuhan ang iba
- **In-activate** ito para malaman ng terminal na gamitin ang partikular na environment na ito
- **Nag-install** ng essentials: OpenAI para sa AI magic, FastAPI para sa web API, Uvicorn para sa pag-run nito, at python-dotenv para sa secure secrets management
**Mga pangunahing dependencies na ipinaliwanag:**
- **FastAPI**: Modernong, mabilis na web framework na may awtomatikong API documentation
- **Uvicorn**: Napakabilis na ASGI server na nagpapatakbo ng FastAPI applications
- **OpenAI**: Opisyal na library para sa GitHub Models at OpenAI API integration
- **python-dotenv**: Secure na pag-load ng environment variables mula sa .env files
### Environment Configuration: Panatilihing Ligtas ang Mga Sekreto
Bago natin simulan ang API, pag-usapan natin ang isa sa pinakamahalagang aral sa web development: paano panatilihing talagang sikreto ang iyong mga sekreto. Ang environment variables ay parang secure vault na ang iyong application lang ang may access.
#### Ano ang Environment Variables?
**Isipin ang environment variables na parang safety deposit box** – inilalagay mo ang mahalagang bagay doon, at ikaw (at ang iyong app) lang ang may susi para makuha ito. Sa halip na isulat ang sensitibong impormasyon nang direkta sa iyong code (kung saan makikita ito ng kahit sino), itinatago mo ito nang ligtas sa environment.
**Narito ang pagkakaiba:**
- **Maling paraan**: Isinusulat ang password sa sticky note at inilalagay ito sa monitor
- **Tamang paraan**: Itinatago ang password sa secure password manager na ikaw lang ang may access
#### Bakit Mahalaga ang Environment Variables
```python
# 🚨 NEVER DO THIS - API key visible to everyone
client = OpenAI(
api_key="ghp_1234567890abcdef...", # Anyone can steal this!
base_url="https://models.github.ai/inference"
)
# ✅ DO THIS - API key stored securely
client = OpenAI(
api_key=os.environ["GITHUB_TOKEN"], # Only your app can access this
base_url="https://models.github.ai/inference"
)
```
**Ano ang nangyayari kapag hardcoded ang mga sekreto:**
1. **Version control exposure**: Makikita ng sinuman na may access sa iyong Git repository ang iyong API key
2. **Public repositories**: Kung i-push mo sa GitHub, makikita ng buong internet ang iyong key
3. **Team sharing**: Ang ibang developers na nagtatrabaho sa iyong proyekto ay magkakaroon ng access sa iyong personal API key
4. **Security breaches**: Kung may magnakaw ng iyong API key, magagamit nila ang iyong AI credits
#### Pag-setup ng Iyong Environment File
Gumawa ng `.env` file sa iyong backend directory. Ang file na ito ang nagtatago ng iyong mga sekreto nang lokal:
```bash
# .env file - This should NEVER be committed to Git
GITHUB_TOKEN=your_github_personal_access_token_here
FASTAPI_DEBUG=True
ENVIRONMENT=development
```
**Pag-unawa sa .env file:**
- **Isang sekreto kada linya** sa `KEY=value` format
- **Walang spaces** sa paligid ng equals sign
- **Hindi kailangan ng quotes** sa paligid ng values (karaniwan)
- **Comments** nagsisimula sa `#`
#### Paglikha ng Iyong GitHub Personal Access Token
Ang iyong GitHub token ay parang espesyal na password na nagbibigay ng pahintulot sa iyong application na gamitin ang GitHub's AI services:
**Step-by-step token creation:**
1. **Pumunta sa GitHub Settings** → Developer settings → Personal access tokens → Tokens (classic)
2. **I-click ang "Generate new token (classic)"**
3. **Itakda ang expiration** (30 araw para sa testing, mas mahaba para sa production)
4. **Piliin ang scopes**: I-check ang "repo" at iba pang permissions na kailangan mo
5. **I-generate ang token** at kopyahin ito kaagad (hindi mo na ito makikita ulit!)
6. **I-paste sa iyong .env file**
```bash
# Example of what your token looks like (this is fake!)
GITHUB_TOKEN=ghp_1A2B3C4D5E6F7G8H9I0J1K2L3M4N5O6P7Q8R
```
#### Pag-load ng Environment Variables sa Python
```python
import os
from dotenv import load_dotenv
# Load environment variables from .env file
load_dotenv()
# Now you can access them securely
api_key = os.environ.get("GITHUB_TOKEN")
if not api_key:
raise ValueError("GITHUB_TOKEN not found in environment variables!")
client = OpenAI(
api_key=api_key,
base_url="https://models.github.ai/inference"
)
```
**Ano ang ginagawa ng code na ito:**
- **Naglo-load** ng iyong .env file at ginagawang available ang variables sa Python
- **Sine-check** kung umiiral ang kinakailangang token (magandang error handling!)
- **Nag-raise** ng malinaw na error kung nawawala ang token
- **Ginagamit** ang token nang ligtas nang hindi ito inilalantad sa code
#### Git Security: Ang .gitignore File
Ang iyong `.gitignore` file ang nagsasabi sa Git kung aling mga file ang hindi kailanman dapat i-track o i-upload:
```bash
# .gitignore - Add these lines
.env
*.env
.env.local
.env.production
__pycache__/
venv/
.vscode/
```
**Bakit ito mahalaga**: Kapag idinagdag mo ang `.env` sa `.gitignore`, i-ignore ito ng Git, na pumipigil sa iyo na aksidenteng ma-upload ang iyong mga sekreto sa GitHub.
#### Iba't Ibang Environments, Iba't Ibang Sekreto
Ang mga propesyonal na application ay gumagamit ng iba't ibang API keys para sa iba't ibang environments:
```bash
# .env.development
GITHUB_TOKEN=your_development_token
DEBUG=True
# .env.production
GITHUB_TOKEN=your_production_token
DEBUG=False
```
**Bakit ito mahalaga**: Ayaw mong maapektuhan ng iyong development experiments ang iyong production AI usage quota, at gusto mo ng iba't ibang security levels para sa iba't ibang environments.
### Pagsisimula ng Iyong Development Server: Pagpapagana ng Iyong FastAPI
Ngayon na ang exciting na bahagi – simulan ang iyong FastAPI development server at makita ang iyong AI integration na gumagana! Ang FastAPI ay gumagamit ng Uvicorn, isang napakabilis na ASGI server na partikular na dinisenyo para sa async Python applications.
#### Pag-unawa sa FastAPI Server Startup Process
```bash
# Method 1: Direct Python execution (includes auto-reload)
python api.py
# Method 2: Using Uvicorn directly (more control)
uvicorn api:app --host 0.0.0.0 --port 5000 --reload
```
Kapag pinatakbo mo ang command na ito, narito ang nangyayari sa likod ng eksena:
**1. I-load ng Python ang iyong FastAPI application**:
- Ini-import ang lahat ng kinakailangang libraries (FastAPI, Pydantic, OpenAI, atbp.)
- I-load ang environment variables mula sa iyong `.env` file
- Gumagawa ng FastAPI application instance na may awtomatikong documentation
**2. I-configure ng Uvicorn ang ASGI server**:
- Nagbi-bind sa port 5000 na may async request handling capabilities
- Nagse-set up ng request routing na may awtomatikong validation
- Nag-enable ng hot reload para sa development (nagre-restart kapag may file changes)
- Gumagawa ng interactive API documentation
**3. Nagsisimulang makinig ang server**:
- Makikita mo sa terminal: `INFO: Uvicorn running on http://0.0.0.0:5000`
- Kayang mag-handle ng maraming sabay-sabay na AI requests ang server
- Handa na ang iyong API na may awtomatikong docs sa `http://localhost:5000/docs`
#### Ano ang Dapat Mong Makita Kapag Gumagana ang Lahat
```bash
$ python api.py
INFO: Will watch for changes in these directories: ['/your/project/path']
INFO: Uvicorn running on http://0.0.0.0:5000 (Press CTRL+C to quit)
INFO: Started reloader process [12345] using WatchFiles
INFO: Started server process [12346]
INFO: Waiting for application startup.
INFO: Application startup complete.
```
**Pag-unawa sa FastAPI output:**
- **Magmo-monitor ng changes**: Auto-reload enabled para sa development
- **Uvicorn running**: Aktibo ang high-performance ASGI server
- **Nagsimula ang reloader process**: File watcher para sa awtomatikong restarts
- **Application startup complete**: Matagumpay na na-initialize ang FastAPI app
- **Interactive docs available**: Bisitahin ang `/docs` para sa awtomatikong API documentation
#### Pagsubok sa Iyong FastAPI: Maraming Makapangyarihang Paraan
Nagbibigay ang FastAPI ng ilang maginhawang paraan para subukan ang iyong API, kabilang ang awtomatikong interactive documentation:
**Paraan 1: Interactive API Documentation (Inirerekomenda)**
1. Buksan ang iyong browser at pumunta sa `http://localhost:5000/docs`
2. Makikita mo ang Swagger UI na may lahat ng iyong endpoints na documented
3. I-click ang `/hello` → "Try it out" → Maglagay ng test message → "Execute"
4. Makikita ang response direkta sa browser na may tamang formatting
**Paraan 2: Basic Browser Test**
1. Pumunta sa `http://localhost:5000` para sa root endpoint
2. Pumunta sa `http://localhost:5000/health` para i-check ang server health
3. Kinukumpirma nito na tumatakbo nang maayos ang iyong FastAPI server
**Paraan 3: Command Line Test (Advanced)**
```bash
# Test with curl (if available)
curl -X POST http://localhost:5000/hello \
-H "Content-Type: application/json" \
-d '{"message": "Hello AI!"}'
# Expected response:
# {"response": "Hello! I'm your AI assistant. How can I help you today?"}
```
**Paraan 4: Python Test Script**
#### Pag-aayos ng Karaniwang Problema sa Startup
| Mensahe ng Error | Ano ang Kahulugan | Paano Ayusin |
|-------------------|-------------------|-------------|
| `ModuleNotFoundError: No module named 'fastapi'` | Hindi naka-install ang FastAPI | Patakbuhin ang `pip install fastapi uvicorn` sa iyong virtual environment |
| `ModuleNotFoundError: No module named 'uvicorn'` | Hindi naka-install ang ASGI server | Patakbuhin ang `pip install uvicorn` sa iyong virtual environment |
| `KeyError: 'GITHUB_TOKEN'` | Hindi natagpuan ang environment variable | Suriin ang iyong `.env` file at ang tawag sa `load_dotenv()` |
| `Address already in use` | Abala ang Port 5000 | Patayin ang ibang proseso na gumagamit ng port 5000 o palitan ang port |
| `ValidationError` | Hindi tugma ang request data sa Pydantic model | Suriin kung ang format ng iyong request ay tumutugma sa inaasahang schema |
| `HTTPException 422` | Hindi maiproseso ang entity | Nabigo ang request validation, suriin ang `/docs` para sa tamang format |
| `OpenAI API error` | Nabigo ang authentication ng AI service | Siguraduhing tama ang iyong GitHub token at may tamang mga pahintulot |
#### Mga Pinakamahusay na Praktika sa Pag-develop
**Hot Reloading**: Ang FastAPI kasama ang Uvicorn ay nagbibigay ng awtomatikong pag-reload kapag nag-save ka ng mga pagbabago sa iyong Python files. Nangangahulugan ito na maaari mong baguhin ang iyong code at agad na subukan nang hindi mano-manong nire-restart.
**Pag-log para sa Pag-develop**: Magdagdag ng logging upang maunawaan ang nangyayari:
**Bakit nakakatulong ang logging**: Sa panahon ng pag-develop, makikita mo nang eksakto kung anong mga request ang pumapasok, kung ano ang tugon ng AI, at kung saan nagkakaroon ng mga error. Mas mabilis ang debugging dahil dito.
### Pag-configure para sa GitHub Codespaces: Madaling Pag-develop sa Cloud
Ang GitHub Codespaces ay parang pagkakaroon ng makapangyarihang development computer sa cloud na maaari mong ma-access mula sa anumang browser. Kung nagtatrabaho ka sa Codespaces, may ilang karagdagang hakbang upang gawing accessible ang iyong backend sa iyong frontend.
#### Pag-unawa sa Networking ng Codespaces
Sa lokal na development environment, lahat ay tumatakbo sa parehong computer:
- Backend: `http://localhost:5000`
- Frontend: `http://localhost:3000` (o file://)
Sa Codespaces, ang iyong development environment ay tumatakbo sa mga server ng GitHub, kaya ang "localhost" ay may ibang kahulugan. Awtomatikong lumilikha ang GitHub ng mga pampublikong URL para sa iyong mga serbisyo, ngunit kailangan mong i-configure ang mga ito nang maayos.
#### Hakbang-hakbang na Configuration ng Codespaces
**1. Simulan ang iyong backend server**:
Makikita mo ang pamilyar na FastAPI/Uvicorn startup message, ngunit mapapansin mong ito ay tumatakbo sa loob ng Codespace environment.
**2. I-configure ang visibility ng port**:
- Hanapin ang "Ports" tab sa ibabang panel ng VS Code
- Hanapin ang port 5000 sa listahan
- I-right-click ang port 5000
- Piliin ang "Port Visibility" → "Public"
**Bakit gawing pampubliko?** Sa default, ang mga port ng Codespace ay pribado (accessible lamang sa iyo). Ang paggawa nito bilang pampubliko ay magpapahintulot sa iyong frontend (na tumatakbo sa browser) na makipag-ugnayan sa iyong backend.
**3. Kunin ang iyong pampublikong URL**:
Pagkatapos gawing pampubliko ang port, makakakita ka ng URL tulad ng:
**4. I-update ang configuration ng iyong frontend**:
#### Pag-unawa sa mga URL ng Codespace
Ang mga URL ng Codespace ay sumusunod sa isang predictable na pattern:
**Pag-unawa sa istruktura**:
- `codespace-name`: Isang natatanging identifier para sa iyong Codespace (karaniwang kasama ang iyong username)
- `port`: Ang numero ng port kung saan tumatakbo ang iyong serbisyo (5000 para sa aming FastAPI app)
- `app.github.dev`: Domain ng GitHub para sa mga application ng Codespace
#### Pagsubok sa Iyong Setup ng Codespace
**1. Subukan ang backend nang direkta**:
Buksan ang iyong pampublikong URL sa isang bagong tab ng browser. Makikita mo:
**2. Subukan gamit ang browser developer tools**:
#### Codespaces vs Lokal na Pag-develop
| Aspeto | Lokal na Pag-develop | GitHub Codespaces |
|--------|-----------------------|-------------------|
| **Oras ng Setup** | Mas matagal (install Python, dependencies) | Agad (pre-configured environment) |
| **URL Access** | `http://localhost:5000` | `https://xyz-5000.app.github.dev` |
| **Configuration ng Port** | Awtomatiko | Manu-mano (gawing pampubliko ang mga port) |
| **File Persistence** | Lokal na makina | GitHub repository |
| **Collaborative** | Mahirap ibahagi ang environment | Madaling ibahagi ang link ng Codespace |
| **Internet Dependency** | Para lamang sa AI API calls | Kinakailangan para sa lahat |
#### Mga Tip sa Pag-develop gamit ang Codespaces
**Environment Variables sa Codespaces**:
Ang iyong `.env` file ay gumagana nang pareho sa Codespaces, ngunit maaari ka ring mag-set ng environment variables nang direkta sa Codespace.
**Pamamahala ng Port**:
- Awtomatikong nadedetect ng Codespaces kapag ang iyong application ay nagsimulang makinig sa isang port
- Maaari kang mag-forward ng maraming port nang sabay-sabay (kapaki-pakinabang kung magdadagdag ka ng database sa hinaharap)
- Ang mga port ay nananatiling accessible hangga't tumatakbo ang iyong Codespace
**Workflow ng Pag-develop**:
1. Gumawa ng mga pagbabago sa code sa VS Code
2. Awtomatikong nagre-reload ang FastAPI (salamat sa reload mode ng Uvicorn)
3. Agad na subukan ang mga pagbabago sa pamamagitan ng pampublikong URL
4. I-commit at i-push kapag handa na
> 💡 **Pro Tip**: I-bookmark ang iyong Codespace backend URL sa panahon ng pag-develop. Dahil ang mga pangalan ng Codespace ay stable, hindi magbabago ang URL hangga't ginagamit mo ang parehong Codespace.
## Paglikha ng Frontend Chat Interface: Kung Saan Nagkikita ang Tao at AI
Ngayon ay gagawa tayo ng user interface – ang bahagi na tumutukoy kung paano nakikipag-ugnayan ang mga tao sa iyong AI assistant. Tulad ng disenyo ng orihinal na interface ng iPhone, magpo-focus tayo sa paggawa ng kumplikadong teknolohiya na intuitive at natural gamitin.
### Pag-unawa sa Modernong Arkitektura ng Frontend
Ang ating chat interface ay magiging tinatawag na "Single Page Application" o SPA. Sa halip na ang lumang paraan kung saan bawat click ay naglo-load ng bagong pahina, ang ating app ay nag-a-update nang maayos at instant:
**Lumang websites**: Parang nagbabasa ng pisikal na libro – nag-flip ka sa ganap na bagong mga pahina
**Ang ating chat app**: Parang gumagamit ng iyong telepono – lahat ay dumadaloy at nag-a-update nang seamless
### Ang Tatlong Haligi ng Frontend Development
Ang bawat frontend application – mula sa simpleng websites hanggang sa mga kumplikadong apps tulad ng Discord o Slack – ay binubuo ng tatlong pangunahing teknolohiya. Isipin ang mga ito bilang pundasyon ng lahat ng nakikita at nakikipag-ugnayan sa web:
**HTML (Istruktura)**: Ito ang iyong pundasyon
- Nagpapasya kung anong mga elemento ang umiiral (mga button, text areas, containers)
- Nagbibigay ng kahulugan sa content (ito ay header, ito ay form, atbp.)
- Lumilikha ng pangunahing istruktura na binubuo ng lahat ng iba pa
**CSS (Presentasyon)**: Ito ang iyong interior designer
- Ginagawang maganda ang lahat (kulay, font, layout)
- Nag-a-adjust sa iba't ibang screen sizes (telepono vs laptop vs tablet)
- Lumilikha ng smooth animations at visual feedback
**JavaScript (Pag-uugali)**: Ito ang iyong utak
- Tumutugon sa ginagawa ng mga user (clicks, typing, scrolling)
- Nakikipag-usap sa iyong backend at nag-a-update ng pahina
- Ginagawang interactive at dynamic ang lahat
**Isipin ito tulad ng architectural design:**
- **HTML**: Ang structural blueprint (nagde-define ng spaces at relationships)
- **CSS**: Ang aesthetic at environmental design (visual style at user experience)
- **JavaScript**: Ang mechanical systems (functionality at interactivity)
### Bakit Mahalaga ang Modernong Arkitektura ng JavaScript
Ang ating chat application ay gagamit ng modernong JavaScript patterns na makikita mo sa mga propesyonal na application. Ang pag-unawa sa mga konseptong ito ay makakatulong sa iyo habang lumalago ka bilang developer:
**Class-Based Architecture**: I-oorganisa natin ang ating code sa mga klase, na parang gumagawa ng blueprint para sa mga object
**Async/Await**: Modernong paraan ng pag-handle ng mga operasyon na tumatagal ng oras (tulad ng API calls)
**Event-Driven Programming**: Ang ating app ay tumutugon sa mga aksyon ng user (clicks, key presses) sa halip na tumakbo sa loop
**DOM Manipulation**: Dinamikong pag-update ng content ng webpage base sa mga interaksyon ng user at mga tugon ng API
### Setup ng Istruktura ng Proyekto
Gumawa ng frontend directory na may ganitong organisadong istruktura:
**Pag-unawa sa arkitektura:**
- **Pinaghihiwalay** ang mga concern sa pagitan ng istruktura (HTML), pag-uugali (JavaScript), at presentasyon (CSS)
- **Pinapanatili** ang simpleng file structure na madaling i-navigate at i-modify
- **Sumusunod** sa mga pinakamahusay na praktika sa web development para sa organisasyon at maintainability
### Paggawa ng HTML Foundation: Semantic Structure para sa Accessibility
Simulan natin sa HTML structure. Ang modernong web development ay nagbibigay-diin sa "semantic HTML" – paggamit ng mga HTML element na malinaw na naglalarawan ng kanilang layunin, hindi lamang ang kanilang hitsura. Ginagawa nitong accessible ang iyong application sa screen readers, search engines, at iba pang tools.
**Bakit mahalaga ang semantic HTML**: Isipin ang pag-describe ng iyong chat app sa isang tao sa telepono. Sasabihin mo "may header na may title, isang pangunahing lugar kung saan lumalabas ang mga conversation, at isang form sa ibaba para sa pag-type ng mga mensahe." Ang semantic HTML ay gumagamit ng mga element na tumutugma sa natural na deskripsyon na ito.
Gumawa ng `index.html` na may ganitong maingat na structured markup:
**Pag-unawa sa bawat HTML element at ang layunin nito:**
#### Istruktura ng Dokumento
- **``**: Sinasabi sa browser na ito ay modernong HTML5
- **``**: Nagsasaad ng wika ng pahina para sa screen readers at translation tools
- **``**: Tinitiyak ang tamang character encoding para sa international text
- **``**: Ginagawang mobile-responsive ang pahina sa pamamagitan ng pag-control sa zoom at scale
#### Semantic Elements
- **``**: Malinaw na tinutukoy ang top section na may title at description
- **``**: Itinalaga ang pangunahing content area (kung saan nagaganap ang mga conversation)
- **`