.github/copilot-instructions.md

AI Agent Instructions for LocalAI

Project Overview

LocalAI is a Gradio-based application that implements MCP (Model Context Protocol) server/client architecture with specialized translation services. The system uses profile-guided AI agents to translate complex English into simplified, contextually-clear text and corresponding Python code.

Architecture & Core Concepts

The Two-Agent Translation System

This project implements a two-stage pipeline where distinct AI profiles work in sequence:

1. English Translator (Profiles/Python Translator.txt): Converts complex English specifications into simple, context-preserving sentences—breaking down compound/complex sentences into simple ones and replacing pronouns with antecedents.

2. Python Translator (Profiles/Python Translator.txt): Translates simplified English into Python code by mapping nouns/verbs to classes/functions and objects to constants/variables.

Key insight: The profiles deliberately separate concerns—the English translator handles human language clarity, the Python translator handles code generation. This allows each agent to specialize.

Entry Point Architecture

• app.py: Single Gradio interface file that contains all application logic
  • Simple greet() function demonstrates the interface pattern
  • Uses gr.Interface() with text input/output
  • Profiles are loaded as string constants within the function (see stProfile variable)
  • Application is launched with demo.launch()

Pattern: Keep Gradio interfaces minimal—business logic should flow through function parameters into the translator profiles.

Extending the System

Adding New Translation Profiles

1. Create new .txt file in Profiles/ directory
2. Follow the [Begin Profile]...[End Profile] format
3. Define role, transformation rules, and constraints clearly
4. Reference the profile in app.py as a string constant

Modifying the Translation Pipeline

• Update the greet() function to accept more complex inputs
• Add intermediate processing steps between English and Python translation
• Maintain the separation of concerns: preserve English-to-simple and simple-to-code as distinct stages

Configuration & Deployment

• Gradio version: 5.49.1 (specified in README.md)
• SDK: Gradio (not a custom SDK)
• License: Apache 2.0
• Deployment: Hugging Face Spaces (see README metadata)

The app follows Spaces configuration conventions—keep app.py as the entry point and maintain compatibility with the pinned SDK version.

Development Patterns

Profile-Driven Behavior

Instead of hardcoding logic, this system encodes behavioral specifications in profile strings. When extending:

• Put rules in profiles (not code)
• Put execution in functions (e.g., interface handlers)

Interface Pattern

All user interactions flow through Gradio's Interface.launch(). When adding features:

1. Extend the input/output specification
2. Update the handler function to process new inputs
3. Add corresponding profile guidance if new translation rules are needed

Common Tasks

Running the application: python app.py (Gradio will launch on localhost:7860)

Testing translations: Pass test strings through the Gradio interface—both profiles operate on the same text stream sequentially.

Debugging profile behavior: Enable Gradio's debug mode in demo.launch() to see intermediate outputs.