{"id":17526953,"url":"https://github.com/brevia-ai/brevia","last_synced_at":"2025-08-13T18:02:50.194Z","repository":{"id":199532753,"uuid":"703107979","full_name":"brevia-ai/brevia","owner":"brevia-ai","description":"Extensible API and framework to build your Retrieval Augmented Generation (RAG) and Information Extraction (IE) applications with LLMs","archived":false,"fork":false,"pushed_at":"2024-10-15T15:27:14.000Z","size":665,"stargazers_count":23,"open_issues_count":1,"forks_count":4,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-10-16T18:36:38.921Z","etag":null,"topics":["ai","api-rest","fastapi","information-extraction","information-retrieval","langchain","llm","pgvector","postgresql","rag"],"latest_commit_sha":null,"homepage":"http://docs.brevia.app","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/brevia-ai.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"docs/security.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-10-10T15:54:55.000Z","updated_at":"2024-10-15T15:27:17.000Z","dependencies_parsed_at":"2023-10-25T16:45:22.362Z","dependency_job_id":"709bd299-6f5a-44aa-98fc-f6f0c368f3d5","html_url":"https://github.com/brevia-ai/brevia","commit_stats":null,"previous_names":["brevia-ai/brevia"],"tags_count":44,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brevia-ai%2Fbrevia","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brevia-ai%2Fbrevia/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brevia-ai%2Fbrevia/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brevia-ai%2Fbrevia/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/brevia-ai","download_url":"https://codeload.github.com/brevia-ai/brevia/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":242161559,"owners_count":20081895,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","api-rest","fastapi","information-extraction","information-retrieval","langchain","llm","pgvector","postgresql","rag"],"created_at":"2024-10-20T15:02:39.338Z","updated_at":"2025-08-13T18:02:50.049Z","avatar_url":"https://github.com/brevia-ai.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"# Brevia\n\n[![Github Actions CS](https://github.com/brevia-ai/brevia/actions/workflows/cs.yml/badge.svg)](https://github.com/brevia-ai/brevia/actions?query=workflow%3Acs)\n[![Github Actions Unit](https://github.com/brevia-ai/brevia/actions/workflows/unit.yml/badge.svg)](https://github.com/brevia-ai/brevia/actions?query=workflow%3Aunit)\n[![Coverage Status](https://coveralls.io/repos/github/brevia-ai/brevia/badge.svg?branch=main\u0026kill_cache=1)](https://coveralls.io/github/brevia-ai/brevia?branch=main)\n![Python Versions](https://img.shields.io/pypi/pyversions/brevia.svg)\n[![Version](https://img.shields.io/pypi/v/brevia.svg?label=brevia)](https://pypi.org/project/brevia/)\n[![License](https://img.shields.io/badge/license-MIT-orange.svg)](https://github.com/brevia-ai/brevia/blob/main/LICENSE)\n\nBrevia is an extensible API and framework for building Retrieval Augmented Generation (RAG) and Information Extraction (IE) applications with LLMs.\n\nOut of the box, Brevia provides:\n\n* A complete API for RAG applications\n* An API with information extraction capabilities such as summarization, with the ability to create your own analysis logic and support for asynchronous background operations\n\nBrevia uses:\n\n* The popular [LangChain](https://github.com/langchain-ai/langchain) framework, which you can use to create custom AI tools and logic\n* The [FastAPI](https://github.com/tiangolo/fastapi) framework to easily extend your application with new endpoints\n* [PostgreSQL](https://www.postgresql.org) with the [`pg_vector`](https://github.com/pgvector/pgvector) extension as a vector database\n\n## Documentation\n\nBrevia documentation is available at [docs.brevia.app](https://docs.brevia.app).\n\n## Admin UI\n\nAn official UI is now available via [Brevia App](https://github.com/brevia-ai/brevia-app).\nIt is a web app that allows you to:\n\n* Create and configure new RAG collections\n* Add files, questions, or links to each collection\n* Test collections with a chat UI\n* Analyze the chat history for each collection\n* Perform information extraction actions such as summarization, audio transcription, or custom analysis\n\n## Requirements\n\nYou need Python 3.10 or higher and [Poetry](https://python-poetry.org/docs/#installation).\nA PostgreSQL database version 14 or higher with [`pg_vector`](https://github.com/pgvector/pgvector) is required, but you can use the provided Docker image for a quick setup.\n\n## Quick Try\n\nThe easiest way to try Brevia is through Docker. By launching Docker Compose with the following command, you will have a working Brevia system without any setup or configuration:\n\n```bash\n# Download docker-compose.yml and .env files (not necessary if you are in the brevia repo)\ncurl -o docker-compose.yml https://raw.githubusercontent.com/brevia-ai/brevia/refs/heads/main/docker-compose.yml\ncurl -o .env https://raw.githubusercontent.com/brevia-ai/brevia/refs/heads/main/.env.sample\n\ndocker compose --profile fullstack up\n```\n\nThis will provide:\n\n* Brevia API at http://localhost:8000\n* Brevia App UI at http://localhost:3000\n* [PgAdmin UI](https://www.pgadmin.org) at http://localhost:4000\n* [PostgreSQL](https://www.postgresql.org) with [`pg_vector`](https://github.com/pgvector/pgvector) running on `localhost:5432`\n\nTo use ports other than 8000, 3000, 4000, or 5432, set the environment variables `BREVIA_API_PORT`, `BREVIA_APP_PORT`, `PGVECTOR_PORT`, or `PGADMIN_PORT` in the `.env` file or before running the Docker compose command.\n\nYou can also use:\n\n* `--profile api` option to start only the Brevia API without the Brevia App\n* `--profile admin` option to start only the Postgres+pg_vector and the PgAdmin UI.\n\nWithout any `--profile` option, only the Postgres+pg_vector service will start.\n\n## Create a Brevia Project\n\n### Quick Start\n\nThe fastest way to create a new Brevia project is by using the [cookiecutter](https://github.com/cookiecutter/cookiecutter) template:\n\n```bash\npip install cookiecutter\ncookiecutter gh:brevia-ai/brevia-cookiecutter\n```\n\nSimply answer a few questions and you're ready to go.\n\n### Manual Setup\n\nTo set up a project manually:\n\n* Create a new project with `poetry new {your-brevia-project}`\n* Install Brevia and its dependencies by running `poetry add brevia` (a virtualenv will be created automatically)\n* Create a new `main.py` starting with a [copy](https://raw.githubusercontent.com/brevia-ai/brevia-cookiecutter/main/%7B%7Bcookiecutter.project_slug%7D%7D/main.py)\n* Activate the virtualenv by running `poetry env activate`\n* Copy `.env.sample` to `.env` and set the environment variables, especially secrets like API keys for LLM API services (e.g., `OPENAI_API_KEY` for OpenAI or `COHERE_API_KEY` for Cohere) and database connection via `PGVECTOR_*`. See the [Database](#database) section.\n\n## Model Configuration\n\nWith Brevia, you can configure any Large Language Model supported by LangChain—virtually all major models currently available.\nSee the [Brevia documentation](https://docs.brevia.app/models/overview/) for more details.\nFollow the steps below to set up and use a custom model in your Brevia project.\n\n### Ollama Model Integration\n\nSuppose you want to use a local Llama 3.2 model via [Ollama](https://ollama.com). Update your Brevia project as follows:\n\n1. Open the `.env` file in your project directory.\n\n2. For QA/RAG applications, set `QA_COMPLETION_LLM` and `QA_FOLLOWUP_LLM` as follows:\n\n```bash\nQA_COMPLETION_LLM='{\n    \"model_provider\": \"ollama\",\n    \"model\": \"llama3.2\",\n    \"temperature\": 0,\n    \"max_tokens\": 1000\n}'\nQA_FOLLOWUP_LLM='{\n    \"model_provider\": \"ollama\",\n    \"model\": \"llama3.2\",\n    \"temperature\": 0,\n    \"max_tokens\": 200\n}'\n```\n\n3. To configure the embeddings engine, you can use another model such as `nomic-embed-text`:\n\n```bash\nEMBEDDINGS='{\n    \"_type\": \"langchain_ollama.embeddings.OllamaEmbeddings\",\n    \"model\": \"nomic-embed-text\"\n}'\n```\n\n4. For summarization functions, set the `SUMMARIZE_LLM` variable:\n\n```bash\nSUMMARIZE_LLM='{\n    \"model_provider\": \"ollama\",\n    \"model\": \"llama3.2\",\n    \"temperature\": 0,\n    \"max_tokens\": 2000\n}'\n```\n\n## Database\n\nIf you have a PostgreSQL instance with the `pg_vector` extension available, you are ready to go. Otherwise, you can use the provided Docker Compose file.\n\nSimply run `docker compose up` to start a PostgreSQL database with `pg_vector`.\nYou can also run the embedded [`pgAdmin`](https://www.pgadmin.org) admin tool by running `docker compose --profile admin up` to start both the postgres+pgvector and pgadmin Docker images.\nOpen `pgadmin` in your browser at http://localhost:4000\n\nThe `4000` port is configurable via the `PGADMIN_PORT` environment variable in the `.env` file.\n\n## Migrations\n\nBefore using Brevia, you need to run the migrations script to create or update the initial schema. Use the following command from the virtual environment:\n\n```bash\ndb_upgrade\n```\n\nThis will run migrations using [Alembic](https://alembic.sqlalchemy.org/en/latest/) (already installed as a dependency) to create or update the required tables in your database.\n\n### Creating New Database Revisions\n\nIf you need to create new database migrations after modifying the database models, you can use the `db_revision` command:\n\n```bash\n# Create a new revision with manual changes\ndb_revision --message \"Add new column to users table\"\n\n# Create a new revision with automatic detection of model changes\ndb_revision --message \"Update user model\" --autogenerate\n```\n\nThe `--autogenerate` flag will automatically detect changes in your SQLAlchemy models and generate the appropriate migration code. Without this flag, you'll need to manually write the migration code in the generated revision file.\n\n## Launch\n\nYou are now ready to go. Simply run from the virtual environment:\n\n```bash\nuvicorn --env-file .env main:app\n```\n\nand your [Brevia API](https://github.com/brevia-ai/brevia) project is ready to accept calls!\n\n## Test Your API\n\nWhile we are working on a simple reference frontend for Brevia API, the easiest way to test your new API is by using the provided OpenAPI Swagger UI and ReDoc UI, or by using the official Postman files.\n\nGo to `/docs` for Swagger UI and `/redoc` for ReDoc.\n\nIf you prefer Postman, you can import the [collection file](https://raw.githubusercontent.com/brevia-ai/brevia/main/brevia/postman/Brevia%20API.postman_collection.json) and an [environment sample](https://raw.githubusercontent.com/brevia-ai/brevia/main/brevia/postman/Brevia%20API.postman_environment.json).\n\n## Add Documents via CLI\n\nYou can quickly create collections and add documents via CLI using the `import_file` command:\n\n```bash\nimport_file --file-path /path/to/file --collection my-collection\n```\n\nWhere:\n\n* `/path/to/file` is the path to a local PDF or TXT file\n* `my-collection` is the unique name of the collection (it will be created if it does not exist)\n\n## Import/Export Collections\n\nTo import or export collections via CLI, use the [PostgreSQL COPY command](https://www.postgresql.org/docs/current/sql-copy.html) in the `import_collection` and `export_collection` scripts.\n\nA `psql` client is required for these scripts. Connection parameters are read from environment variables (via the `.env` file).\n\nTwo PostgreSQL CSV files will be created during export and imported during import:\n* `{collection-name}-collection.csv` contains collection data\n* `{collection-name}-embedding.csv` contains document data and embeddings\n\nTo export a collection:\n\n```bash\nexport_collection --folder-path /path/to/folder --collection collection-name\n```\n\nTo import a collection:\n\n```bash\nimport_collection --folder-path /path/to/folder --collection collection-name\n```\n\nWhere:\n\n* `/path/to/folder` is the path where the two CSV files will be created (export) or searched for (import)\n* `collection-name` is the name of the collection\n\n## LangSmith Support\n\n[LangSmith](https://www.langchain.com/langsmith) is a platform to monitor, test, and debug LLM apps built with LangChain.\nTo use it in Brevia, if you have an account, export these environment variables when running Brevia:\n\n```bash\nLANGCHAIN_TRACING_V2=True\nLANGCHAIN_ENDPOINT=\"https://api.smith.langchain.com\"\nLANGCHAIN_API_KEY=\"########\"\nLANGCHAIN_PROJECT=\"My Project\"\n```\n\nIf you are using a `.env` file, use the `BREVIA_ENV_SECRETS` variable like this:\n\n```bash\nBREVIA_ENV_SECRETS='{\n  \"LANGCHAIN_TRACING_V2\": \"True\",\n  \"LANGCHAIN_ENDPOINT\": \"https://api.smith.langchain.com\",\n  \"LANGCHAIN_API_KEY\": \"########\",\n  \"LANGCHAIN_PROJECT\": \"My Project\"\n}'\n```\n\nThis ensures these variables are available as environment variables.\n\nEdit `LANGCHAIN_API_KEY` with your LangSmith API Key and set your project name in the `LANGCHAIN_PROJECT` variable.\n\n## Access Tokens\n\nThere is basic built-in support for access tokens for API security.\n\nAccess tokens are checked via the `Authorization: Bearer \u003ctoken\u003e` header if the `TOKENS_SECRET` environment variable is set.\nYou can generate a new access token using:\n\n```bash\npoetry run create_token --user {user} --duration {minutes}\n```\n\nIf the `TOKENS_SECRET` environment variable is set, token verification is automatically performed on every endpoint using `brevia.dependencies.get_dependencies`.\n\nThe recommended way to generate `TOKENS_SECRET` is with openssl:\n\n```bash\nopenssl rand -hex 32\n```\n\nYou can also define a list of valid users as a comma-separated string in the `TOKENS_USERS` environment variable.\n\nFor example, setting `TOKENS_USERS=\"brevia,gustavo\"` means that only `brevia` and `gustavo` are considered valid user names. Remember to use double quotes in a `.env` file.\n\n## Brevia Developer Quick Reference\n\nHere are some brief notes if you want to help develop Brevia.\n\n### Unit Tests\n\nTo run unit tests, make sure you have the `dev` dependencies installed:\n\n```bash\npoetry install --with dev\n```\n\nA `tests/.env` file must be present with test environment variables set. You can start with a copy of `tests/.env.sample`.\nEnsure that `PGVECTOR_*` variables point to a unit test database that will be continuously dropped and recreated. Also, set `USE_TEST_MODELS=True` to use fake LLM instances.\n\nTo run unit tests from the virtualenv:\n\n```bash\npytest tests/\n```\n\nTo generate coverage in HTML format:\n\n```bash\npytest --cov-report html --cov=brevia tests/\n```\n\nThe coverage report is created using `pytest-cov`.\n\n### Update Documentation\n\nInstall `mkdocs-material` using `pip` (do not alter `pyproject.toml`):\n\n```bash\npip install mkdocs-material\n```\n\nWhen working on documentation files, you can use a live preview server with:\n\n```bash\nmkdocs serve\n```\n\nOr build the documentation in the `site/` folder using:\n\n```bash\nmkdocs build --clean\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrevia-ai%2Fbrevia","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbrevia-ai%2Fbrevia","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrevia-ai%2Fbrevia/lists"}