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

glean_agent_toolkit-0.3.0/.cz.toml

@@ -0,0 +1,8 @@
+[tool.commitizen]
+name = "cz_conventional_commits"
+version = "0.3.0"
+tag_format = "$version"
+version_files = [
+  "pyproject.toml:version",
+  "glean/toolkit/__init__.py:__version__",
+]

{glean_agent_toolkit-0.2.0 → glean_agent_toolkit-0.3.0}/.github/workflows/publish.yml

@@ -3,7 +3,7 @@ name: Publish to PyPI
 on:
   push:
     tags:
-      - 'v*.*.*'
+      - '*.*.*'
   workflow_dispatch:
 
 jobs:

glean_agent_toolkit-0.3.0/.markdown-coderc.json

@@ -0,0 +1,14 @@
+{
+  "snippetRoot": "./snippets",
+  "markdownGlob": "README.md",
+  "excludeGlob": [
+    "node_modules/**",
+    ".git/**",
+    "dist/**",
+    "build/**",
+    "coverage/**",
+    "target/**",
+    "vendor/**"
+  ],
+  "includeExtensions": [".py", ".bash", ".sh"]
+}

glean_agent_toolkit-0.3.0/.pre-commit-config.yaml

@@ -0,0 +1,23 @@
+repos:
+  - repo: https://github.com/commitizen-tools/commitizen
+    rev: v4.4.1
+    hooks:
+      - id: commitizen
+        stages: [commit-msg]
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.5.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-added-large-files
+      - id: check-merge-conflict
+      - id: debug-statements
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.5.0
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format

glean_agent_toolkit-0.3.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)
+   - [go-task](https://taskfile.dev/)
+2. Run `task setup` to create the `.venv` and install all development, test, lint and typing dependencies via `uv`.
+
+Environment variables `GLEAN_API_TOKEN` and `GLEAN_INSTANCE` must be set to interact with Glean or regenerate VCR cassettes.
+
+## Development Tasks
+
+The repository uses **go-task**. Key commands from `Taskfile.yml` include:
+
+| Task | Description |
+|------|-------------|
+| `task test` | Run unit tests |
+| `task test:watch` | Run tests in watch mode |
+| `task test:cov` | Run tests with coverage |
+| `task test:all` | Run tests, apply lint fixes, and run pyright |
+| `task lint` | Run Ruff, formatting checks and pyright |
+| `task lint:diff` | Lint only changed files |
+| `task lint:fix` | Apply Ruff fixes and formatting |
+| `task format` | Format code using Ruff formatter |
+| `task spell:check` | Check spelling |
+| `task clean` | Remove build artifacts |
+| `task build` | Build the package |
+| `task release` | Bump version and generate the changelog |
+
+Special tasks exist to manage VCR cassettes used in tests:
+
+- `task test:vcr:regenerate` – Re-record all HTTP interactions (requires `GLEAN_API_TOKEN` and `GLEAN_INSTANCE`).
+- `task 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 (`task test` and `task 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/CHANGELOG.md

@@ -0,0 +1,16 @@
+## 0.3.0 (2025-07-21)
+
+### Feat
+
+- Add enhanced parameter schemas with Field metadata support
+
+### Fix
+
+- Adds newline to .cz.toml
+- Fixes type errors during task:lint
+
+## 0.2.0 (2025-06-05)
+
+### Feat
+
+- Implements Agent Builder tools as defaults

glean_agent_toolkit-0.3.0/COMMIT_LINTING.md

@@ -0,0 +1,166 @@
+# Commit Linting Setup
+
+This project uses conventional commits with pre-commit hooks to ensure all commits follow the proper format.
+
+## What is Conventional Commits?
+
+Conventional Commits is a specification for commit messages that provides a standardized way to write commit messages. This makes it easier to:
+
+- Automatically generate changelogs
+- Determine semantic version bumps
+- Communicate the nature of changes to teammates
+
+Format: `<type>(<scope>): <description>`
+
+Examples:
+
+- `feat: add new search functionality`
+- `fix(auth): resolve login issue`
+- `docs: update README with new examples`
+- `refactor(api): simplify response handling`
+
+## Setup
+
+### 1. Install Dependencies
+
+```bash
+# Install all dependencies including pre-commit
+task setup
+```
+
+This will:
+
+- Install Python dependencies with `uv`
+- Install pre-commit hooks automatically
+
+### 2. Manual Pre-commit Setup (if needed)
+
+```bash
+# Install pre-commit hooks
+task pre-commit:install
+```
+
+## Available Tools
+
+### Pre-commit Hooks
+
+Pre-commit hooks run automatically before each commit and will:
+
+- Validate commit message format using Commitizen
+- Run code formatting and linting with Ruff
+- Check for common issues (trailing whitespace, merge conflicts, etc.)
+
+**Commands:**
+
+```bash
+# Run pre-commit hooks on all files
+task pre-commit:run
+
+# Run pre-commit hooks on changed files only
+task pre-commit:run:diff
+
+# Update pre-commit hooks to latest versions
+task pre-commit:update
+```
+
+## Making Commits
+
+### Option 1: Use Commitizen (Recommended)
+
+```bash
+# Interactive commit creation
+uv run python -m commitizen commit
+
+# Or use the shorthand
+uv run cz commit
+```
+
+This will guide you through creating a conventional commit interactively.
+
+### Option 2: Manual Commits
+
+You can write commits manually, but they must follow the conventional commit format:
+
+```bash
+git commit -m "feat: add new feature"
+git commit -m "fix(auth): resolve login issue"
+git commit -m "docs: update API documentation"
+```
+
+### Option 3: Use Pre-commit with Conventional Commits
+
+```bash
+# Write your commit message
+git add .
+git commit -m "your message here"
+
+# Pre-commit will validate and potentially fix issues
+```
+
+**Note:** Pre-commit hooks will automatically run and validate your commit message format.
+
+## Commit Types
+
+- `feat`: A new feature
+- `fix`: A bug fix
+- `docs`: Documentation only changes
+- `style`: Changes that do not affect the meaning of the code
+- `refactor`: A code change that neither fixes a bug nor adds a feature
+- `perf`: A code change that improves performance
+- `test`: Adding missing tests or correcting existing tests
+- `build`: Changes that affect the build system or external dependencies
+- `ci`: Changes to CI configuration files and scripts
+- `chore`: Other changes that don't modify src or test files
+- `revert`: Reverts a previous commit
+
+## Troubleshooting
+
+### Pre-commit Hook Not Running
+
+```bash
+# Reinstall pre-commit hooks
+task pre-commit:install
+```
+
+### Commit Message Validation Failing
+
+1. Use Commitizen for interactive commit creation:
+
+   ```bash
+   uv run python -m commitizen commit
+   ```
+
+2. Check the conventional commit format:
+
+   - Must start with a type: `feat`, `fix`, `docs`, etc.
+   - Optional scope in parentheses: `(auth)`, `(api)`, etc.
+   - Colon and space: `: `
+   - Description: `add new feature`
+
+3. Examples of valid commits:
+   ```bash
+   git commit -m "feat: add new search functionality"
+   git commit -m "fix(auth): resolve login timeout issue"
+   git commit -m "docs: update installation instructions"
+   ```
+
+### Skipping Validation (Emergency Only)
+
+```bash
+# Skip pre-commit hooks (not recommended)
+git commit -m "your message" --no-verify
+```
+
+## Configuration Files
+
+- `.pre-commit-config.yaml`: Pre-commit hooks configuration
+- `.cz.toml`: Commitizen configuration
+- `pyproject.toml`: Project dependencies including pre-commit
+
+## Benefits
+
+1. **Consistent History**: All commits follow the same format
+2. **Automated Changelogs**: Commitizen can generate changelogs automatically
+3. **Semantic Versioning**: Automatic version bumping based on commit types
+4. **Better Collaboration**: Clear communication about what each commit does
+5. **Local Validation**: Immediate feedback before commits are made

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: glean-agent-toolkit
-Version: 0.2.0
+Version: 0.3.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>
@@ -10,7 +10,7 @@ Requires-Python: <4.0,>=3.10
 Requires-Dist: glean-api-client<1.0,>=0.6.0
 Requires-Dist: pydantic<3.0,>=2.7
 Provides-Extra: adk
-Requires-Dist: google-adk<1.0,>=0.1.0; extra == 'adk'
+Requires-Dist: google-adk<2.0,>=1.7.0; extra == 'adk'
 Provides-Extra: codespell
 Requires-Dist: codespell<3.0,>=2.2.6; extra == 'codespell'
 Provides-Extra: crewai
@@ -18,6 +18,7 @@ Requires-Dist: crewai<1.0,>=0.28.0; extra == 'crewai'
 Provides-Extra: dev
 Requires-Dist: commitizen<5.0,>=4.4.1; extra == 'dev'
 Requires-Dist: pip-audit<3.0,>=2.6.0; extra == 'dev'
+Requires-Dist: pre-commit<4.0,>=3.6.0; extra == 'dev'
 Requires-Dist: vcrpy<7.0,>=6.0.2; extra == 'dev'
 Provides-Extra: langchain
 Requires-Dist: langchain<1.0,>=0.1.0; extra == 'langchain'
@@ -28,7 +29,7 @@ Requires-Dist: openai-agents<1.0,>=0.0.11; extra == 'openai'
 Requires-Dist: openai<2.0,>=1.0.0; extra == 'openai'
 Provides-Extra: test
 Requires-Dist: crewai<1.0,>=0.28.0; extra == 'test'
-Requires-Dist: google-adk<1.0,>=0.1.0; extra == 'test'
+Requires-Dist: google-adk<2.0,>=1.7.0; extra == 'test'
 Requires-Dist: langchain<1.0,>=0.1.0; extra == 'test'
 Requires-Dist: openai-agents<1.0,>=0.0.11; extra == 'test'
 Requires-Dist: openai<2.0,>=1.0.0; extra == 'test'
@@ -54,13 +55,13 @@ The Glean Agent Toolkit makes it easy to integrate Glean's powerful search and k
 
 Install the base toolkit:
 
-```bash
+```bash snippet=readme/snippet-01.bash
 pip install glean-agent-toolkit
 ```
 
 To include support for specific agent frameworks, install the relevant extras:
 
-```bash
+```bash snippet=readme/snippet-02.bash
 pip install glean-agent-toolkit[openai]
 pip install glean-agent-toolkit[adk]
 pip install glean-agent-toolkit[langchain]
@@ -69,7 +70,7 @@ pip install glean-agent-toolkit[crewai]
 
 You can also install all extras:
 
-```bash
+```bash snippet=readme/snippet-03.bash
 pip install glean-agent-toolkit[all]
 ```
 
@@ -81,11 +82,112 @@ Before using any Glean tools, you'll need:
 
 1. **Glean API credentials**: Obtain these from your Glean administrator
 2. **Environment variables**:
+
    ```bash
    export GLEAN_API_TOKEN="your-api-token"
    export GLEAN_INSTANCE="your-instance-name"
    ```
 
+## 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.
+
+### Step 1: Create Project Directory
+
+First, create the project structure:
+
+```bash snippet=readme/snippet-04.bash
+export GLEAN_API_TOKEN="your-api-token"
+export GLEAN_INSTANCE="your-instance-name"
+```
+
+### Step 2: Create the Agent File
+
+Create `company_assistant/agent.py` with your agent definition:
+
+```python snippet=readme/snippet-01.py
+import os
+
+from google.adk.agents import Agent
+
+from glean.agent_toolkit.tools import calendar_search, employee_search, glean_search, gmail_search
+
+# Ensure environment variables are set
+required_env_vars = ["GLEAN_API_TOKEN", "GLEAN_INSTANCE"]
+for var in required_env_vars:
+    if not os.getenv(var):
+        raise ValueError(f"{var} environment variable must be set")
+
+# For Google ADK, you also need authentication
+# Either set GOOGLE_API_KEY for Google AI Studio, or use gcloud auth for Vertex AI
+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()
+people_finder = employee_search.as_adk_tool()
+meeting_search = calendar_search.as_adk_tool()
+email_search = gmail_search.as_adk_tool()
+
+# Create a Company Assistant agent
+root_agent = Agent(
+    name="company_assistant",
+    model="gemini-2.0-flash",
+    description="""Company Assistant that helps employees find information, people, and resources
+    within the organization.""",
+    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)
+    - Employee directory and contact information (use employee_search)
+    - Calendar and meeting information (use calendar_search)
+    - Email search capabilities (use gmail_search)
+
+    Always be helpful, professional, and respect privacy. When searching for people,
+    only share appropriate business contact information.""",
+    tools=[company_search, people_finder, meeting_search, email_search],
+)
+```
+
+### Step 3: Create Package Init File
+
+Create `company_assistant/__init__.py` to import your agent:
+
+```python snippet=readme/snippet-02.py
+from . import agent
+```
+
+### Step 4: Configure Environment Variables
+
+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"
+```
+
+### Step 5: Run Your Agent
+
+From the parent directory (outside `company_assistant/`), run your Company Assistant:
+
+```bash snippet=readme/snippet-06.bash
+mkdir company_assistant/
+cd company_assistant/
+```
+
+### Real-World Queries You Can Handle
+
+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"*
+
+This type of assistant can dramatically improve employee productivity by making company knowledge instantly accessible through natural conversation.
+
 ## Available Tools
 
 The toolkit comes with a suite of production-ready tools that connect to various Glean functionalities:
@@ -105,11 +207,13 @@ The toolkit comes with a suite of production-ready tools that connect to various
 
 #### OpenAI Agents SDK
 
-```python
+```python snippet=readme/snippet-03.py
 import os
-from glean.agent_toolkit.tools import glean_search
+
 from agents import Agent, Runner
 
+from glean.agent_toolkit.tools import glean_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"
@@ -118,8 +222,9 @@ assert os.getenv("OPENAI_API_KEY"), "OPENAI_API_KEY must be set"
 # Create an agent with the Glean search tool
 agent = Agent(
     name="KnowledgeAssistant",
-    instructions="You help users find information from the company knowledge base using Glean search.",
-    tools=[glean_search.func]  # Use the underlying function
+    instructions="""You help users find information from the company knowledge base using
+    Glean search.""",
+    tools=[glean_search],  # Use the tool function directly
 )
 
 # Run a search query
@@ -129,12 +234,14 @@ print(f"Search results: {result.final_output}")
 
 #### LangChain
 
-```python
+```python snippet=readme/snippet-04.py
 import os
-from glean.agent_toolkit.tools import glean_search
-from langchain_openai import ChatOpenAI
+
 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
 
 # Ensure environment variables are set
 assert os.getenv("GLEAN_API_TOKEN"), "GLEAN_API_TOKEN must be set"
@@ -175,10 +282,12 @@ print(result["output"])
 
 #### CrewAI
 
-```python
+```python snippet=readme/snippet-05.py
 import os
+
+from crewai import Agent, Crew, Task
+
 from glean.agent_toolkit.tools import glean_search
-from crewai import Agent, Task, Crew
 
 # Ensure environment variables are set
 assert os.getenv("GLEAN_API_TOKEN"), "GLEAN_API_TOKEN must be set"
@@ -191,16 +300,19 @@ crewai_tool = glean_search.as_crewai_tool()
 researcher = Agent(
     role="Corporate Knowledge Researcher",
     goal="Find and summarize relevant company information",
-    backstory="You are an expert at navigating company knowledge bases to find accurate, up-to-date information.",
+    backstory="""You are an expert at navigating company knowledge bases to find accurate,
+    up-to-date information.""",
     tools=[crewai_tool],
-    verbose=True
+    verbose=True,
 )
 
 # Create a research task
 research_task = Task(
-    description="Find information about our company's remote work policy and summarize the key points.",
-    expected_output="A clear summary of the remote work policy including eligibility, expectations, and guidelines.",
-    agent=researcher
+    description="""Find information about our company's remote work policy and summarize the key
+    points.""",
+    expected_output="""A clear summary of the remote work policy including eligibility,
+    expectations, and guidelines.""",
+    agent=researcher,
 )
 
 # Execute the research
@@ -213,7 +325,7 @@ print(result)
 
 #### Employee Directory Search
 
-```python
+```python snippet=readme/snippet-06.py
 from glean.agent_toolkit.tools import employee_search
 
 # Find engineering team members
@@ -227,7 +339,7 @@ engineering_team = employee_search.as_langchain_tool()
 
 #### Code Discovery
 
-```python
+```python snippet=readme/snippet-07.py
 from glean.agent_toolkit.tools import code_search
 
 # Search company codebases
@@ -241,8 +353,8 @@ code_tool = code_search.as_langchain_tool()
 
 #### Email and Calendar Integration
 
-```python
-from glean.agent_toolkit.tools import gmail_search, calendar_search
+```python snippet=readme/snippet-08.py
+from glean.agent_toolkit.tools import calendar_search, gmail_search
 
 # Search emails and meetings
 gmail_tool = gmail_search.as_langchain_tool()
@@ -256,8 +368,8 @@ calendar_tool = calendar_search.as_langchain_tool()
 
 #### Web Research with Context
 
-```python
-from glean.agent_toolkit.tools import web_search, ai_web_search
+```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()
@@ -273,10 +385,14 @@ ai_web_tool = ai_web_search.as_langchain_tool()
 
 Define your own tools that work across all supported frameworks:
 
-```python
-from glean.agent_toolkit import tool_spec
-from pydantic import BaseModel
+```python snippet=readme/snippet-10.py
+import os
+
 import requests
+from pydantic import BaseModel
+
+from glean.agent_toolkit import tool_spec
+
 
 class WeatherResponse(BaseModel):
     temperature: float
@@ -284,10 +400,11 @@ class WeatherResponse(BaseModel):
     humidity: int
     city: str
 
+
 @tool_spec(
     name="get_current_weather",
     description="Get current weather information for a specified city",
-    output_model=WeatherResponse
+    output_model=WeatherResponse,
 )
 def get_weather(city: str, units: str = "celsius") -> WeatherResponse:
     """Fetch current weather for a city."""
@@ -297,14 +414,12 @@ def get_weather(city: str, units: str = "celsius") -> WeatherResponse:
         f"https://api.weather.com/v1/current?key={api_key}&q={city}&units={units}"
     )
     data = response.json()
-    
+
     return WeatherResponse(
-        temperature=data["temp"],
-        condition=data["condition"],
-        humidity=data["humidity"],
-        city=city
+        temperature=data["temp"], condition=data["condition"], humidity=data["humidity"], city=city
     )
 
+
 # Use across frameworks
 openai_weather = get_weather.as_openai_tool()
 langchain_weather = get_weather.as_langchain_tool()