### Bootstrap Demo Environment with Make

Source: https://context7.com/world-open-graph/br-acc/llms.txt

Sets up the full stack environment with synthetic demo data for local development using Make commands. This includes copying environment variables and starting services.

```bash
# Set up environment and start services
cp .env.example .env
make bootstrap-demo
```

--------------------------------

### Quick Local Demo Setup (Bash)

Source: https://github.com/world-open-graph/br-acc/blob/main/docs/reproducibility.md

Sets up a quick, deterministic local demo environment. It involves copying an environment file and running a make command to bootstrap the demo. Expected results include a running health check endpoint and Neo4j Browser.

```bash
cp .env.example .env
make bootstrap-demo
```

--------------------------------

### Configure Environment Variables (Bash)

Source: https://context7.com/world-open-graph/br-acc/llms.txt

Example configuration for environment variables in a .env file. Covers Neo4j connection details, API settings, authentication, security, public mode options, and rate limiting.

```bash
# .env file configuration

# Neo4j Connection
NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=changeme
NEO4J_DATABASE=neo4j

# API Settings
API_HOST=0.0.0.0
API_PORT=8000
LOG_LEVEL=info
APP_ENV=dev  # dev, test, or production

# Authentication
JWT_SECRET_KEY=your-secret-key-minimum-32-chars
JWT_ALGORITHM=HS256
JWT_EXPIRE_MINUTES=1440
INVITE_CODE=optional-registration-code

# Security
CORS_ORIGINS=http://localhost:3000
AUTH_COOKIE_SECURE=false
AUTH_COOKIE_SAMESITE=lax

# Public Mode (privacy controls)
PUBLIC_MODE=true
PUBLIC_ALLOW_PERSON=false
PUBLIC_ALLOW_ENTITY_LOOKUP=false
PUBLIC_ALLOW_INVESTIGATIONS=false
PATTERNS_ENABLED=false

# Rate Limiting
RATE_LIMIT_ANON=60/minute
RATE_LIMIT_AUTH=300/minute
```

--------------------------------

### Initialize Git Repository

Source: https://github.com/world-open-graph/br-acc/blob/main/docs/release/public_repo_release_checklist.md

Initializes a new Git repository in the specified directory, adds all files, and creates an initial commit with a descriptive message. This is a standard Git workflow for starting a new project or preparing for a release.

```bash
cd /tmp/world-transparency-graph-public
git init
git add .
git commit -m "Initial public release (WTG)"
```

--------------------------------

### Export Investigation to PDF via API

Source: https://context7.com/world-open-graph/br-acc/llms.txt

Generates a PDF report for a given investigation by sending a GET request to the export endpoint. Supports language selection via query parameter.

```bash
curl "http://localhost:8000/api/v1/investigations/inv-uuid-here/export/pdf?lang=en" \
  -H "Authorization: Bearer $TOKEN" \
  -o investigation-report.pdf
```

--------------------------------

### GET /api/v1/investigations/{investigation_id}/export/pdf

Source: https://context7.com/world-open-graph/br-acc/llms.txt

Generates a PDF report of an investigation, including all entities and annotations.

```APIDOC
## GET /api/v1/investigations/{investigation_id}/export/pdf

### Description
Generates a PDF report of an investigation with all entities and annotations.

### Method
GET

### Endpoint
/api/v1/investigations/{investigation_id}/export/pdf

### Parameters
#### Path Parameters
- **investigation_id** (string) - Required - The ID of the investigation to export.

#### Query Parameters
- **lang** (string) - Optional - The language for the report. Available options: 'pt' (Portuguese), 'en' (English). Defaults to 'en'.

### Response
#### Success Response (200)
A PDF file containing the investigation report.

### Response Example
(Returns a PDF file, not a JSON object)
```

--------------------------------

### Make Commands

Source: https://context7.com/world-open-graph/br-acc/llms.txt

Utility commands for setting up the development environment and running data ingestion.

```APIDOC
## Quick Start with Make Commands

### Bootstrap Demo Environment

#### Description
Starts the full stack with synthetic demo data for local development.

#### Commands
1. **Copy environment file:**
   ```bash
   cp .env.example .env
   ```
2. **Bootstrap demo environment:**
   ```bash
   make bootstrap-demo
   ```

#### Services Available After Bootstrap:
- **API:** `http://localhost:8000/health`
- **Frontend:** `http://localhost:3000`
- **Neo4j Browser:** `http://localhost:7474`

#### Verify Services:
```bash
curl http://localhost:8000/health
curl http://localhost:8000/api/v1/public/meta
```

### Full Data Ingestion

#### Description
Downloads and ingests data from all implemented sources.

#### Download Commands:
- `make download-cnpj`      # Company registry (1 file per type)
- `make download-tse`       # Electoral data (2024)
- `make download-transparencia`  # Federal transparency data
- `make download-sanctions` # CEIS/CNEP sanctions

#### ETL Run Commands:
```bash
export NEO4J_PASSWORD=your-password

make etl-cnpj          # Full CNPJ ingestion
make etl-cnpj-dev      # Limited rows for development
make etl-tse           # Electoral donations
make etl-transparencia # Contracts and finances
```
```

--------------------------------

### Run Full Bootstrap (Shell)

Source: https://context7.com/world-open-graph/br-acc/llms.txt

Executes the complete bootstrap process for all data sources. This operation can be time-consuming.

```shell
make bootstrap-all
```

--------------------------------

### Create Custom Data Pipeline (Python)

Source: https://context7.com/world-open-graph/br-acc/llms.txt

Demonstrates how to create a custom data ingestion pipeline by extending the base Pipeline class. It includes extract, transform, and load methods for processing data from a CSV file and loading it into Neo4j.

```python
from bracc_etl.base import Pipeline
from bracc_etl.loader import Neo4jBatchLoader
import pandas as pd

class CustomDataPipeline(Pipeline):
    name = "custom_source"
    source_id = "custom_source"

    def __init__(self, driver, data_dir="./data", **kwargs):
        super().__init__(driver, data_dir, **kwargs)
        self.records = []

    def extract(self):
        """Download or read raw data from source."""
        df = pd.read_csv(f"{self.data_dir}/custom/data.csv")
        self.raw_data = df
        self.rows_in = len(df)

    def transform(self):
        """Normalize and prepare data for Neo4j."""
        for _, row in self.raw_data.iterrows():
            self.records.append({
                "id": str(row["id"]),
                "name": str(row["name"]).strip().upper(),
                "value": float(row.get("value", 0)),
                "source": self.source_id,
            })

    def load(self):
        """Load transformed data into Neo4j."""
        loader = Neo4jBatchLoader(self.driver, batch_size=self.chunk_size)
        loader.load_nodes("CustomEntity", self.records, key_field="id")
        self.rows_loaded = len(self.records)

# Usage
from neo4j import GraphDatabase

driver = GraphDatabase.driver("bolt://localhost:7687", auth=("neo4j", "password"))
pipeline = CustomDataPipeline(driver, data_dir="./data", limit=1000)
pipeline.run()  # Executes extract -> transform -> load
driver.close()
```

--------------------------------

### List Configured Data Sources

Source: https://context7.com/world-open-graph/br-acc/llms.txt

Retrieves a list of all data sources currently configured and loaded in the system. This endpoint is useful for understanding available data and their statuses. It does not require authentication.

```bash
curl http://localhost:8000/api/v1/meta/sources
```

--------------------------------

### Full Data Ingestion with Make

Source: https://context7.com/world-open-graph/br-acc/llms.txt

Performs full data ingestion for various sources using Make commands. This includes downloading specific data sources and running their respective ETL processes.

```bash
# Download specific data sources
make download-cnpj      # Company registry (1 file per type)
make download-tse       # Electoral data (2024)
make download-transparencia  # Federal transparency data
make download-sanctions # CEIS/CNEP sanctions

# Run ETL for specific sources
export NEO4J_PASSWORD=your-password
make etl-cnpj          # Full CNPJ ingestion
make etl-cnpj-dev      # Limited rows for development
make etl-tse           # Electoral donations
make etl-transparencia # Contracts and finances
```

--------------------------------

### Prepare Public Snapshot Script

Source: https://github.com/world-open-graph/br-acc/blob/main/docs/release/public_repo_release_checklist.md

Executes a bash script to create a sanitized snapshot of the project for public release. It takes the source directory and the destination directory as arguments.

```bash
bash scripts/prepare_public_snapshot.sh /Users/brunoclz/CORRUPTOS /tmp/world-transparency-graph-public
```

--------------------------------

### Full Ingestion Orchestration with Docker

Source: https://github.com/world-open-graph/br-acc/blob/main/README.md

This snippet shows commands for orchestrating a full data ingestion process using Docker and all implemented pipelines. It includes options for a standard heavy run, a non-interactive version for automation, and a command to print the report of the latest full ingestion.

```bash
# Heavy full ingestion orchestration (Docker + all implemented pipelines)
make bootstrap-all

# Noninteractive heavy run (automation)
make bootstrap-all-noninteractive

# Print latest bootstrap-all report
make bootstrap-all-report
```

--------------------------------

### Push Initial Release to GitHub

Source: https://github.com/world-open-graph/br-acc/blob/main/docs/release/public_repo_release_checklist.md

Configures the main branch to 'main' and adds a remote origin pointing to the GitHub repository. It then pushes the initial commit to the remote repository, making the code publicly accessible.

```bash
git branch -M main
git remote add origin https://github.com/brunoclz/world-transparency-graph.git
git push -u origin main
```

--------------------------------

### List ETL Pipelines CLI

Source: https://context7.com/world-open-graph/br-acc/llms.txt

Lists all available data source pipelines managed by the bracc-etl CLI. Can optionally display ingestion status from Neo4j.

```bash
# List available pipelines
bracc-etl sources

# Show ingestion status from Neo4j
bracc-etl sources --status --neo4j-password "$NEO4J_PASSWORD"
```

--------------------------------

### List Data Sources

Source: https://context7.com/world-open-graph/br-acc/llms.txt

Retrieves a list of all configured data sources available in the system.

```APIDOC
## GET /api/v1/meta/sources

### Description
Lists all configured data sources.

### Method
GET

### Endpoint
/api/v1/meta/sources

### Parameters
None

### Request Example
```bash
curl http://localhost:8000/api/v1/meta/sources
```

### Response
#### Success Response (200)
- **sources** (array) - An array of data source objects.
  - **name** (string) - The name of the data source.
  - **description** (string) - A description of the data source.
  - **status** (string) - The loading status of the data source.

#### Response Example
```json
{
  "sources": [
    {"name": "receita_federal", "description": "Company Registry (CNPJ)", "status": "loaded"},
    {"name": "tse", "description": "Electoral Data", "status": "loaded"},
    {"name": "transparencia", "description": "Portal da Transparência", "status": "loaded"}
  ]
}
```
```

--------------------------------

### Run ETL Pipeline CLI

Source: https://context7.com/world-open-graph/br-acc/llms.txt

Executes a specified ETL pipeline to download, transform, and load data into Neo4j. Supports various options like chunk size, row limits, streaming, and history modes.

```bash
# Run the CNPJ (company registry) pipeline
bracc-etl run \
  --source cnpj \
  --neo4j-uri bolt://localhost:7687 \
  --neo4j-user neo4j \
  --neo4j-password "$NEO4J_PASSWORD" \
  --data-dir ./data \
  --chunk-size 50000

# Run with row limit for development
bracc-etl run \
  --source cnpj \
  --neo4j-password "$NEO4J_PASSWORD" \
  --data-dir ./data \
  --limit 10000

# Run in streaming mode for large datasets
bracc-etl run \
  --source cnpj \
  --neo4j-password "$NEO4J_PASSWORD" \
  --data-dir ./data \
  --streaming

# Run with historical data mode
bracc-etl run \
  --source cnpj \
  --neo4j-password "$NEO4J_PASSWORD" \
  --data-dir ./data \
  --history
```

--------------------------------

### Register New User Account

Source: https://context7.com/world-open-graph/br-acc/llms.txt

Registers a new user account. In controlled deployments, an invite code is mandatory. This API requires a JSON payload containing the user's email, password, and optionally an invite code.

```bash
curl -X POST http://localhost:8000/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "securePassword123",
    "invite_code": "your-invite-code"
  }'
```

--------------------------------

### Download CNPJ Data CLI

Source: https://context7.com/world-open-graph/br-acc/llms.txt

Downloads company registry data from Receita Federal using the bracc-etl CLI. Allows specifying the number of files to download and pinning to specific monthly releases.

```bash
# Download reference tables and 1 file per type (for testing)
bracc-etl download --output-dir ./data/cnpj --files 1

# Download all files (production)
bracc-etl download --output-dir ./data/cnpj --files 10

# Pin to specific monthly release
bracc-etl download --output-dir ./data/cnpj --files 10 --release 2024-03
```

--------------------------------

### List Data Sources

Source: https://context7.com/world-open-graph/br-acc/llms.txt

Returns information about all data sources configured in the system with their status.

```APIDOC
## GET /api/v1/sources

### Description
Returns information about all data sources configured in the system with their status.

### Method
GET

### Endpoint
/api/v1/sources

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
curl http://localhost:8000/api/v1/sources
```

### Response
#### Success Response (200)
- **sources** (array) - A list of data sources.
  - **name** (string) - The name of the data source.
  - **status** (string) - The status of the data source (e.g., 'healthy', 'stale', 'blocked').
  - **last_updated** (string) - The timestamp of the last update.
  - **record_count** (integer) - The number of records from this source.

#### Response Example
```json
{
  "sources": [
    {
      "name": "receita_federal",
      "status": "healthy",
      "last_updated": "2023-10-27T10:00:00Z",
      "record_count": 4500000
    },
    {
      "name": "tse",
      "status": "stale",
      "last_updated": "2023-09-15T08:30:00Z",
      "record_count": 45000
    }
  ]
}
```
```

--------------------------------

### ETL Pipeline CLI

Source: https://context7.com/world-open-graph/br-acc/llms.txt

Command-line interface for managing and running ETL pipelines.

```APIDOC
## ETL Pipeline CLI

### List Available Pipelines

#### Description
Displays all available data source pipelines with optional ingestion status.

#### Command
`bracc-etl sources [--status] [--neo4j-password <password>]`

#### Options
- `--status`: Show ingestion status from Neo4j.
- `--neo4j-password <password>`: The password for Neo4j authentication.

#### Example Output (Sources)
```
Available pipelines:
  bcb
  bndes
  camara
  cnpj
  comprasnet
  ...
```

#### Example Output (Status)
```
Source               Status          Rows In    Loaded    Started              Finished
----------------------------------------------------------------------------------------------------
cnpj                 loaded       45,230,000 45,230,000 2024-03-01T08:00:00  2024-03-01T12:30:00
tse                  loaded        1,250,000  1,250,000 2024-03-01T13:00:00  2024-03-01T13:45:00
```

### Run ETL Pipeline

#### Description
Executes a specific ETL pipeline to download, transform, and load data into Neo4j.

#### Command
`bracc-etl run --source <source_name> [--neo4j-uri <uri>] [--neo4j-user <user>] [--neo4j-password <password>] [--data-dir <directory>] [--chunk-size <size>] [--limit <rows>] [--streaming] [--history]`

#### Options
- `--source <source_name>`: The name of the ETL pipeline to run (e.g., `cnpj`).
- `--neo4j-uri <uri>`: The URI for the Neo4j database.
- `--neo4j-user <user>`: The username for Neo4j authentication.
- `--neo4j-password <password>`: The password for Neo4j authentication.
- `--data-dir <directory>`: The directory to store downloaded data.
- `--chunk-size <size>`: The number of rows to process per chunk.
- `--limit <rows>`: Limit the number of rows to process (useful for development).
- `--streaming`: Enable streaming mode for large datasets.
- `--history`: Enable historical data mode.

#### Example Commands
```bash
# Run the CNPJ pipeline
bracc-etl run \
  --source cnpj \
  --neo4j-uri bolt://localhost:7687 \
  --neo4j-user neo4j \
  --neo4j-password "$NEO4J_PASSWORD" \
  --data-dir ./data \
  --chunk-size 50000

# Run with row limit for development
bracc-etl run \
  --source cnpj \
  --neo4j-password "$NEO4J_PASSWORD" \
  --data-dir ./data \
  --limit 10000

# Run in streaming mode
bracc-etl run \
  --source cnpj \
  --neo4j-password "$NEO4J_PASSWORD" \
  --data-dir ./data \
  --streaming

# Run with historical data mode
bracc-etl run \
  --source cnpj \
  --neo4j-password "$NEO4J_PASSWORD" \
  --data-dir ./data \
  --history
```

### Download CNPJ Data

#### Description
Downloads company registry data from Receita Federal.

#### Command
`bracc-etl download --output-dir <directory> --files <count> [--release <YYYY-MM>]`

#### Options
- `--output-dir <directory>`: The directory to save the downloaded files.
- `--files <count>`: The number of files to download per type. Use `1` for testing, `10` for production.
- `--release <YYYY-MM>`: Pin the download to a specific monthly release (e.g., `2024-03`).

#### Example Commands
```bash
# Download reference tables and 1 file per type (for testing)
bracc-etl download --output-dir ./data/cnpj --files 1

# Download all files (production)
bracc-etl download --output-dir ./data/cnpj --files 10

# Pin to specific monthly release
bracc-etl download --output-dir ./data/cnpj --files 10 --release 2024-03
```
```

--------------------------------

### Generate Synthetic Demo Dataset using Python

Source: https://github.com/world-open-graph/br-acc/blob/main/data/demo/README.md

This snippet demonstrates how to generate a synthetic demo dataset using a Python script. It requires Python 3 and the script is located at 'scripts/generate_demo_dataset.py'. The output is saved to 'data/demo/synthetic_graph.json'.

```bash
python3 scripts/generate_demo_dataset.py --output data/demo/synthetic_graph.json
```

--------------------------------

### User Registration API

Source: https://context7.com/world-open-graph/br-acc/llms.txt

Handles the registration of new user accounts. An invite code may be required in certain deployment scenarios.

```APIDOC
## POST /api/v1/auth/register

### Description
Registers a new user account. Requires an invite code in controlled deployments.

### Method
POST

### Endpoint
/api/v1/auth/register

### Parameters
#### Request Body
- **email** (string) - Required - The email address for the new user.
- **password** (string) - Required - The password for the new user.
- **invite_code** (string) - Optional - The invite code for registration.

### Request Example
```json
{
  "email": "user@example.com",
  "password": "securePassword123",
  "invite_code": "your-invite-code"
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the newly created user.
- **email** (string) - The email address of the registered user.

#### Response Example
```json
{
  "id": "user-uuid-here",
  "email": "user@example.com"
}
```
```

--------------------------------

### BYO-Data Ingestion with ETL (Bash)

Source: https://github.com/world-open-graph/br-acc/blob/main/docs/reproducibility.md

Directly uses the ETL (Extract, Transform, Load) tools for data ingestion. This involves navigating to the ETL directory, synchronizing dependencies, and running specific ETL jobs for selected sources, such as 'cnpj'. Requires setting up environment variables like NEO4J_PASSWORD.

```bash
cd etl
uv sync
uv run bracc-etl sources
uv run bracc-etl run --source cnpj --neo4j-password "$NEO4J_PASSWORD" --data-dir ../data
```

--------------------------------

### Use Neo4j Batch Loader (Python)

Source: https://context7.com/world-open-graph/br-acc/llms.txt

Utilizes the Neo4jBatchLoader for efficient bulk loading of nodes and relationships into a Neo4j database. Supports loading nodes, relationships, and executing custom Cypher queries.

```python
from neo4j import GraphDatabase
from bracc_etl.loader import Neo4jBatchLoader

driver = GraphDatabase.driver("bolt://localhost:7687", auth=("neo4j", "password"))
loader = Neo4jBatchLoader(driver, batch_size=10000)

# Load company nodes
companies = [
    {"cnpj": "33.000.167/0001-01", "razao_social": "PETROBRAS", "uf": "RJ"},
    {"cnpj": "60.746.948/0001-12", "razao_social": "BRADESCO", "uf": "SP"},
]
loader.load_nodes("Company", companies, key_field="cnpj")

# Load relationships
relationships = [
    {"source_key": "123.456.789-00", "target_key": "33.000.167/0001-01",
     "qualificacao": "Diretor", "data_entrada": "2020-01-15"},
]
loader.load_relationships(
    rel_type="SOCIO_DE",
    rows=relationships,
    source_label="Person",
    source_key="cpf",
    target_label="Company",
    target_key="cnpj",
    properties=["qualificacao", "data_entrada"],
)

# Execute custom Cypher query
loader.run_query(
    "MATCH (c:Company {cnpj: $cnpj}) SET c.updated_at = datetime()",
    [{"cnpj": "33.000.167/0001-01"}]
)

driver.close()
```

--------------------------------

### One-Script End-to-End Orchestration (Bash)

Source: https://github.com/world-open-graph/br-acc/blob/main/docs/reproducibility.md

Orchestrates the data ingestion process using a single script with different profiles and options. Supports demo, full, and CI/automation runs, including pipeline selection and data downloading. The 'full' profile may depend on external data sources and machine resources.

```bash
# Demo profile
bash scripts/bootstrap_public_demo.sh --profile demo

# Full profile (orchestrates docker + ETL loop)
bash scripts/bootstrap_public_demo.sh --profile full --pipelines cnpj,tse,transparencia,sanctions --download

# Heavy one-command full ingestion (all implemented pipelines from contract)
make bootstrap-all

# Noninteractive heavy run (CI/automation)
make bootstrap-all-noninteractive
```

--------------------------------

### Perform Privacy and Compliance Checks

Source: https://github.com/world-open-graph/br-acc/blob/main/docs/release/public_repo_release_checklist.md

Runs Python scripts to verify public privacy, compliance pack adherence, and open core boundary rules. These checks ensure the repository meets the necessary security and legal standards before launch.

```python
python scripts/check_public_privacy.py --repo-root .
python scripts/check_compliance_pack.py --repo-root .
python scripts/check_open_core_boundary.py --repo-root .
```

--------------------------------

### Retrieve Full Entity Graph Visualization

Source: https://context7.com/world-open-graph/br-acc/llms.txt

Retrieves the complete graph visualization data for an entity, including nodes and edges. Supports configurable depth and entity type filtering. Includes supernode protection to manage complexity. Requires an 'Authorization' header with a valid Bearer token.

```bash
# Get graph for entity (up to depth 4)
curl "http://localhost:8000/api/v1/graph/4:abc123:0?depth=3&entity_types=company,contract,sanction" \
  -H "Authorization: Bearer $TOKEN"
```

--------------------------------

### Create Investigation via API

Source: https://context7.com/world-open-graph/br-acc/llms.txt

Creates a new investigation by sending a POST request to the /api/v1/investigations/ endpoint. Requires an Authorization token and a JSON payload with title and description.

```bash
curl -X POST http://localhost:8000/api/v1/investigations/ \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Public Contract Analysis Q1 2024",
    "description": "Investigating contract patterns in São Paulo region"
  }'
```

--------------------------------

### POST /api/v1/investigations/

Source: https://context7.com/world-open-graph/br-acc/llms.txt

Creates a new investigation with a title and description.

```APIDOC
## POST /api/v1/investigations/

### Description
Creates a new investigation with a title and description.

### Method
POST

### Endpoint
/api/v1/investigations/

### Parameters
#### Request Body
- **title** (string) - Required - The title of the investigation.
- **description** (string) - Required - A detailed description of the investigation.

### Request Example
```json
{
  "title": "Public Contract Analysis Q1 2024",
  "description": "Investigating contract patterns in São Paulo region"
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the created investigation.
- **title** (string) - The title of the investigation.
- **description** (string) - The description of the investigation.
- **entity_ids** (array) - An array of entity IDs associated with the investigation.
- **created_at** (string) - The timestamp when the investigation was created.
- **updated_at** (string) - The timestamp when the investigation was last updated.

#### Response Example
```json
{
  "id": "inv-uuid-here",
  "title": "Public Contract Analysis Q1 2024",
  "description": "Investigating contract patterns in São Paulo region",
  "entity_ids": [],
  "created_at": "2024-03-15T10:30:00Z",
  "updated_at": "2024-03-15T10:30:00Z"
}
```
```

--------------------------------

### Retrieve Entity Timeline

Source: https://context7.com/world-open-graph/br-acc/llms.txt

Fetches a chronological list of events related to an entity. Supports pagination using a cursor and a limit parameter. Requires an 'Authorization' header with a valid Bearer token. The entity ID is part of the URL path.

```bash
# Get entity timeline
curl "http://localhost:8000/api/v1/entity/4:abc123:0/timeline?limit=20" \
  -H "Authorization: Bearer $TOKEN"
```

```bash
# Paginate with cursor
curl "http://localhost:8000/api/v1/entity/4:abc123:0/timeline?limit=20&cursor=2024-01-15" \
  -H "Authorization: Bearer $TOKEN"
```

--------------------------------

### Retrieve Entity by Document ID

Source: https://context7.com/world-open-graph/br-acc/llms.txt

Fetches detailed information about an entity using its unique document identifier (CPF for individuals, CNPJ for companies). The API supports both raw and formatted document numbers. Requires an 'Authorization' header with a valid Bearer token.

```bash
# Get company by CNPJ
curl http://localhost:8000/api/v1/entity/33000167000101 \
  -H "Authorization: Bearer $TOKEN"
```

```bash
# Get entity by formatted document
curl http://localhost:8000/api/v1/entity/33.000.167/0001-01 \
  -H "Authorization: Bearer $TOKEN"
```

--------------------------------

### Entity API

Source: https://context7.com/world-open-graph/br-acc/llms.txt

Provides endpoints for retrieving and analyzing entity information, including details, connections, and timelines. Requires authentication.

```APIDOC
## GET /api/v1/entity/{document_id}

### Description
Retrieves detailed information about an entity using its document ID (CPF or CNPJ).

### Method
GET

### Endpoint
/api/v1/entity/{document_id}

### Parameters
#### Path Parameters
- **document_id** (string) - Required - The document ID (CPF or CNPJ) of the entity. Can be formatted or unformatted.

### Request Example
```bash
# Get company by CNPJ
curl http://localhost:8000/api/v1/entity/33000167000101 \
  -H "Authorization: Bearer $TOKEN"

# Get entity by formatted document
curl http://localhost:8000/api/v1/entity/33.000.167/0001-01 \
  -H "Authorization: Bearer $TOKEN"
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the entity.
- **type** (string) - The type of the entity (e.g., 'company', 'person').
- **entity_label** (string) - A human-readable label for the entity type.
- **identity_quality** (any) - Quality assessment of the entity's identity information.
- **properties** (object) - Key-value pairs of entity-specific properties.
- **sources** (array) - List of databases where the entity information was found.
- **is_pep** (boolean) - Indicates if the entity is a Politically Exposed Person.
- **exposure_tier** (string) - The exposure tier of the entity.

#### Response Example
```json
{
  "id": "4:abc123:0",
  "type": "company",
  "entity_label": "Company",
  "identity_quality": null,
  "properties": {
    "razao_social": "PETROBRAS",
    "cnpj": "33.000.167/0001-01",
    "capital_social": 205431960490.52,
    "uf": "RJ"
  },
  "sources": [{"database": "receita_federal"}],
  "is_pep": false,
  "exposure_tier": "public_safe"
}
```
```

```APIDOC
## GET /api/v1/entity/{entity_id}/connections

### Description
Retrieves connections for a given entity, with options to control depth and filter by connection types.

### Method
GET

### Endpoint
/api/v1/entity/{entity_id}/connections

### Parameters
#### Path Parameters
- **entity_id** (string) - Required - The unique identifier of the entity.

#### Query Parameters
- **depth** (integer) - Optional - The maximum depth of connections to retrieve. Defaults to 1.
- **types** (string) - Optional - A comma-separated list of connection types to filter by (e.g., 'company,contract').

### Request Example
```bash
# Get entity connections with depth 2
curl "http://localhost:8000/api/v1/entity/4:abc123:0/connections?depth=2&types=company,contract" \
  -H "Authorization: Bearer $TOKEN"
```

### Response
#### Success Response (200)
- **entity** (object) - Information about the central entity.
- **connections** (array) - An array of connection objects between entities.
  - **source_id** (string) - The ID of the source entity in the connection.
  - **target_id** (string) - The ID of the target entity in the connection.
  - **relationship_type** (string) - The type of relationship.
  - **properties** (object) - Properties associated with the connection.
  - **confidence** (number) - Confidence score of the connection.
- **connected_entities** (array) - Information about entities involved in the connections.

#### Response Example
```json
{
  "entity": {
    "id": "4:abc123:0",
    "type": "company",
    "properties": {}
  },
  "connections": [
    {
      "source_id": "4:abc123:0",
      "target_id": "4:def456:0",
      "relationship_type": "CONTRATADO_POR",
      "properties": {"value": 1500000.00},
      "confidence": 1.0
    }
  ],
  "connected_entities": [
    {"id": "4:def456:0", "type": "contract", "properties": {}}
  ]
}
```
```

```APIDOC
## GET /api/v1/entity/{entity_id}/timeline

### Description
Retrieves a chronological timeline of events related to an entity, supporting cursor-based pagination.

### Method
GET

### Endpoint
/api/v1/entity/{entity_id}/timeline

### Parameters
#### Path Parameters
- **entity_id** (string) - Required - The unique identifier of the entity.

#### Query Parameters
- **limit** (integer) - Optional - The maximum number of events to return per page. Defaults to 20.
- **cursor** (string) - Optional - A cursor for paginating results. Use the `next_cursor` from a previous response.

### Request Example
```bash
# Get entity timeline
curl "http://localhost:8000/api/v1/entity/4:abc123:0/timeline?limit=20" \
  -H "Authorization: Bearer $TOKEN"

# Paginate with cursor
curl "http://localhost:8000/api/v1/entity/4:abc123:0/timeline?limit=20&cursor=2024-01-15" \
  -H "Authorization: Bearer $TOKEN"
```

### Response
#### Success Response (200)
- **entity_id** (string) - The ID of the entity whose timeline is being retrieved.
- **events** (array) - An array of event objects.
  - **id** (string) - The unique identifier of the event.
  - **date** (string) - The date of the event (YYYY-MM-DD).
  - **label** (string) - A description of the event.
  - **entity_type** (string) - The type of entity associated with the event.
  - **properties** (object) - Properties related to the event.
- **total** (integer) - The total number of events available.
- **next_cursor** (string) - A cursor for fetching the next page of results.

#### Response Example
```json
{
  "entity_id": "4:abc123:0",
  "events": [
    {
      "id": "4:event789:0",
      "date": "2024-03-15",
      "label": "Contract Award",
      "entity_type": "Contract",
      "properties": {"value": 500000.00, "object": "IT Services"}
    }
  ],
  "total": 20,
  "next_cursor": "2024-01-15"
}
```
```

--------------------------------

### Retrieve Entity Connections

Source: https://context7.com/world-open-graph/br-acc/llms.txt

Retrieves all connections associated with a specific entity up to a defined depth. It allows filtering connections by type and requires an 'Authorization' header with a valid Bearer token. The entity ID is part of the URL path.

```bash
# Get entity connections with depth 2
curl "http://localhost:8000/api/v1/entity/4:abc123:0/connections?depth=2&types=company,contract" \
  -H "Authorization: Bearer $TOKEN"
```

--------------------------------

### Pattern Analysis API

Source: https://github.com/world-open-graph/br-acc/blob/main/README.md

Performs and returns pattern analysis for a specific company, if enabled.

```APIDOC
## GET /api/v1/public/patterns/company/{cnpj_or_id}

### Description
Performs and returns pattern analysis for a specific company, if the pattern analysis feature is enabled.

### Method
GET

### Endpoint
/api/v1/public/patterns/company/{cnpj_or_id}

### Parameters
#### Path Parameters
- **cnpj_or_id** (string) - Required - The CNPJ or unique identifier of the company.

#### Query Parameters
None

#### Request Body
None

### Response
#### Success Response (200)
- **pattern_results** (object) - The results of the pattern analysis for the specified company.

#### Response Example
```json
{
  "pattern_results": {
    "pattern_type": "growth_trend",
    "confidence_score": 0.85,
    "details": "Consistent revenue increase over the last 5 quarters."
  }
}
```
```

--------------------------------

### User Login API

Source: https://context7.com/world-open-graph/br-acc/llms.txt

Authenticates users and issues a JWT token, which is also set as an HTTP-only cookie for subsequent requests.

```APIDOC
## POST /api/v1/auth/login

### Description
Authenticates and receives a JWT token. Token is also set as an HTTP-only cookie.

### Method
POST

### Endpoint
/api/v1/auth/login

### Parameters
#### Query Parameters
- **username** (string) - Required - The user's email address.
- **password** (string) - Required - The user's password.

### Request Example
```bash
curl -X POST http://localhost:8000/api/v1/auth/login \
  -d "username=user@example.com&password=securePassword123"
```

### Response
#### Success Response (200)
- **access_token** (string) - The JWT access token for authenticated requests.

#### Response Example
```json
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

### Usage in Subsequent Requests
```bash
curl http://localhost:8000/api/v1/auth/me \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
```
```

--------------------------------

### Public Metadata and Statistics

Source: https://context7.com/world-open-graph/br-acc/llms.txt

Returns aggregated metrics about the graph database including node counts, relationship counts, and source health information.

```APIDOC
## GET /api/v1/public/meta

### Description
Returns aggregated metrics about the graph database including node counts, relationship counts, and source health information.

### Method
GET

### Endpoint
/api/v1/public/meta

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
curl http://localhost:8000/api/v1/public/meta
```

### Response
#### Success Response (200)
- **product** (string) - The name of the product.
- **mode** (string) - The operational mode of the API.
- **total_nodes** (integer) - The total number of nodes in the graph.
- **total_relationships** (integer) - The total number of relationships in the graph.
- **company_count** (integer) - The number of companies in the graph.
- **contract_count** (integer) - The number of contracts in the graph.
- **sanction_count** (integer) - The number of sanctions in the graph.
- **finance_count** (integer) - The number of financial records in the graph.
- **bid_count** (integer) - The number of bids in the graph.
- **inquiry_count** (integer) - The number of inquiries in the graph.
- **source_health** (object) - An object containing statistics about data source health.
  - **data_sources** (integer) - The number of data sources.
  - **implemented_sources** (integer) - The number of implemented data sources.
  - **loaded_sources** (integer) - The number of loaded data sources.
  - **healthy_sources** (integer) - The number of healthy data sources.
  - **stale_sources** (integer) - The number of stale data sources.
  - **blocked_external_sources** (integer) - The number of blocked external data sources.
  - **quality_fail_sources** (integer) - The number of data sources that failed quality checks.
  - **discovered_uningested_sources** (integer) - The number of discovered but uningested data sources.

#### Response Example
```json
{
  "product": "World Transparency Graph",
  "mode": "public_safe",
  "total_nodes": 5432100,
  "total_relationships": 12500000,
  "company_count": 4500000,
  "contract_count": 250000,
  "sanction_count": 15000,
  "finance_count": 180000,
  "bid_count": 95000,
  "inquiry_count": 1200,
  "source_health": {
    "data_sources": 39,
    "implemented_sources": 45,
    "loaded_sources": 38,
    "healthy_sources": 35,
    "stale_sources": 2,
    "blocked_external_sources": 1,
    "quality_fail_sources": 0,
    "discovered_uningested_sources": 3
  }
}
```
```

--------------------------------

### Authenticate User and Obtain JWT

Source: https://context7.com/world-open-graph/br-acc/llms.txt

Authenticates a user using their email and password via OAuth2 form data. Upon successful authentication, it returns a JWT access token, which is also set as an HTTP-only cookie. This token is required for accessing protected API endpoints.

```bash
# Login with username/password (OAuth2 form)
curl -X POST http://localhost:8000/api/v1/auth/login \
  -d "username=user@example.com&password=securePassword123"
```

```bash
# Use the token in subsequent requests
curl http://localhost:8000/api/v1/auth/me \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
```

--------------------------------

### Database Statistics

Source: https://context7.com/world-open-graph/br-acc/llms.txt

Returns detailed statistics about all entity types in the database and data source health status.

```APIDOC
## GET /api/v1/meta/stats

### Description
Returns detailed statistics about all entity types in the database and data source health status.

### Method
GET

### Endpoint
/api/v1/meta/stats

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
curl http://localhost:8000/api/v1/meta/stats
```

### Response
#### Success Response (200)
- **total_nodes** (integer) - The total number of nodes in the graph.
- **total_relationships** (integer) - The total number of relationships in the graph.
- **company_count** (integer) - The number of companies in the graph.
- **person_count** (integer) - The number of persons in the graph (hidden in public mode).
- **contract_count** (integer) - The number of contracts in the graph.
- **sanction_count** (integer) - The number of sanctions in the graph.
- **election_count** (integer) - The number of election records in the graph.
- **amendment_count** (integer) - The number of amendment records in the graph.
- **embargo_count** (integer) - The number of embargo records in the graph.
- **offshore_entity_count** (integer) - The number of offshore entities in the graph.
- **cpi_count** (integer) - The number of CPI (Comissão Parlamentar de Inquérito) records in the graph.
- **data_sources** (integer) - The number of data sources.
- **implemented_sources** (integer) - The number of implemented data sources.
- **loaded_sources** (integer) - The number of loaded data sources.

#### Response Example
```json
{
  "total_nodes": 5432100,
  "total_relationships": 12500000,
  "company_count": 4500000,
  "person_count": 0,
  "contract_count": 250000,
  "sanction_count": 15000,
  "election_count": 45000,
  "amendment_count": 12000,
  "embargo_count": 8500,
  "offshore_entity_count": 2500,
  "cpi_count": 1200,
  "data_sources": 39,
  "implemented_sources": 45,
  "loaded_sources": 38
}
```
```