Initial commit: Fara-7B chat interface

.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.Python
+*.so
+*.dylib
+*.egg
+*.egg-info/
+dist/
+build/
+.env
+.venv
+venv/
+flagged/

DEPLOYMENT_GUIDE.md

@@ -0,0 +1,146 @@
+# 🚀 Deployment Guide for Fara-7B Space
+
+## Quick Start
+
+Your Hugging Face Space is ready to deploy! Follow these steps:
+
+### Step 1: Create a New Space on Hugging Face
+
+1. Go to [huggingface.co/new-space](https://huggingface.co/new-space)
+2. Fill in the details:
+   - **Space name**: `fara-7b-chat` (or any name you prefer)
+   - **License**: MIT
+   - **Select SDK**: Gradio
+   - **Space hardware**: CPU Basic (free) - this is fine since we're using Inference API
+   - **Visibility**: Public or Private (your choice)
+3. Click **Create Space**
+
+### Step 2: Upload Your Files
+
+You have two options:
+
+#### Option A: Git Upload (Recommended)
+
+```bash
+# Navigate to your space folder
+cd "c:/Users/Amir/OneDrive - Digital Health CRC Limited/Projects/url2md/fara-7b-space"
+
+# Initialize git repository
+git init
+git add .
+git commit -m "Initial commit: Fara-7B chat interface"
+
+# Add your HuggingFace Space as remote
+# Replace YOUR_USERNAME and YOUR_SPACE_NAME
+git remote add origin https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME
+git push -u origin main
+```
+
+#### Option B: Web Upload
+
+1. In your newly created Space, click **Files** → **Add file** → **Upload files**
+2. Drag and drop these files:
+   - `app.py`
+   - `requirements.txt`
+   - `README.md`
+   - `.gitignore`
+3. Click **Commit changes to main**
+
+### Step 3: Add Your HuggingFace Token as a Secret
+
+This is **CRITICAL** - the app won't work without this:
+
+1. In your Space, go to **Settings** (gear icon)
+2. Scroll to **Variables and secrets**
+3. Click **New secret**
+4. Enter:
+   - **Name**: `HF_TOKEN`
+   - **Value**: Your Hugging Face token
+   - ⚠️ Make sure this is marked as **Secret** (not a variable)
+5. Click **Save**
+6. The Space will automatically rebuild
+
+### Step 4: Wait for Build
+
+- The Space will install dependencies and start
+- This usually takes 1-3 minutes
+- Watch the **Logs** tab to see progress
+- Once you see "Running on local URL", it's ready!
+
+### Step 5: Test Your Space
+
+1. Go to the **App** tab
+2. Try a test message: "Help me find a good coffee shop"
+3. You should see Fara-7B respond!
+
+## Troubleshooting
+
+### Error: "HF_TOKEN not found"
+- Make sure you added the token as a **Secret**, not a Variable
+- Restart the Space after adding the secret
+
+### Error: "Model not found"
+- Check if `microsoft/Fara-7B` is publicly available
+- Ensure your token has inference permissions
+
+### Error: "Rate limit exceeded"
+- You're using the free inference tier
+- Wait a few minutes and try again
+- Consider upgrading to Inference Endpoints for production use
+
+### Space is slow
+- The free CPU tier is sufficient since inference happens on HF servers
+- Response time depends on model inference, not your Space hardware
+
+## Optional Enhancements
+
+### 1. Request GPU Hardware
+If you want faster Space loading (not needed for inference):
+- Settings → Hardware → Select a GPU tier
+- Note: This costs money, but inference API is separate
+
+### 2. Add Custom Examples
+Edit `app.py` and add example buttons:
+```python
+gr.Examples(
+    examples=[
+        "Find Italian restaurants in Seattle",
+        "Help me search for running shoes",
+        "What's the process to book a hotel?"
+    ],
+    inputs=msg
+)
+```
+
+### 3. Enable Analytics
+- Settings → Enable visitor analytics
+- Track usage of your Space
+
+## Cost Breakdown
+
+- **Space hosting**: FREE (CPU Basic tier)
+- **Inference API**: 
+  - Free tier: Limited requests/day
+  - Pro account: More requests
+  - Inference Endpoints: ~$0.60-1.00/hour for dedicated
+
+## Next Steps
+
+Once deployed, you can:
+1. Share your Space URL with others
+2. Embed it in websites
+3. Use the API endpoint programmatically
+4. Duplicate and customize for other models
+
+## Need Help?
+
+Check the logs in your Space for detailed error messages, or refer to:
+- [Gradio Documentation](https://gradio.app/docs)
+- [HuggingFace Spaces](https://huggingface.co/docs/hub/spaces)
+- [Inference API Docs](https://huggingface.co/docs/api-inference/index)
+
+---
+
+**Your Space folder**: `c:/Users/Amir/OneDrive - Digital Health CRC Limited/Projects/url2md/fara-7b-space`
+
+Happy deploying! 🚀

LOCAL_TESTING.md

@@ -0,0 +1,110 @@
+# Local Testing Instructions
+
+## Test Your Space Locally Before Deploying
+
+Before deploying to Hugging Face, you can test the app on your local machine.
+
+### Prerequisites
+
+1. Python 3.8 or higher installed
+2. Your Hugging Face token ready
+
+### Steps
+
+#### 1. Install Dependencies
+
+Open PowerShell/Terminal and navigate to this folder:
+
+```bash
+cd "c:/Users/Amir/OneDrive - Digital Health CRC Limited/Projects/url2md/fara-7b-space"
+```
+
+Install required packages:
+
+```bash
+pip install -r requirements.txt
+```
+
+#### 2. Set Your HuggingFace Token
+
+Create a `.env` file in this folder (it's already in .gitignore, so it won't be committed):
+
+```bash
+# PowerShell command to create .env file
+echo "HF_TOKEN=your_token_here" > .env
+```
+
+Replace `your_token_here` with your actual Hugging Face token.
+
+#### 3. Update app.py to Load .env (Temporary)
+
+For local testing only, add these lines at the top of `app.py`:
+
+```python
+from dotenv import load_dotenv
+load_dotenv()  # Load .env file
+```
+
+And install python-dotenv:
+```bash
+pip install python-dotenv
+```
+
+#### 4. Run the App Locally
+
+```bash
+python app.py
+```
+
+You should see output like:
+```
+Running on local URL:  http://127.0.0.1:7860
+```
+
+Open that URL in your browser to test!
+
+#### 5. Test the Chat
+
+- Type a message
+- Verify you get responses from Fara-7B
+- Test different temperatures and max_tokens settings
+- Check if streaming works properly
+
+### Important Notes
+
+⚠️ **Before Deploying:**
+- Remove the `load_dotenv()` code from `app.py` (Spaces use secrets, not .env)
+- Don't commit your `.env` file (already in .gitignore)
+- The Space will use the `HF_TOKEN` secret instead
+
+### Troubleshooting Local Testing
+
+**Import Error for dotenv:**
+```bash
+pip install python-dotenv
+```
+
+**Token Error:**
+- Check your token is correct in `.env`
+- Ensure no extra spaces or quotes
+- Verify token has inference permissions
+
+**Port Already in Use:**
+```bash
+# Kill the process or run on different port
+python app.py --server-port 7861
+```
+
+### Alternative: Quick Test Without .env
+
+You can also temporarily hardcode your token (FOR TESTING ONLY):
+
+```python
+client = InferenceClient(token="your_token_here")  # TEMPORARY - REMOVE BEFORE DEPLOYING
+```
+
+⚠️ **NEVER commit hardcoded tokens to git!**
+
+---
+
+Once local testing works, you're ready to deploy to Hugging Face Spaces! See `DEPLOYMENT_GUIDE.md` for deployment instructions.

QUICKSTART.md

@@ -0,0 +1,106 @@
+# 🎉 Your Fara-7B Hugging Face Space is Ready!
+
+## 📁 What You Have
+
+Your Space is in: `c:/Users/Amir/OneDrive - Digital Health CRC Limited/Projects/url2md/fara-7b-space`
+
+### Files Created:
+
+1. **app.py** - Main Gradio application with chat interface
+2. **requirements.txt** - Python dependencies
+3. **README.md** - Space documentation (shows on HuggingFace)
+4. **.gitignore** - Git ignore rules
+5. **DEPLOYMENT_GUIDE.md** - Step-by-step deployment instructions
+6. **LOCAL_TESTING.md** - How to test locally before deploying
+
+## 🚀 Quick Start - Deploy to HuggingFace
+
+### Option 1: Web Upload (Easiest)
+
+1. Go to https://huggingface.co/new-space
+2. Create a new Space (SDK: Gradio)
+3. Upload all files from the folder
+4. Add `HF_TOKEN` secret in Settings
+5. Done! 🎉
+
+### Option 2: Git Push
+
+```bash
+cd "c:/Users/Amir/OneDrive - Digital Health CRC Limited/Projects/url2md/fara-7b-space"
+git init
+git add .
+git commit -m "Initial commit"
+git remote add origin https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME
+git push -u origin main
+```
+
+Then add `HF_TOKEN` secret in Space Settings.
+
+## 🧪 Test Locally First (Optional)
+
+```bash
+cd "c:/Users/Amir/OneDrive - Digital Health CRC Limited/Projects/url2md/fara-7b-space"
+pip install -r requirements.txt
+pip install python-dotenv
+echo "HF_TOKEN=your_token_here" > .env
+python app.py
+```
+
+See `LOCAL_TESTING.md` for details.
+
+## ✨ Features
+
+Your Space includes:
+- 💬 **Chat Interface** - Clean, modern Gradio UI
+- 🌊 **Streaming Responses** - Real-time text generation
+- ⚙️ **Customization** - Temperature and max tokens controls
+- 📱 **Responsive** - Works on mobile and desktop
+- 🎨 **Themed** - Soft, professional color scheme
+- 📚 **Documentation** - Built-in help and examples
+
+## 🔑 Critical: HuggingFace Token Setup
+
+Your app REQUIRES a HuggingFace token with inference permissions:
+
+1. **Get/Check Token**: https://huggingface.co/settings/tokens
+2. **In Space Settings**: Add as secret named `HF_TOKEN`
+3. **Restart Space** after adding the secret
+
+## 💰 Costs
+
+- **Space Hosting**: FREE (CPU Basic)
+- **Inference API**: Uses your HF free tier
+  - Free tier: ~100 requests/day
+  - For more: Consider HF Pro or dedicated endpoints
+
+## 📖 Next Steps
+
+1. **Read DEPLOYMENT_GUIDE.md** for detailed deployment steps
+2. **Optionally test locally** using LOCAL_TESTING.md
+3. **Create your Space** on HuggingFace
+4. **Upload files** and add your token
+5. **Share your Space** with the world!
+
+## 🛠️ Customization Ideas
+
+- Add example prompts with `gr.Examples()`
+- Change theme colors
+- Add file upload for images (when model supports it)
+- Integrate with Magentic-UI for full computer use
+- Add conversation export/save functionality
+
+## 📞 Support Resources
+
+- **This Space**: See DEPLOYMENT_GUIDE.md and LOCAL_TESTING.md
+- **Gradio Docs**: https://gradio.app/docs
+- **HuggingFace Spaces**: https://huggingface.co/docs/hub/spaces
+- **Fara-7B Model**: https://huggingface.co/microsoft/Fara-7B
+
+---
+
+**Created**: 2025-12-01
+**Model**: Microsoft Fara-7B (7B parameters)
+**Framework**: Gradio 4.x
+**Inference**: HuggingFace Inference API
+
+Enjoy your Space! 🚀🤖

README.md

@@ -0,0 +1,81 @@
+---
+title: Fara-7B Computer Use Agent
+emoji: 🤖
+colorFrom: purple
+colorTo: blue
+sdk: gradio
+sdk_version: 4.44.0
+app_file: app.py
+pinned: false
+license: mit
+---
+
+# Fara-7B: Computer Use Agent Chat Interface
+
+This Space provides a chat interface to interact with **Microsoft Fara-7B**, an efficient agentic model designed for computer use and web automation.
+
+## 🌟 Features
+
+- **Interactive Chat**: Converse with Fara-7B about web automation tasks
+- **Streaming Responses**: Real-time response generation
+- **Customizable Parameters**: Adjust temperature and max tokens
+- **Clean UI**: Modern, user-friendly interface built with Gradio
+
+## 🚀 About Fara-7B
+
+Fara-7B is Microsoft's first agentic small language model (SLM) designed specifically for computer use. With only 7 billion parameters, it achieves state-of-the-art performance for:
+
+- 🛒 **Shopping automation**
+- ✈️ **Travel booking research**
+- 🍽️ **Restaurant reservations**
+- 📧 **Account workflows**
+- 🔍 **Information seeking**
+
+## ⚙️ Setup Instructions
+
+### For Space Owners:
+
+1. **Fork/Duplicate this Space** to your account
+2. Go to **Settings** → **Variables and secrets**
+3. Add a new secret:
+   - **Name**: `HF_TOKEN`
+   - **Value**: Your Hugging Face token (get it from [huggingface.co/settings/tokens](https://huggingface.co/settings/tokens))
+4. Ensure your token has **inference** permissions
+5. Restart the Space
+
+### Getting a Hugging Face Token:
+
+1. Go to [huggingface.co/settings/tokens](https://huggingface.co/settings/tokens)
+2. Click **New token**
+3. Select **Read** access (sufficient for inference)
+4. Copy the token and add it to Space secrets
+
+## 🎯 Usage
+
+Simply type your request in the chat box! Examples:
+
+- "Help me find Italian restaurants in Seattle"
+- "What steps would I take to book a flight to London?"
+- "How can I search for running shoes on an e-commerce site?"
+
+⚠️ **Note**: This is a text-only chat interface. For full computer use capabilities with screenshots and browser automation, check out the [Magentic-UI framework](https://github.com/microsoft/magentic-ui).
+
+## 📚 Resources
+
+- [Model Card](https://huggingface.co/microsoft/Fara-7B)
+- [Microsoft Research](https://www.microsoft.com/en-us/research/)
+- [Magentic-UI](https://github.com/microsoft/magentic-ui) - Full computer use framework
+
+## 📝 License
+
+MIT License - See [microsoft/Fara-7B](https://huggingface.co/microsoft/Fara-7B) for model license details.
+
+## 🤝 Credits
+
+- **Model**: Microsoft Research
+- **Interface**: Built with Gradio
+- **Inference**: Hugging Face Inference API
+
+---
+
+*This Space demonstrates the capabilities of Fara-7B through a simple chat interface. For production use cases requiring actual computer control, integrate with the full Magentic-UI framework.*

app.py

@@ -0,0 +1,185 @@
+import gradio as gr
+from huggingface_hub import InferenceClient
+import os
+
+# Initialize the Inference Client
+# The HF_TOKEN will be set as a Space secret
+client = InferenceClient(token=os.getenv("HF_TOKEN"))
+
+def chat_with_fara(message, history, temperature, max_tokens):
+    """
+    Interact with Fara-7B model via Hugging Face Inference API
+    
+    Args:
+        message: User's input message
+        history: Chat history
+        temperature: Sampling temperature
+        max_tokens: Maximum tokens to generate
+    """
+    try:
+        # Convert Gradio history format to messages format
+        messages = []
+        
+        # Add system prompt as per Fara-7B documentation
+        system_prompt = """You are a web automation agent that performs actions on websites to fulfill user requests by calling various tools.
+
+You should stop execution at Critical Points. A Critical Point occurs in tasks like:
+- Checkout
+- Book
+- Purchase
+- Call
+- Email
+- Order
+
+A Critical Point requires the user's permission or personal/sensitive information (name, email, credit card, address, payment information, resume, etc.) to complete a transaction (purchase, reservation, sign-up, etc.), or to communicate as a human would (call, email, apply to a job, etc.).
+
+Guideline: Solve the task as far as possible up until a Critical Point.
+
+Examples:
+- If the task is to "call a restaurant to make a reservation," do not actually make the call. Instead, navigate to the restaurant's page and find the phone number.
+- If the task is to "order new size 12 running shoes," do not place the order. Instead, search for the right shoes that meet the criteria and add them to the cart.
+
+Some tasks, like answering questions, may not encounter a Critical Point at all."""
+        
+        messages.append({"role": "system", "content": system_prompt})
+        
+        # Add conversation history
+        for user_msg, assistant_msg in history:
+            messages.append({"role": "user", "content": user_msg})
+            if assistant_msg:
+                messages.append({"role": "assistant", "content": assistant_msg})
+        
+        # Add current message
+        messages.append({"role": "user", "content": message})
+        
+        # Call the inference API with streaming
+        response_text = ""
+        for chunk in client.chat_completion(
+            model="microsoft/Fara-7B",
+            messages=messages,
+            temperature=temperature,
+            max_tokens=max_tokens,
+            stream=True
+        ):
+            if chunk.choices[0].delta.content:
+                response_text += chunk.choices[0].delta.content
+                yield response_text
+                
+    except Exception as e:
+        error_msg = f"❌ Error: {str(e)}\n\nPlease ensure:\n1. Your HF_TOKEN is set in Space secrets\n2. The token has inference permissions\n3. You have access to microsoft/Fara-7B"
+        yield error_msg
+
+# Custom CSS for better UI
+custom_css = """
+.gradio-container {
+    font-family: 'Inter', sans-serif;
+}
+.chat-message {
+    padding: 10px;
+    border-radius: 8px;
+}
+footer {
+    visibility: hidden;
+}
+"""
+
+# Create the Gradio interface
+with gr.Blocks(css=custom_css, theme=gr.themes.Soft()) as demo:
+    gr.Markdown(
+        """
+        # 🤖 Fara-7B: Computer Use Agent
+        
+        **Microsoft's first agentic small language model** designed for web automation and computer use tasks.
+        
+        This is a 7B parameter multimodal model that can help with:
+        - 🛒 Shopping automation
+        - ✈️ Travel booking research
+        - 🍽️ Restaurant reservations
+        - 📧 Account workflows
+        - 🔍 Information seeking
+        
+        ⚠️ **Note**: This chat interface provides text-only interaction. For full computer use capabilities 
+        (screenshots, browser automation), integrate with the Magentic-UI framework.
+        """
+    )
+    
+    chatbot = gr.Chatbot(
+        height=500,
+        label="Chat with Fara-7B",
+        show_label=True,
+        avatar_images=(None, "🤖"),
+        bubble_full_width=False
+    )
+    
+    with gr.Row():
+        msg = gr.Textbox(
+            label="Your Message",
+            placeholder="Example: Help me find a good Italian restaurant in Seattle...",
+            lines=2,
+            scale=4
+        )
+        send_btn = gr.Button("Send 📤", scale=1, variant="primary")
+    
+    with gr.Accordion("⚙️ Advanced Settings", open=False):
+        temperature = gr.Slider(
+            minimum=0.1,
+            maximum=1.0,
+            value=0.7,
+            step=0.1,
+            label="Temperature",
+            info="Higher values make output more creative, lower values more focused"
+        )
+        max_tokens = gr.Slider(
+            minimum=64,
+            maximum=2048,
+            value=512,
+            step=64,
+            label="Max Tokens",
+            info="Maximum length of the response"
+        )
+    
+    with gr.Row():
+        clear_btn = gr.Button("🗑️ Clear Chat", scale=1)
+        
+    gr.Markdown(
+        """
+        ---
+        ### 📚 Learn More
+        - [Model Card](https://huggingface.co/microsoft/Fara-7B)
+        - [Research Paper](https://huggingface.co/microsoft/Fara-7B)
+        - [Magentic-UI Framework](https://github.com/microsoft/magentic-ui) for full computer use capabilities
+        
+        ### ⚙️ Setup Instructions
+        1. Go to Space Settings → Secrets
+        2. Add `HF_TOKEN` with your Hugging Face token
+        3. Ensure your token has inference permissions
+        """
+    )
+    
+    # Event handlers
+    msg.submit(
+        chat_with_fara,
+        inputs=[msg, chatbot, temperature, max_tokens],
+        outputs=[chatbot]
+    ).then(
+        lambda: gr.update(value=""),
+        outputs=[msg]
+    )
+    
+    send_btn.click(
+        chat_with_fara,
+        inputs=[msg, chatbot, temperature, max_tokens],
+        outputs=[chatbot]
+    ).then(
+        lambda: gr.update(value=""),
+        outputs=[msg]
+    )
+    
+    clear_btn.click(
+        lambda: ([], ""),
+        outputs=[chatbot, msg]
+    )
+
+# Launch the app
+if __name__ == "__main__":
+    demo.launch()

requirements.txt

@@ -0,0 +1,2 @@
+gradio>=4.0.0
+huggingface-hub>=0.20.0