glean-agent-toolkit 0.3.0__tar.gz → 0.4.0__tar.gz

{glean_agent_toolkit-0.3.0 → glean_agent_toolkit-0.4.0}/.cz.toml

@@ -1,6 +1,6 @@
 [tool.commitizen]
 name = "cz_conventional_commits"
-version = "0.3.0"
+version = "0.4.0"
 tag_format = "$version"
 version_files = [
   "pyproject.toml:version",

glean_agent_toolkit-0.4.0/.env.template

@@ -0,0 +1,6 @@
+# Glean API configuration
+GLEAN_SERVER_URL=https://your-company-be.glean.com
+GLEAN_API_TOKEN=
+
+# Deprecated: GLEAN_INSTANCE is legacy — still supported as fallback
+# GLEAN_INSTANCE=your-company

{glean_agent_toolkit-0.3.0 → glean_agent_toolkit-0.4.0}/.github/workflows/ci.yml

@@ -22,13 +22,13 @@ jobs:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Setup development environment
-        run: task setup
+        run: mise run setup
 
       - name: Run linters
-        run: task lint
+        run: mise run lint
 
       - name: Build package
-        run: task build
+        run: mise run build
 
   test:
     name: Test Python ${{ matrix.python-version }}
@@ -44,23 +44,21 @@ jobs:
         uses: jdx/mise-action@v2
         with:
           cache: true
-          mise_toml: |
-            [tools]
-            python = "${{ matrix.python-version }}"
-            task = "latest"
-            uv = "latest"
 
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Setup development environment
-        run: task setup
+        run: mise use -g python@${{ matrix.python-version }} uv@latest && mise install
+
+      - name: Initialize dev environment
+        run: mise run setup
 
       - name: Run tests
-        run: task test
+        run: mise run test
 
       - name: Test package installation
         run: |
-          task build
+          mise run build
           uv run pip install dist/*.whl
           uv run python -c "import glean.agent_toolkit; print('Package installed successfully')"

glean_agent_toolkit-0.4.0/AGENTS.md

@@ -0,0 +1,55 @@
+# Agent Guidelines
+
+This project contains the **Glean Agent Toolkit**, a Python package used to integrate Glean's search and discovery tools with various agent frameworks.
+
+## Setup
+
+1. Install the prerequisites:
+   - [uv](https://github.com/astral-sh/uv)
+   - [mise](https://mise.jdx.dev/)
+ 2. Run `mise run setup` to create the `.venv` and install all development, test, lint and typing dependencies via `uv`.
+
+Environment variables `GLEAN_API_TOKEN` and `GLEAN_SERVER_URL` (or deprecated `GLEAN_INSTANCE`) must be set to interact with Glean or regenerate VCR cassettes.
+
+## Development Tasks
+
+The repository uses **mise**. Key commands include:
+
+| Task | Description |
+|------|-------------|
+| `mise run test` | Run unit tests |
+| `mise run test:watch` | Run tests in watch mode |
+| `mise run test:cov` | Run tests with coverage |
+| `mise run test:all` | Run tests, apply lint fixes, and run pyright |
+| `mise run lint` | Run Ruff, formatting checks and pyright |
+| `mise run lint:diff` | Lint only changed files |
+| `mise run lint:fix` | Apply Ruff fixes and formatting |
+| `mise run format` | Format code using Ruff formatter |
+| `mise run spell:check` | Check spelling |
+| `mise run clean` | Remove build artifacts |
+| `mise run build` | Build the package |
+| `mise run release` | Bump version and generate the changelog |
+
+Special tasks exist to manage VCR cassettes used in tests:
+
+- `mise run test:vcr:regenerate` – Re-record all HTTP interactions (requires `GLEAN_API_TOKEN` and `GLEAN_SERVER_URL`; deprecated `GLEAN_INSTANCE` is still accepted as fallback).
+- `mise run test:vcr:clean` – Delete cassettes so the next test run regenerates them.
+
+## Coding Guidelines
+
+- Python **>=3.10** is required. The project enforces formatting with Ruff. Line length is limited to **100** characters and double quotes are used by default.
+- Docstrings follow the **Google** style as configured in `pyproject.toml`.
+- Type checking is performed with **pyright**.
+- Tools should be implemented using the `@tool_spec` decorator found in `glean.agent_toolkit.decorators`. See existing tools under `src/glean/agent_toolkit/tools` for examples.
+
+## Contribution Process
+
+1. Fork the repository and create a branch from `main`.
+2. Make your changes and ensure all tasks run cleanly (`mise run test` and `mise run lint`).
+3. Update or add documentation when necessary.
+4. Submit a pull request.
+5. Be respectful and follow the project's code of conduct.
+
+## Additional Notes
+
+Check the [README](README.md) for feature descriptions and basic usage. The package is released under the [MIT License](LICENSE).

{glean_agent_toolkit-0.3.0 → glean_agent_toolkit-0.4.0}/COMMIT_LINTING.md

@@ -25,7 +25,7 @@ Examples:
 
 ```bash
 # Install all dependencies including pre-commit
-task setup
+mise run setup
 ```
 
 This will:
@@ -37,7 +37,7 @@ This will:
 
 ```bash
 # Install pre-commit hooks
-task pre-commit:install
+mise run pre-commit:install
 ```
 
 ## Available Tools
@@ -54,13 +54,13 @@ Pre-commit hooks run automatically before each commit and will:
 
 ```bash
 # Run pre-commit hooks on all files
-task pre-commit:run
+mise run pre-commit:run
 
 # Run pre-commit hooks on changed files only
-task pre-commit:run:diff
+mise run pre-commit:run:diff
 
 # Update pre-commit hooks to latest versions
-task pre-commit:update
+mise run pre-commit:update
 ```
 
 ## Making Commits

glean_agent_toolkit-0.4.0/CONTRIBUTING.md

@@ -0,0 +1,94 @@
+# Contributing to Glean Agent Toolkit
+
+Thank you for your interest in contributing to the Glean Agent Toolkit! This guide will help you understand the project structure, development workflow, and how to add new tools.
+
+## Project Structure
+
+```sh
+src/
+├─ glean/
+│  ├─ __init__.py
+│  └─ agent_toolkit/     # exposes `glean.agent_toolkit`
+│     ├─ __init__.py
+│     ├─ decorators.py
+│     ├─ registry.py
+│     ├─ spec.py
+│     ├─ adapters/
+│     ├─ tools/
+│     └─ cli.py
+├─ tests/
+└─ docs/
+```
+
+## Development environment
+
+The repository relies on [uv](https://github.com/astral-sh/uv) and [mise](https://mise.jdx.dev/) for reproducible workflows and task orchestration.
+
+### Prerequisites
+
+1. uv
+
+   ```bash
+   pip install uv
+   ```
+
+2. mise
+
+   ```bash
+   brew install mise
+   ```
+
+### One-time setup
+
+```bash
+mise run setup
+```
+
+The command creates `.venv/` and installs all dev/test dependencies via uv.
+
+## Development Tasks
+
+The project uses `mise` to manage development tasks. Here are the available tasks:
+
+### Testing
+
+| Task                  | Description                  |
+| --------------------- | ---------------------------- |
+| `mise run test`       | Run unit tests               |
+| `mise run test:watch` | Run tests in watch mode      |
+| `mise run test:cov`   | Run tests with coverage      |
+| `mise run test:all`   | Run all tests and lint fixes |
+
+### Linting and formatting
+
+| Task                    | Description                             |
+| ----------------------- | --------------------------------------- |
+| `mise run lint`         | Run Ruff, pyright and formatting checks |
+| `mise run lint:diff`    | Same as above but only on changed files |
+| `mise run lint:package` | Lint only `glean/toolkit`               |
+| `mise run lint:tests`   | Lint only `tests`                       |
+| `mise run lint:fix`     | Autofix style issues                    |
+| `mise run format`       | Apply Ruff formatter                    |
+| `mise run format:diff`  | Format only changed files               |
+
+### Examples and Utilities
+
+| Task                   | Description                                     |
+| ---------------------- | ----------------------------------------------- |
+| `mise run spell:check` | Check spelling                                  |
+| `mise run spell:fix`   | Fix spelling                                    |
+| `mise run clean`       | Clean build artifacts                           |
+| `mise run build`       | Build the package                               |
+| `mise run release`     | Create a new release (version bump + changelog) |
+| `mise run security:audit` | Run dependency vulnerability audit (pip-audit) |
+
+## Pull Request Process
+
+1. Fork the repository and create your branch from `main`.
+2. Make your changes and ensure that all tests pass.
+3. Update the documentation to reflect any changes.
+4. Submit a pull request.
+
+## Code of Conduct
+
+Please be respectful and considerate of others when contributing to this project.

{glean_agent_toolkit-0.3.0 → glean_agent_toolkit-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: glean-agent-toolkit
-Version: 0.3.0
+Version: 0.4.0
 Summary: AI Agent toolkit for adapting Glean's enterprise tools across multiple frameworks
 Project-URL: Source Code, https://github.com/gleanwork/glean-agent-toolkit
 Author-email: Steve Calvert <steve.calvert@glean.com>
@@ -47,9 +47,36 @@ The Glean Agent Toolkit makes it easy to integrate Glean's powerful search and k
 
 ## Key Features
 
-* **Production-Ready Glean Tools:** Instantly add capabilities like enterprise search, employee lookup, calendar search, Gmail search, and more to your agents.
-* **Framework Adapters:** Seamlessly convert Glean tools into formats compatible with major agent SDKs.
-* **Custom Tool Creation:** Define your own tools once using the `@tool_spec` decorator and use them across any supported framework.
+- **Production-Ready Glean Tools:** Instantly add capabilities like enterprise search, employee lookup, calendar search, Gmail search, and more to your agents.
+- **Framework Adapters:** Seamlessly convert Glean tools into formats compatible with major agent SDKs.
+- **Custom Tool Creation:** Define your own tools once using the `@tool_spec` decorator and use them across any supported framework.
+
+## Compatibility & Reliability
+
+- Requires Python 3.10+
+- Built-in retries are enabled via the Python client’s `RetryConfig`.
+- See `docs/prerequisites.md` for server-level configuration and connector requirements.
+
+### Retry configuration (env vars)
+
+| Variable                    | Default | Description                    | Example |
+| --------------------------- | ------- | ------------------------------ | ------- |
+| `GLEAN_RETRY_INITIAL`       | `1.0`   | Initial backoff in seconds     | `0.5`   |
+| `GLEAN_RETRY_MAX`           | `50.0`  | Maximum backoff in seconds     | `8`     |
+| `GLEAN_RETRY_MULTIPLIER`    | `1.1`   | Exponential backoff multiplier | `2.0`   |
+| `GLEAN_RETRY_JITTER_MS`     | `100`   | Random jitter in milliseconds  | `250`   |
+| `GLEAN_RETRY_ON_RATE_LIMIT` | `true`  | Retry on HTTP 429 rate limits  | `true`  |
+
+Retries cover transient failures such as HTTP 429/5xx and connection timeouts. Set these before constructing any Glean client usage.
+
+```bash
+# Example: low-latency, bounded retries
+export GLEAN_RETRY_INITIAL=0.5
+export GLEAN_RETRY_MAX=8
+export GLEAN_RETRY_MULTIPLIER=2.0
+export GLEAN_RETRY_JITTER_MS=250
+export GLEAN_RETRY_ON_RATE_LIMIT=true
+```
 
 ## Installation
 
@@ -85,9 +112,11 @@ Before using any Glean tools, you'll need:
 
    ```bash
    export GLEAN_API_TOKEN="your-api-token"
-   export GLEAN_INSTANCE="your-instance-name"
+   export GLEAN_SERVER_URL="https://your-company-be.glean.com"
    ```
 
+See `docs/prerequisites.md` for instance-level connector and Admin settings required per tool.
+
 ## Quickstart Example: Company Assistant with Google ADK
 
 Here's a complete example that demonstrates the power of the Glean Agent Toolkit. We'll build a "Company Assistant" using Google's Agent Development Kit (ADK) that can help employees find information, discover colleagues, and search company resources.
@@ -98,7 +127,7 @@ First, create the project structure:
 
 ```bash snippet=readme/snippet-04.bash
 export GLEAN_API_TOKEN="your-api-token"
-export GLEAN_INSTANCE="your-instance-name"
+export GLEAN_SERVER_URL="https://your-company-be.glean.com"
 ```
 
 ### Step 2: Create the Agent File
@@ -110,10 +139,10 @@ import os
 
 from google.adk.agents import Agent
 
-from glean.agent_toolkit.tools import calendar_search, employee_search, glean_search, gmail_search
+from glean.agent_toolkit.tools import calendar_search, employee_search, gmail_search, search
 
 # Ensure environment variables are set
-required_env_vars = ["GLEAN_API_TOKEN", "GLEAN_INSTANCE"]
+required_env_vars = ["GLEAN_API_TOKEN", "GLEAN_SERVER_URL"]
 for var in required_env_vars:
     if not os.getenv(var):
         raise ValueError(f"{var} environment variable must be set")
@@ -124,7 +153,7 @@ if not os.getenv("GOOGLE_API_KEY") and not os.getenv("GOOGLE_CLOUD_PROJECT"):
     raise ValueError("Either GOOGLE_API_KEY or GOOGLE_CLOUD_PROJECT must be set for ADK")
 
 # Convert Glean tools to Google ADK format
-company_search = glean_search.as_adk_tool()
+company_search = search.as_adk_tool()
 people_finder = employee_search.as_adk_tool()
 meeting_search = calendar_search.as_adk_tool()
 email_search = gmail_search.as_adk_tool()
@@ -138,7 +167,7 @@ root_agent = Agent(
     instruction="""You are a helpful company assistant that helps employees find information,
     people, and resources within the organization. You have access to:
 
-    - Company knowledge base and documents (use glean_search)
+    - Company knowledge base and documents (use search)
     - Employee directory and contact information (use employee_search)
     - Calendar and meeting information (use calendar_search)
     - Email search capabilities (use gmail_search)
@@ -163,7 +192,7 @@ Create `company_assistant/.env` with your credentials:
 
 ```bash snippet=readme/snippet-05.bash
 export GLEAN_API_TOKEN="your-api-token"
-export GLEAN_INSTANCE="your-instance-name"
+export GLEAN_SERVER_URL="https://your-company-be.glean.com"
 ```
 
 ### Step 5: Run Your Agent
@@ -179,12 +208,12 @@ cd company_assistant/
 
 Once set up, your Company Assistant can handle requests like:
 
-- *"Find our security guidelines for handling customer data"*
-- *"Who's the product manager for the mobile app team?"*
-- *"Show me emails about the budget planning meeting from last week"*
-- *"I need the engineering team's architecture docs for the payment system"*
-- *"Find all the design review meetings scheduled for this month"*
-- *"Who worked on the API authentication project? I need to ask them some questions"*
+- _"Find our security guidelines for handling customer data"_
+- _"Who's the product manager for the mobile app team?"_
+- _"Show me emails about the budget planning meeting from last week"_
+- _"I need the engineering team's architecture docs for the payment system"_
+- _"Find all the design review meetings scheduled for this month"_
+- _"Who worked on the API authentication project? I need to ask them some questions"_
 
 This type of assistant can dramatically improve employee productivity by making company knowledge instantly accessible through natural conversation.
 
@@ -192,18 +221,33 @@ This type of assistant can dramatically improve employee productivity by making
 
 The toolkit comes with a suite of production-ready tools that connect to various Glean functionalities:
 
-* **`glean_search`**: Search your company's knowledge base for relevant documents and information
-* **`web_search`**: Search the public web for up-to-date external information
-* **`ai_web_search`**: Query Google Gemini for AI-powered web information
-* **`calendar_search`**: Find meetings and calendar events
-* **`employee_search`**: Search for employees by name, team, department, or expertise
-* **`code_search`**: Search your company's source code repositories
-* **`gmail_search`**: Search Gmail messages and conversations
-* **`outlook_search`**: Search Outlook mail and calendar items
+- `search`: Search your company's knowledge base for relevant documents and information
+- **`read_document`**: Read full content of a specific document by ID or URL (requires
+  config settings `queryapi.getDocuments.enabled` and `queryapi.getDocuments.content.enabled`)
+- **`web_search`**: Search the public web for up-to-date external information
+- `calendar_search`: Find meetings and calendar events
+- `employee_search`: Search for employees by name, team, department, or expertise
+- `code_search`: Search your company's source code repositories
+- `gmail_search`: Search Gmail messages and conversations
+- `outlook_search`: Search Outlook mail and calendar items
+
+### Web Research with Context
+
+```python snippet=readme/snippet-09.py
+from glean.agent_toolkit.tools import web_search
+
+# External information gathering
+web_tool = web_search.as_langchain_tool()
+
+# Example queries:
+# "Latest industry trends in machine learning"
+# "Current market analysis for SaaS companies"
+# "Recent news about our competitors"
+```
 
 ## Quick Start Examples
 
-### Using `glean_search` with Different Frameworks
+### Using `search` with Different Frameworks
 
 #### OpenAI Agents SDK
 
@@ -212,11 +256,11 @@ import os
 
 from agents import Agent, Runner
 
-from glean.agent_toolkit.tools import glean_search
+from glean.agent_toolkit.tools import search
 
 # Ensure environment variables are set
 assert os.getenv("GLEAN_API_TOKEN"), "GLEAN_API_TOKEN must be set"
-assert os.getenv("GLEAN_INSTANCE"), "GLEAN_INSTANCE must be set"
+assert os.getenv("GLEAN_SERVER_URL"), "GLEAN_SERVER_URL must be set"
 assert os.getenv("OPENAI_API_KEY"), "OPENAI_API_KEY must be set"
 
 # Create an agent with the Glean search tool
@@ -224,7 +268,7 @@ agent = Agent(
     name="KnowledgeAssistant",
     instructions="""You help users find information from the company knowledge base using
     Glean search.""",
-    tools=[glean_search],  # Use the tool function directly
+    tools=[search],  # Use the tool function directly
 )
 
 # Run a search query
@@ -241,20 +285,20 @@ from langchain.agents import AgentExecutor, create_react_agent
 from langchain_core.prompts import ChatPromptTemplate
 from langchain_openai import ChatOpenAI
 
-from glean.agent_toolkit.tools import glean_search
+from glean.agent_toolkit.tools import search
 
 # Ensure environment variables are set
 assert os.getenv("GLEAN_API_TOKEN"), "GLEAN_API_TOKEN must be set"
-assert os.getenv("GLEAN_INSTANCE"), "GLEAN_INSTANCE must be set"
+assert os.getenv("GLEAN_SERVER_URL"), "GLEAN_SERVER_URL must be set"
 
 # Convert to LangChain tool format
-langchain_tool = glean_search.as_langchain_tool()
+langchain_tool = search.as_langchain_tool()
 
 llm = ChatOpenAI(model="gpt-4", temperature=0)
 tools = [langchain_tool]
 
 prompt_template = """You are a helpful assistant with access to company knowledge.
-Use the glean_search tool to find relevant information when users ask questions.
+Use the search tool to find relevant information when users ask questions.
 
 Tools available:
 {tools}
@@ -287,14 +331,14 @@ import os
 
 from crewai import Agent, Crew, Task
 
-from glean.agent_toolkit.tools import glean_search
+from glean.agent_toolkit.tools import search
 
 # Ensure environment variables are set
 assert os.getenv("GLEAN_API_TOKEN"), "GLEAN_API_TOKEN must be set"
-assert os.getenv("GLEAN_INSTANCE"), "GLEAN_INSTANCE must be set"
+assert os.getenv("GLEAN_SERVER_URL"), "GLEAN_SERVER_URL must be set"
 
 # Convert to CrewAI tool format
-crewai_tool = glean_search.as_crewai_tool()
+crewai_tool = search.as_crewai_tool()
 
 # Create a research agent
 researcher = Agent(
@@ -366,21 +410,6 @@ calendar_tool = calendar_search.as_langchain_tool()
 # "Search for messages containing budget discussions"
 ```
 
-#### Web Research with Context
-
-```python snippet=readme/snippet-09.py
-from glean.agent_toolkit.tools import ai_web_search, web_search
-
-# External information gathering
-web_tool = web_search.as_langchain_tool()
-ai_web_tool = ai_web_search.as_langchain_tool()
-
-# Example queries:
-# "Latest industry trends in machine learning"
-# "Current market analysis for SaaS companies"
-# "Recent news about our competitors"
-```
-
 ## Creating Custom Tools with `@tool_spec`
 
 Define your own tools that work across all supported frameworks:
@@ -432,4 +461,4 @@ Interested in contributing? Check out our [Contributing Guide](CONTRIBUTING.md)
 
 ## License
 
-This project is licensed under the [MIT License](LICENSE). 
+This project is licensed under the [MIT License](LICENSE).