g4fscript

g4fscript is a PyScript-friendly fork of gpt4free.

The installable distribution and Python import package are both named g4fscript.

This fork focuses on:

• keeping the upstream client/provider API shape familiar while using the g4fscript namespace;
• adding a browser-safe PyScript/Pyodide path;
• exposing a BrowserFetch provider for CORS-enabled OpenAI-compatible APIs;
• keeping the desktop GUI, CLI, API server, MCP server, providers, and examples usable from normal Python installs;
• documenting the sharp edges that matter in browsers.

Contents

• Install
• Quick Start
• PyScript Usage
• Examples
• Providers And Models
• GUI, API, CLI, And MCP
• Docker
• Project Layout
• Development
• Compatibility Notes
• Legal And Safety
• Credits
• License

Install

Install the published package when it is available:

pip install -U "g4fscript[all]"

Install directly from this fork:

pip install -U "g4fscript[all] @ git+https://github.com/NacreousDawn596/g4fscript.git"

Install from a local checkout:

git clone https://github.com/NacreousDawn596/g4fscript.git
cd g4fscript
pip install -e ".[all]"

Small installs are also supported:

pip install -U "g4fscript[pyscript]"
pip install -U "g4fscript[api]"
pip install -U "g4fscript[gui]"
pip install -U "g4fscript[search]"

The import name is g4fscript:

import g4fscript
from g4fscript.client import Client, AsyncClient

Quick Start

Create a chat completion:

from g4fscript.client import Client

client = Client()

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[
        {"role": "user", "content": "Write one calm sentence about PyScript."}
    ],
)

print(response.choices[0].message.content)

Use the async client:

import asyncio
from g4fscript.client import AsyncClient


async def main():
    client = AsyncClient()
    response = await client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[
            {"role": "user", "content": "Explain CORS in one paragraph."}
        ],
    )
    print(response.choices[0].message.content)


asyncio.run(main())

Generate an image:

from g4fscript.client import Client

client = Client()

response = client.images.generate(
    model="flux",
    prompt="a tiny desk setup in watercolor",
    response_format="url",
)

print(response.data[0].url)

PyScript Usage

g4fscript can run under PyScript when PyScript uses the Pyodide interpreter.

Use the pyscript extra:

{
  "interpreter": "0.29.0",
  "packages": ["g4fscript[pyscript]"]
}

During local development, build a wheel and serve it from the same origin as your page:

{
  "interpreter": "0.29.0",
  "packages": ["./dist/g4fscript-0.0.0-py3-none-any.whl"]
}

Browser code should use BrowserFetch:

from g4fscript.client import AsyncClient
from g4fscript.Provider import BrowserFetch

client = AsyncClient(
    provider=BrowserFetch,
    api_key="sk-...",
    base_url="https://api.openai.com/v1",
)

response = await client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[
        {"role": "user", "content": "Say hello from PyScript."}
    ],
)

print(response.choices[0].message.content)

For local OpenAI-compatible endpoints that do not require an API key, pass allow_unauthenticated=True to the completion request.

Important browser limits:

• the target API must allow browser CORS access;
• streaming responses are not exposed by BrowserFetch yet;
• OS cookies, HAR extraction, browser automation, custom certificates, and proxies are desktop features;
• the GUI, CLI, MCP server, API server, and local model backends are not PyScript browser targets;
• PyScript MicroPython mode is not supported for the package install path.

Read the focused PyScript guide in docs/pyscript.md.

Examples

Useful examples live in etc/examples:

• pyscript_browser_fetch.html: complete PyScript browser chat page;
• list_free_working_providers.py: list free working providers and their models;
• text_completions_demo_sync.py: synchronous text completion;
• text_completions_demo_async.py: async text completion;
• text_completions_streaming.py: streaming text completion;
• api_completions_copilot.py: API completion example;
• api_generations_image.py: image generation through the API;
• vision_images.py: vision input example;
• audio.py: audio example;
• video.py: video example;
• mcp_tools_demo.py: MCP tool usage demo.

List providers and models:

python etc/examples/list_free_working_providers.py
python etc/examples/list_free_working_providers.py --json
python etc/examples/list_free_working_providers.py --refresh --model-limit 0

Providers And Models

Providers are available from g4fscript.Provider and are selected automatically unless you pass one explicitly.

from g4fscript.client import Client
from g4fscript.Provider import RetryProvider, Phind

client = Client(
    provider=RetryProvider([Phind], shuffle=False)
)

Provider support varies. Some providers need authentication, browser cookies, a live browser, additional optional dependencies, or a network request to refresh model names. Browser execution is narrower than desktop Python because PyScript must obey browser security rules.

For a local snapshot of free working providers:

python etc/examples/list_free_working_providers.py

GUI, API, CLI, And MCP

Run the web GUI:

g4fscript gui --port 8080 --debug

Open:

http://localhost:8080/chat/

Run the OpenAI-compatible API server:

python -m g4fscript --port 8080 --debug

Use the CLI entry points:

g4fscript --help

Run the MCP server:

g4fscript-mcp
python -m g4fscript.mcp

Run MCP over HTTP:

g4fscript mcp --http --host 127.0.0.1 --port 8765

The MCP server includes tools for web search, web scraping, and image generation when the matching dependencies and providers are available.

Docker

Use the fork image names when publishing or running g4fscript containers.

Full image:

mkdir -p "${PWD}/har_and_cookies" "${PWD}/generated_media"

docker run -p 8080:8080 -p 7900:7900 \
  --shm-size="2g" \
  -v "${PWD}/har_and_cookies:/app/har_and_cookies" \
  -v "${PWD}/generated_media:/app/generated_media" \
  nacreousdawn596/g4fscript:latest

Slim image:

mkdir -p "${PWD}/har_and_cookies" "${PWD}/generated_media"

docker run -p 1337:8080 -p 8080:8080 \
  -v "${PWD}/har_and_cookies:/app/har_and_cookies" \
  -v "${PWD}/generated_media:/app/generated_media" \
  nacreousdawn596/g4fscript:latest-slim

The full image exposes the app on port 8080 and an optional browser desktop on port 7900. Persistent cookies, HAR files, and generated media should be stored in mounted directories.

Project Layout

g4fscript/                         Python import package
g4fscript/Provider/BrowserFetch.py PyScript browser fetch provider
g4fscript/compat/pyscript.py       PyScript/Pyodide runtime helpers
etc/examples/                Runnable examples
docs/pyscript.md             Browser compatibility guide
generated_media/             Default generated media output directory
setup.py                     Distribution metadata and extras

Development

Set up a local editable install:

python -m venv .venv
. .venv/bin/activate
pip install -e ".[all]"

Run a quick syntax check:

python -m compileall -q g4fscript setup.py
python -m py_compile etc/examples/list_free_working_providers.py

Build a wheel for PyScript testing:

python -m build

Then serve the repository directory and point the PyScript package list at the generated wheel in dist/.

Compatibility Notes

g4fscript keeps the upstream client/provider API shape, but the import namespace is now g4fscript.

The fork is designed for Python 3.10+ on desktop/server Python and Pyodide-backed PyScript in the browser. Some optional extras are intentionally skipped on Emscripten/Pyodide because browser environments cannot provide the same OS integrations as desktop Python.

Use desktop Python for:

• provider browser automation;
• cookie and HAR extraction;
• local model runtimes;
• GUI and API hosting;
• MCP serving;
• proxy and custom certificate workflows.

Use PyScript for:

• async client workflows;
• local browser demos;
• CORS-enabled OpenAI-compatible endpoints;
• pure Python request/response shaping in a browser page.

Legal And Safety

This repository is not affiliated with or endorsed by OpenAI or by the third-party providers implemented in the provider tree. Provider names, trademarks, APIs, and services belong to their respective owners.

Use this project for learning, experimentation, and lawful integration work. You are responsible for complying with provider terms, local laws, credential handling requirements, and deployment security expectations.

Read LEGAL_NOTICE.md before using or redistributing the project.

Credits

g4fscript is a fork of xtekky/gpt4free.

Original project credit belongs to the upstream authors and contributors, including @xtekky and maintainers such as @hlohaus. This fork keeps upstream compatibility while adding PyScript-focused packaging, docs, and browser runtime helpers.

Fork repository:

https://github.com/NacreousDawn596/g4fscript

Upstream repository:

https://github.com/xtekky/gpt4free

License

This project is licensed under the GNU General Public License v3.0. See LICENSE for the full text.