Metadata-Version: 2.4
Name: google-adk-firestore-session
Version: 0.1.3
Summary: Firestore Session Manager for Google ADK
Project-URL: Homepage, https://github.com/mohammadshamma/google-adk-firestore-session
Project-URL: Repository, https://github.com/mohammadshamma/google-adk-firestore-session
Project-URL: Issues, https://github.com/mohammadshamma/google-adk-firestore-session/issues
Author-email: Mohammad Shamma <mshamma@gmail.com>
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.11
Requires-Dist: google-adk
Requires-Dist: google-cloud-firestore
Description-Content-Type: text/markdown

[![Python Tests](https://github.com/mohammadshamma/google-adk-firestore-session/actions/workflows/python-tests.yml/badge.svg)](https://github.com/mohammadshamma/google-adk-firestore-session/actions/workflows/python-tests.yml)
[![Python 3.11+](https://img.shields.io/python/required-version-toml?tomlFilePath=https%3A%2F%2Fraw.githubusercontent.com%2Fmohammadshamma%2Fgoogle-adk-firestore-session%2Fmain%2Fpyproject.toml)](https://pypi.org/project/google-adk-firestore-session/)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)

# Google ADK Firestore Session

A specialized implementation of the `BaseSessionService` that uses Google Cloud Firestore for persisting application sessions, user states, and event logs.

## Overview

This package provides the `FirestoreSessionService` class, which handles the lifecycle of sessions within the Google ADK (Agent Development Kit) framework. It organizes data in a hierarchical Firestore structure:

- `apps/{app_name}`: Global application state.
- `apps/{app_name}/users/{user_id}`: Persistent user-specific state.
- `apps/{app_name}/users/{user_id}/sessions/{session_id}`: Individual session data and state.
- `apps/{app_name}/users/{user_id}/sessions/{session_id}/events/{event_id}`: Historical event logs for the session.

## Installation

You can include this package in your project's dependencies using the Git URL.

### Using `pip`
```bash
pip install git+https://github.com/mohammadshamma/google-adk-firestore-session.git
```

### Using `uv` (pyproject.toml)
```toml
dependencies = [
    "google-adk-firestore-session @ git+https://github.com/mohammadshamma/google-adk-firestore-session.git"
]
```

## Configuration

The `FirestoreSessionService` can be configured via constructor arguments, environment variables, or through the built-in ADK factory.

### Precedence
1. **Constructor Arguments**: Explicit `project` and `database` passed to the class.
2. **Environment Variables**: `GOOGLE_CLOUD_PROJECT` and `GOOGLE_DATABASE`.
3. **Default Credentials**: Standard Google Cloud application default credentials.

## Usage with Google ADK

To use the `FirestoreSessionService` with Google ADK, register the provided factory with the ADK `ServiceRegistry`. This allows you to point your agents to Firestore using a simple URI.

### 1. Register the Service

In your main entry point (e.g., `serving.py`), import and register the factory.

```python
from google.adk.cli.service_registry import get_service_registry
from firestore_session import firestore_session_service_factory

# Register the "firestore" scheme
get_service_registry().register_session_service(
    "firestore", 
    firestore_session_service_factory
)
```

### 2. Configure the ADK App

Pass the URI to `get_fast_api_app`. The URI format is `firestore://[project-id]/[database-name]`.

```python
from google.adk.cli.fast_api import get_fast_api_app

app = get_fast_api_app(
    agents_dir="path/to/agents",
    # Connect to a specific project and database instance
    session_service_uri="firestore://my-project-id/my-database", 
    web=True
)
```

## Standalone Usage

```python
from firestore_session import FirestoreSessionService

# Explicitly passing project/database
session_service = FirestoreSessionService(
    project="my-project-id",
    database="my-database"
)

# Or use environment variables (GOOGLE_CLOUD_PROJECT, etc.)
session_service = FirestoreSessionService()
```

## Dependencies

- `google-adk`: Core agent framework.
- `google-cloud-firestore`: Official Firestore client.

## Development

### Running Tests
Tests use `pytest`. Ensure you have a Firestore emulator or a project configured for testing.

```bash
pytest tests/
```
