Metadata-Version: 2.4
Name: filgood
Version: 0.1.2
Summary: Fake your PostgreSQL database content with utmost ease using an AI agent
Author-email: Tracktor SAS <sre@tracktor.fr>
Maintainer-email: Tracktor SAS <sre@tracktor.fr>
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: aiofile<4,>=3
Requires-Dist: asyncpg<1,>=0.30
Requires-Dist: faker<38,>=37
Requires-Dist: openai<2,>=1
Requires-Dist: piou<1,>=0.16
Requires-Dist: rich<14,>=13
Description-Content-Type: text/markdown

Filgood
-------

“fil” came from the arabic transliteration (فيل) - meaning elephant!

Utility to populate a database only knowing the actual schemas. This program only operate with Postgres.
Sufficient right will be required (SCHEMA CREATE / TABLE CREATE & Inspect pg_catalog).

The library require asyncio. We are bound to the asyncpg connector, and we support no other connector for the time being.

## Quick start

### Using the CLI

FilGood come with a CLI! It is really easy to use, for your convenience.

```
$ filgood -h
usage: filgood [-h] [-i INCREASE] [-s SCHEMA] [-t TABLE] [--no-cache] [--skip-empty] [-v] database

LLM agent for filling a database with fake records

positional arguments:
  database              Postgres database DSN to be used

options:
  -h, --help            show this help message and exit
  -i INCREASE           Percentage increase or flat row count target for data injection
  -s SCHEMA, --schema SCHEMA
                        Target a specific schema
  -t TABLE, --table TABLE
                        Target a specific table
  --no-cache            Disable the cache (LLM)
  --skip-empty          Skip empty table
  -v, --verbose         Enable advanced debugging
```

For example, running: `filgood postgres://postgres:postgres@localhost:5555/postgres -i 1000`
will increase every table by a thousand records!

Or, running: `filgood postgres://postgres:postgres@localhost:5555/postgres -i 300%`
will increase every table by adding three times more records.

### Starting code

Here is a minimal code snippet to get started. This will increase by 300% (or 3 times the current amount of rows) every
detected tables in every accessible schemas.

```python
import asyncio

from filgood import DatabaseFaker, GrowthStrategy

async def main() -> None:
    async with DatabaseFaker(
        "postgres://postgres:postgres@localhost/tracktor",
        openai_key="sk-proj-gm...",  # either provide the key here or set OPENAI_API_KEY environment variable first.
    ) as db_faker:
        await db_faker.load(
            strategy=GrowthStrategy.BY_PERCENT_INCREASE,
            increase=300,
        )

if __name__ == "__main__":
    asyncio.run(main())
```

### Exclude schemas

Don't worry, we already excluded system schemas. Moreover, you may also exclude some schemas yourself.

```python
from filgood import DatabaseFaker

async def main() -> None:
    async with DatabaseFaker(
        "postgres://postgres:postgres@localhost/tracktor",
        excluded_schemas=["sensible_schema_a", "useless_schema_b",]  # you get the idea!
    ) as db_faker:
        ...
```

### Focusing on schema or table or both

Here's how to keep focused on a target schema:

```python
from filgood import DatabaseFaker

async def main() -> None:
    async with DatabaseFaker(
        "postgres://postgres:postgres@localhost/tracktor",
    ) as db_faker:
        await db_faker.load(target_schema="xyz")
```

And now a specific table without a specific schema:

```python
from filgood import DatabaseFaker

async def main() -> None:
    async with DatabaseFaker(
        "postgres://postgres:postgres@localhost/tracktor",
    ) as db_faker:
        await db_faker.load(target_table="abc")
```

Of course, you may set both `schema` and `table` to ensure a really specific case.

## Caching

In order to avoid depleting your OpenAI API credit, we made a tiny caching layer that just works.
You can expect the bare minimum amount of requests to OpenAI! Feel free to inspect at will the generated
cache file that should be named `.filgood.json` in your pwd or $HOME (via CLI).

## Performance

You may increase at any time the database pool connection by setting the `database_pool_size` parameter.

```python
from filgood import DatabaseFaker

async def main() -> None:
    async with DatabaseFaker(
        "postgres://postgres:postgres@localhost/tracktor",
        database_pool_size=100,
    ) as db_faker:
        await db_faker.load(target_table="abc")
```

## Warnings / Disclaimers

That's the tough section, unfortunately not everything "automagic" is pretty inside.
Here is some of our warnings about this:

- FilGood does not watch for the remaining disk space left on your device. Don't go south with the row insertions!
- We rely on a LLM codegen, and we trust the given generated code blindly. It would be wise to only use a provider/model you know is guarded by a trusted third party.
- The RAM usage may spike depending on your initial request.
- Can often fail on really complex databases. We did our best.

We think that you get the general idea. Be careful. It's a nice proof of concept, but we shouldn't expect too much out of it.
