Metadata-Version: 2.4
Name: gaard-api
Version: 0.2.20
Summary: GAARD backend web services providing admin interface
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: gaard-core==0.2.20
Requires-Dist: gaard-connectors==0.2.20
Requires-Dist: gaard-llm==0.2.20
Requires-Dist: gaard-plugin-api<0.3.0,>=0.2.20
Requires-Dist: fastapi>=0.111.0
Requires-Dist: uvicorn[standard]>=0.30.0
Requires-Dist: pydantic>=2.7.0
Requires-Dist: python-multipart>=0.0.9
Requires-Dist: sqlalchemy>=2.0.0
Requires-Dist: httpx2>=2.5.0
Requires-Dist: certifi>=2024.8.30
Provides-Extra: oracle
Requires-Dist: oracledb>=2.0.0; extra == "oracle"
Provides-Extra: mssql
Requires-Dist: pyodbc>=5.0.0; extra == "mssql"
Provides-Extra: odbc
Requires-Dist: pyodbc>=5.0.0; extra == "odbc"
Provides-Extra: ibm-db2
Requires-Dist: ibm-db-sa>=0.4.4; extra == "ibm-db2"
Provides-Extra: teradata
Requires-Dist: teradatasqlalchemy>=20.0.0.9; extra == "teradata"
Provides-Extra: all-datasources
Requires-Dist: oracledb>=2.0.0; extra == "all-datasources"
Requires-Dist: pyodbc>=5.0.0; extra == "all-datasources"
Requires-Dist: ibm-db-sa>=0.4.4; extra == "all-datasources"
Requires-Dist: teradatasqlalchemy>=20.0.0.9; extra == "all-datasources"
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: ruff>=0.5.0; extra == "dev"
Requires-Dist: mypy>=1.10.0; extra == "dev"
Requires-Dist: psycopg[binary]>=3.2.0; extra == "dev"
Requires-Dist: pymysql>=1.2.0; extra == "dev"

# GAARD - Governed AI Access to Relational Data

GAARD is a self-hosted AI SQL Gateway for governed natural-language access to relational data.

GAARD allows applications and users to ask questions about relational databases using natural language while keeping SQL generation, validation, execution, prompts, connectors, and auditability under control.

For more informacion see https://github.com/pkroliszewski/gaard

# This package

`gaard-api` provides the GAARD FastAPI backend and bundled admin application.

After installation, start it with:

```bash
gaard-core install-example-database
gaard-core start
```

`gaard-core install-example-database` creates the bundled Medical POC SQLite
database at `examples/medical-poc/demo.db` in the current working directory,
registers it as the active `default` datasource in `metadata.db`, and matches
the default datasource URL. Use
`gaard-core install-example-database --output /path/to/demo.db` to place it
elsewhere; the command prints the SQLite datasource URL saved in metadata.

`gaard-core start` accepts `--host`, `--port`, and `--reload`. By default the
API is available at `http://localhost:8000` and the admin application at
`http://localhost:8000/admin`.

`gaard-api start` is an alias. `gaard admin` remains available for compatibility.

## Conversation context

With `context_mode: "auto"`, each question stores a `new_topic` or `follow_up`
decision. The LLM receives all turns since the last `new_topic`, including that
question. For a follow-up, a separate LLM call compresses this context together
with the current question into one standalone sentence. Both calls use
temperature zero. The resulting sentence is saved before SQL or Analysis runs;
a new topic uses the current question as its context.

`GET /api/v1/conversations/{conversation_id}/turns/{turn_id}/context` returns
the saved execution-time snapshot as JSON with `context`, `context_decision`,
`conversation_id`, and `turn_id`. The IDs are available in the query response's
`metadata.conversation` object. This authenticated endpoint only allows the
conversation owner and never regenerates the context from later messages.

`context_mode: "new"` starts a new conversation; `"off"` remains stateless.
Mock mode does not perform semantic context classification.
