Getting started
Welcome to the official documentation for **Keoxs Co-Pilot**, an open-source, local-first intelligence engine designed to automate, audit, and optimize your Amazon PPC portfolio. Keoxs puts enterprise-grade diagnostic economics and deep cognitive AI analysis directly on your local computer, ensuring complete data privacy and sub-second analysis times.
Local-First Privacy Guard
Unlike traditional SaaS platforms that require full seller account integration and store your financial data on remote servers, Keoxs operates **entirely inside your local machine**. Your search term reports, COGS, pricing structures, and API keys never leave your computer.
How Keoxs Co-Pilot Works
Keoxs Co-Pilot relies on a **dual-engine architecture** that combines mathematical precision with qualitative AI synthesis:
1. Algorithmic Unit Economics
The core calculation engine parses your Search Term Reports (STR) line by line, comparing metrics against your actual product pricing, COGS, and FBA fees to flag bleeding targets and compute optimal bids.
2. Cognitive AI Brain
Powered by Google Gemini, the AI bypasses rigid algorithmic thresholds to analyze seasonal search intent, organic potential, and competitor conquest opportunities, generating custom strategic roadmaps.
What you need
Before deploying Keoxs Co-Pilot, ensure your system meets the following specifications:
- Node.js – Node 18+ recommended (v20+ fully supported) to power the frontend interface.
- Python – Python 3.10+ required to run the local FastAPI calculation backend.
- Google AI Studio API Key – Required to activate the Cognitive AI Brain tab. Get one for free at Google AI Studio.
- Git – Recommended to easily fetch updates and manage the repository.
Quick Onboarding
We provide a friction-free, one-liner installer that checks prerequisites, clones the latest repository, configures the local virtual environments, and starts both servers automatically.
Manual Developer Setup
If you prefer to configure your development workspace manually or want to contribute to the open-source codebase, follow these step-by-step instructions.
1. Clone the Repository
cd keoxs-co-pilot
2. Configure the FastAPI Backend
python -m venv venv
# Windows:
.\venv\Scripts\activate
# macOS/Linux:
source venv/bin/activate
pip install -r requirements.txt
python -m uvicorn api:app --host 127.0.0.1 --port 8001 --reload
3. Configure the React Frontend
npm install
npm run dev
Setup Wizard Module
On launch, Keoxs prompts you with a comprehensive financial onboarding panel. Enter your:
- API Key – Secures connection to Gemini models. Saved strictly inside local storage.
- Average Price & COGS – Enables the algorithm to calculate your Break-Even ACOS dynamically (`Profit Margin = (Sales Price - COGS - FBA Fees) / Sales Price`).
- Wasted Spend Threshold – Standard: 10 clicks without conversion. This threshold determines when bleeding keywords should be aggressively bid down or paused.
Drop Zone Ingestion
Drag and drop your raw Amazon **Search Term Report** (either Sponsored Products or General PPC Campaign Reports) in CSV or XLSX format directly into the designated Drop Zone.
Keoxs immediately normalizes files from any Amazon locale, filters out empty variables, and displays a tri-column executive dashboard categorized by mathematical urgency:
🔴 Urgencies
Bleeding keywords with high clicks but 0 orders. Suggests immediate negative exact exclusions.
🟠 Optimizations
Converting keywords with an ACOS exceeding your calculated Break-Even margin. Suggests standard bid decreases.
🟢 Opportunities
Highly profitable terms, seasonal keywords, or conquest competitor targets. Suggests bid increases.
Cognitive AI Brain
Traditional programmatic filters often fail to recognize micro-opportunities—such as competitor targets that convert at the very first click, or early seasonal search trends.
The **AI Brain** tab bypasses these rigid mathematical constraints by feeding Gemini with rich, unfiltered context:
- Full Converter Feed – The AI scans every search term that generated at least 1 sale, immediately capturing competitor targets (like `b0fmzkwkx9`) with sky-high ROAS.
- Historical Context Injection – Automatically stores and appends your 5 most recent audits, ensuring tactical coherence and preventing conflicting decisions.
- Traffic/Conversion Diagnostics – Synthesizes traffic limits against conversion rates, letting you know if a campaign is a "Ferrari running without fuel" due to budget or bidding constraints.
Bulk Action Export
Apply optimizations on Amazon in seconds. Clicking **Export Bulk Actions** filters your entire STR to retain only high-impact rows with suggested bid adjustments and action labels.
The output flat CSV uses standard semicolons, making it immediately readable by Excel or Google Sheets, allowing you to copy-paste actions directly into your Amazon Ads Campaign Manager or Bulk Sheets.
Pro-Tips & Strategy
📅 Select the Ideal Lookback Window
When downloading reports from Amazon Ads Console, we recommend using a **last 30 days** lookback period (excluding the last 48 hours to account for attribution lag). This provides the engine with a statistically robust dataset to identify genuine trends rather than short-term noise.
✍️ Optimize Your AI Prompt Context
In the AI Brain context input, feed the assistant with specific qualitative variables (e.g., *"We are launching a new hydration flavor next week and need to be highly aggressive on conquesting,"* or *"We are out of stock on ASIN B until June, prioritize preserving cash flow on campaigns 3 and 4"*). The cognitive engine will dynamically adjust its action plan to align with your corporate realities.
⚖️ Balance TACoS & Net Margins
Keep a close eye on your TACoS (Total Advertising Cost of Sales). If your organic conversion rate is healthy but your overall net margins are suffering, use Keoxs' suggested bids to systematically lower bidding pressure on high-ACOS keywords until your TACoS stabilizes under 15%.