First steps

Quickstart

Quick guide to set up the environment, install dependencies and run the BetterAI services for the first time.

On this page

    #1. Update the Project

    First, make sure you are on the correct branch and that your code is up to date:

    git checkout production
git pull
git checkout -b nome-da-sua-branch

    #2. Create the Virtual Environment

    Requirement: Python 3.14 or higher (version pinned in .python-version).

    Create a virtual environment to isolate the project's dependencies:

    python -m venv .venv

    #3. Activate the Virtual Environment

    .\.venv\Scripts\Activate.ps1

    After activation, your terminal should look like this:

    (.venv) PS C:\Users\nome_do_usuario\better-ai>

    #4. Install the Dependencies

    You can install the dependencies in two ways:

    uv sync

    #5. Configure the Environment Variables

    Create a .env file in the project root with the following variables:

    VariableDescription
    BETTERAI_API_KEYBetterAI internal API key
    OPENAI_API_KEYOpenAI API key
    OPENAI_EMBEDDING_MODELOpenAI embeddings model in use
    GEMINI_API_KEYGoogle Gemini API key
    GROQ_API_KEYGroq API key
    ANTHROPIC_API_KEYAnthropic (Claude) API key
    TAVILY_API_KEYTavily (web search) API key
    FAL_API_KEYFal (media generation) API key
    EXCHANGE_RATE_API_KEYExchange rate API key
    HUGGINGFACEHUB_API_TOKENHugging Face Hub access token
    PINECONE_API_KEYPinecone (vector store) API key
    PINECONE_ENVIRONMENTPinecone region/environment
    PINECONE_INDEX_NAMEName of the vector index in Pinecone
    PINECONE_NAMESPACEKnowledge base namespace
    PINECONE_GLOBAL_NAMESPACEGlobal knowledge base namespace
    MONGO_URIFull MongoDB connection string
    MONGO_USERMongoDB user
    MONGO_PASSWORDMongoDB password
    MONGO_HOSTMongoDB host
    MONGO_PORTMongoDB port
    NOSQL_BACKENDNoSQL backend in use (local or remote)
    SUPABASE_URLSupabase project URL
    SUPABASE_SECRET_KEYSupabase service secret key
    SUPABASE_DATABASE_URLSupabase Postgres database connection string
    SUPABASE_PROJECT_NAMESupabase project name
    SUPABASE_PROJECT_HOSTSupabase project host
    SUPABASE_DATABASE_PASSWORDSupabase database password
    SHOW_INFO_LOGSShows informational logs (true/false)
    SHOW_METADATAShows metadata in responses (true/false)
    FORMAT_METADATAFormats the displayed metadata (true/false)
    SAVE_LOGSSaves execution logs (true/false)
    SAVE_MONGOSaves execution data to MongoDB (true/false)
    LOCALFlag for local execution (true/false)
    See the full .env template
    .env
    # BetterAI
BETTERAI_API_KEY=********************

# LLM's
OPENAI_API_KEY=********************
OPENAI_EMBEDDING_MODEL=text-embedding-3-large

GEMINI_API_KEY=********************
GROQ_API_KEY=********************
ANTHROPIC_API_KEY=********************

# Tools
TAVILY_API_KEY=********************
FAL_API_KEY=********************
EXCHANGE_RATE_API_KEY=********************
HUGGINGFACEHUB_API_TOKEN=********************

# Database

# Pinecone
PINECONE_API_KEY=********************
PINECONE_ENVIRONMENT=us-east-1
PINECONE_INDEX_NAME=backai-vectorstore
PINECONE_NAMESPACE=knowledge_base
PINECONE_GLOBAL_NAMESPACE=global_knowledge_base

# MongoDB
MONGO_URI=********************
MONGO_USER=********************
MONGO_PASSWORD=********************
MONGO_HOST=********************
MONGO_PORT=********************

NOSQL_BACKEND=local

# Supabase
SUPABASE_URL=********************
SUPABASE_SECRET_KEY=********************
SUPABASE_DATABASE_URL=********************
SUPABASE_PROJECT_NAME=better-ai-bucket-storage
SUPABASE_PROJECT_HOST=********************
SUPABASE_DATABASE_PASSWORD=********************

# Application Tracing Rules
SHOW_INFO_LOGS=false
SHOW_METADATA=false
FORMAT_METADATA=false
SAVE_LOGS=false
SAVE_MONGO=false

LOCAL=false

    #6. Run the application

    The project exposes two independent services, which can be run separately or in parallel (in separate terminals):

    ServiceCommandPortWhen to use
    API (FastAPI)uvicorn web_services:app --reload8000Programmatic access to the AI modules over HTTP
    Interface (Streamlit)streamlit run web_app.py8501Visual use of the applications (Acquarello, Content Generator)

    Prerequisites: virtual environment activated (step 3), dependencies installed (step 4) and .env file configured (step 5).

    #6.1. API (FastAPI + Uvicorn)

    uvicorn web_services:app --reload

    The --reload flag restarts the server automatically on every code change — recommended for development only.

    INFO:     Will watch for changes in these directories: ['C:\\Users\\user_name\\better-ai']
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
INFO:     Started reloader process [24960] using StatReload
INFO:     Router included: /agents
INFO:     Router included: /davinci
INFO:     Router included: /deep-research
INFO:     Router included: /parse-content
INFO:     Router included: /vector-store
INFO:     Started server process [4748]
INFO:     Waiting for application startup.
INFO:

    ╔═══════════════════════════════════════════════════════════════════════╗

        ██████╗ ███████╗████████╗████████╗███████╗██████╗      █████╗ ██╗ ✦
        ██╔══██╗██╔════╝╚══██╔══╝╚══██╔══╝██╔════╝██╔══██╗    ██╔══██╗██║
        ██████╔╝█████╗     ██║      ██║   █████╗  ██████╔╝    ███████║██║
        ██╔══██╗██╔══╝     ██║      ██║   ██╔══╝  ██╔══██╗    ██╔══██║██║
        ██████╔╝███████╗   ██║      ██║   ███████╗██║  ██║    ██║  ██║██║
        ╚═════╝ ╚══════╝   ╚═╝      ╚═╝   ╚══════╝╚═╝  ╚═╝    ╚═╝  ╚═╝╚═╝

    ╚═══════════════════════════════════════════════════════════════════════╝

                        ✦ Where intelligence finds purpose. ✦

INFO:     BetterAI Web Service Network initialized successfully at 2026-08-17 08:55:20.
INFO:     Version: 1.0.0
INFO:     API_DOMAIN: http://localhost:8000
INFO:     Health check available at: http://localhost:8000/health
INFO:     Documentation available at: http://localhost:8000/docs
INFO:     Application startup complete.

    Available addresses

    ResourceURL
    Base URLhttp://localhost:8000
    Health checkhttp://localhost:8000/health
    Interactive documentation (Swagger UI)http://localhost:8000/docs

    Validate the startup

    Confirm that the API responded correctly before moving on:

    curl -X GET "http://127.0.0.1:8000/health"

    Main endpoints

    EndpointDescription
    GET /healthService availability check
    GET /health-authorizationService availability check with authentication
    POST /deep-research/context-builderContext building from deep research
    POST /parse-content/document-parseExtraction and structuring of document content
    POST /davinci/image-generationImage generation

    Each response follows a standardized format with job_id, status, result and execution time metrics. The full parameters and request/response examples are in Web Service Network - API.ipynb.

    #6.2. Streamlit Interface

    streamlit run web_app.py

    The application will be available at http://localhost:8501, with the following pages:

    ApplicationURLDocumentation
    Acquarellohttp://localhost:8501/acquarelloAcquarello.ipynb
    Content Generatorhttp://localhost:8501/content_generatorContent Generator.ipynb

    #6.3. Troubleshooting

    SymptomProbable causeWhat to do
    ModuleNotFoundError on startupVirtual environment not activated or dependencies missingReactivate the .venv (step 3) and run uv sync (step 4)
    Authentication error with the AI providersMissing or invalid keys in the .envReview step 5 and confirm the key values
    Connection failure to MongoDB/Supabase/PineconeWrong credentials or host in the .envCheck the database variables and network connectivity
    Port already in useAnother instance of the service is runningStop the previous process or use another port (--port)

    If the virtual environment becomes inconsistent, recreate it from scratch:

    deactivate
Remove-Item -Recurse -Force .\.venv
python -m venv .venv
    Esc
    ↑↓navigate Enteropen