Skip to content
2 changes: 2 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,7 @@ This section might supplement the Changelog file from the repository and only hi
| [health news agent](/examples/agents/health_news_agent/) | A no-code agent specialized in health and medical news, with access to a news collection and search tools. |
| [image render agent](/examples/agents/image_render_agent/) | An agent that demonstrates how to render tool-generated images in the RAM chat using base64-encoded image output. |
| [mcp tool agent](/examples/agents/mcp_tool_agent/) | A code agent template that discovers and directly invokes MCP tools by name from user prompts, bypassing LLM-driven tool selection. |
| [metadata filtering](/examples/agents/metadata_tag_filtering_agent/) | Examples showing how to narrow retrieval using custom metadata, either through explicit filters or Agentic Retrieval. |
| [multiple llms agent](/examples/agents/multiple_llms_agent/) | An agent that routes prompts between low- and high-reasoning LLM aliases to show dynamic multi-model selection in a single agent template. |
| [news information finder](/examples/agents/news_information_finder/) | A general-purpose news search agent with access to all news collections and web search tools. |
| [science and tech news agent](/examples/agents/science_tech_news_agent/) | A no-code agent specialized in science and technology news, with access to a news collection and search tools. |
Expand Down Expand Up @@ -75,6 +76,7 @@ This section might supplement the Changelog file from the repository and only hi

| Example | Description |
| ------ | ------ |
| [file tags](/examples/custom_sources/file_tags/) | A custom source example that generates three IT support documents and tags them by source filename, including multiple tags on one file. |
| [financial news fetcher](/examples/custom_sources/financial_news_fetcher/) | A custom source example that fetches technology-sector financial news, generates a PDF digest, and saves the PDF into a RAM source for downstream collection ingestion. |
| [news source](/examples/custom_sources/news_source/) | A parameterized news source that fetches from NYT, Reddit, and Yahoo Finance for a configurable news domain. |
| [NYT front page source](/examples/custom_sources/nyt_front_page_source/) | A custom soure example that fetches the daily headlines from all 26 NYT Top Stories sections. |
Expand Down
44 changes: 44 additions & 0 deletions examples/agents/metadata_filtering_agent/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
# Metadata Filtering Agent

The following examples demonstrate how SAS Retrieval Agent Manager (RAM) can use custom metadata to filter search results during retrieval.

The collection contains approximately 6,000 IT service management (ITSM) incidents with the following fields:

- incident_id
- description
- assigned_it_person
- category
- severity
- status
- date

## Metadata

The following fields are configured as custom metadata columns in the RAM sources page:

- category (Access, Application, Database, Email, Hardware, Infrastructure, Network, Security, Software)
- severity (Low, Medium, High, Critical)
- status (Open, In Progress, Investigating, Resolved, Closed)
- date
- assigned_it_person

After assigning the desired metadata columns to the source file, you must create and vectorize a collection that the agent will use.

## Approaches

After you create the collection, there are two ways to connect agents to it:
- [Tool-based experiment with agentic retrieval enabled](./tool_based/):

Check failure on line 30 in examples/agents/metadata_filtering_agent/README.md

View workflow job for this annotation

GitHub Actions / lint

Lists should be surrounded by blank lines

examples/agents/metadata_filtering_agent/README.md:30 MD032/blanks-around-lists Lists should be surrounded by blank lines [Context: "- [Tool-based experiment with ..."] https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md032.md

Check failure on line 30 in examples/agents/metadata_filtering_agent/README.md

View workflow job for this annotation

GitHub Actions / lint

Unordered list indentation

examples/agents/metadata_filtering_agent/README.md:30:1 MD007/ul-indent Unordered list indentation [Expected: 0; Actual: 2] https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md007.md
- This is often the easiest option when users interact directly with the agent and are unlikely to know the underlying metadata schema.

Check failure on line 31 in examples/agents/metadata_filtering_agent/README.md

View workflow job for this annotation

GitHub Actions / lint

Unordered list indentation

examples/agents/metadata_filtering_agent/README.md:31:1 MD007/ul-indent Unordered list indentation [Expected: 2; Actual: 4] https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md007.md
- In this approach, the LLM selects the appropriate filters to use based on the user's query.

Check failure on line 32 in examples/agents/metadata_filtering_agent/README.md

View workflow job for this annotation

GitHub Actions / lint

Unordered list indentation

examples/agents/metadata_filtering_agent/README.md:32:1 MD007/ul-indent Unordered list indentation [Expected: 2; Actual: 4] https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md007.md
- [Template-based experiment](./template_based):

Check failure on line 33 in examples/agents/metadata_filtering_agent/README.md

View workflow job for this annotation

GitHub Actions / lint

Unordered list indentation

examples/agents/metadata_filtering_agent/README.md:33:1 MD007/ul-indent Unordered list indentation [Expected: 0; Actual: 2] https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md007.md
- This approach gives the caller complete control over retrieval because filters are supplied explicitly to the agent.

Check failure on line 34 in examples/agents/metadata_filtering_agent/README.md

View workflow job for this annotation

GitHub Actions / lint

Unordered list indentation

examples/agents/metadata_filtering_agent/README.md:34:1 MD007/ul-indent Unordered list indentation [Expected: 2; Actual: 4] https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md007.md
- A template-based approach may be a better fit when retrieval filters must be explicitly controlled, generated by another application, or applied consistently across repeated queries.

Check failure on line 35 in examples/agents/metadata_filtering_agent/README.md

View workflow job for this annotation

GitHub Actions / lint

Unordered list indentation

examples/agents/metadata_filtering_agent/README.md:35:1 MD007/ul-indent Unordered list indentation [Expected: 2; Actual: 4] https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md007.md

## How It Works

For each request:

1. Apply metadata filters.
2. Retrieve matching records.
3. Rank results semantically.
4. Return the most relevant matches.
5,001 changes: 5,001 additions & 0 deletions examples/agents/metadata_filtering_agent/it_incidents_large.csv

Large diffs are not rendered by default.

29 changes: 29 additions & 0 deletions examples/agents/metadata_filtering_agent/template_based/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
# Template-Based Experiment Metadata Filtering

This example uses a code template that applies explicit metadata filters supplied by the user.

## Supported Metadata

- category
- severity
- status
- date
- assigned_it_person

## Example Query

```text
#filters: {"category":"Database","status":"Investigating"}
What database issues are currently under investigation?
```

RAM first applies the exact-match metadata filters and then performs semantic retrieval on the remaining records.

## Why Use This Approach?

Use the template-based approach when:

- Exact filtering behavior is required
- Filters are generated programmatically
- Retrieval must be deterministic and reproducible
- Users already know which metadata filters should be applied
45 changes: 45 additions & 0 deletions examples/agents/metadata_filtering_agent/template_based/run.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,45 @@
import json

from sasram.agent import Client


def _parse(text: str) -> tuple[str, dict[str, object]]:
content = text.strip()
# Without a directive, use the whole prompt as an unfiltered retrieval question.
if not content.lower().startswith("#filters:"):
return content, {}

# Optional first line: #filters: {"priority": "high"}; the question follows below.
directive, _, question = content.partition("\n")
try:
filters = json.loads(directive.split(":", 1)[1].strip())
except json.JSONDecodeError as error:
raise ValueError("#filters must contain valid JSON.") from error

if not isinstance(filters, dict):
raise ValueError("#filters must contain a JSON object.")

return question.strip(), filters


async def exec(text: str, ram_client: Client) -> str:
try:
question, filters = _parse(text)
except ValueError as error:
return str(error)

if not question:
return "Include a question after the retrieval directives."

search_kwargs: dict[str, object] = {"k": 10}
if filters:
# Keys and values must match metadata already present in the collection.
search_kwargs["filter"] = filters

# RAM retrieves up to 10 matching results and generates the answer.
response = ram_client.post_query(
prompt=question,
search_kwargs=search_kwargs,
persistent=False,

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why is persistent false here?

)
return response.response.answer
45 changes: 45 additions & 0 deletions examples/agents/metadata_filtering_agent/tool_based/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,45 @@
# Tool-Based Experiment Metadata Filtering

This example uses the default tool-based agent with Agentic Retrieval to automatically infer metadata filters from natural-language requests.

## Configuration

When creating the agent experiment:

1. Add the collection containing the IT incidents document.
2. Enable **Agentic Retrieval** toggle under Collections.
3. (Optional) Include instructions in the agent's system prompt on how/when to properly use the filters.

## Example

User:

```text
Show me critical security incidents that are still open.
```

The LLM can automatically infer filters such as:

```json
{
"category": "Security",
"severity": "Critical",
"status": "Open"
}
```

before performing semantic search.

## Why Use This Approach?

- No filter syntax required
- Natural-language queries
- Automatic metadata inference
- Better experience for business users
- Faster to configure than a custom filtering template

## Agentic Retrieval vs Template-Based Filtering

Agentic Retrieval is often the easiest option when users interact directly with an agent and are unlikely to know the underlying metadata schema.

A template-based approach may be a better fit when retrieval filters must be explicitly controlled, generated by another application, or applied consistently across repeated queries.
Comment on lines +41 to +45

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
## Agentic Retrieval vs Template-Based Filtering
Agentic Retrieval is often the easiest option when users interact directly with an agent and are unlikely to know the underlying metadata schema.
A template-based approach may be a better fit when retrieval filters must be explicitly controlled, generated by another application, or applied consistently across repeated queries.

1 change: 1 addition & 0 deletions examples/custom_sources/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -57,6 +57,7 @@ A custom source example will typically contain:

| Example | Description |
| ------- | ----------- |
| [File Tags](./file_tags/) | A source that generates three IT support documents and tags them by source filename, including multiple tags on one file |
| [Financial News Fetcher](./financial_news_fetcher/) | A source that fetches daily financial news articles for use in a financial news collection |
| [News Source](./news_source/) | A parameterized news source that fetches from NYT, Reddit, and Yahoo Finance for a configurable news domain |
| [NYT Front Page Source](./nyt_front_page_source/) | A source that fetches daily headlines from all 26 NYT Top Stories sections |
58 changes: 58 additions & 0 deletions examples/custom_sources/file_tags/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,58 @@
# File Tags Custom Source

This example generates three fictional IT support documents and applies different
file tags using the RAM Custom Source API. It demonstrates saving files and then
tagging them by their source filenames, including multiple tags on one file.

## How It Works

The entry point in [run.py](./run.py) writes three text files under `/tmp`
and saves each with `client.save_file(filepath)`. It then applies tags with
`client.add_tags_to_file(filename, tags)`, using the matching source filename
without the `/tmp/` prefix.
Each tag is a `SourceClient.FileTag` with a name and description.

The password reset guide receives both its topic tag and an onboarding tag in
the same tagging call. The files are written directly under `/tmp`, not inside
a randomly named temporary directory, to keep source filenames stable.

This example uses separate save and tag calls because `save_file(..., tags=...)`
was observed to produce an untagged file and a second, tagged file under a random
temporary path in the reported RAM runtime. This behavior may depend on the
runtime version; verify that synchronization produces only the three filenames
Comment on lines +9 to +22

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The entry point in [run.py](./run.py) writes three text files under `/tmp`
and saves each with `client.save_file(filepath)`. It then applies tags with
`client.add_tags_to_file(filename, tags)`, using the matching source filename
without the `/tmp/` prefix.
Each tag is a `SourceClient.FileTag` with a name and description.
The password reset guide receives both its topic tag and an onboarding tag in
the same tagging call. The files are written directly under `/tmp`, not inside
a randomly named temporary directory, to keep source filenames stable.
This example uses separate save and tag calls because `save_file(..., tags=...)`
was observed to produce an untagged file and a second, tagged file under a random
temporary path in the reported RAM runtime. This behavior may depend on the
runtime version; verify that synchronization produces only the three filenames
The entry point in [run.py](./run.py) writes three text files under `/tmp`
and saves each with `client.save_file(filepath)`. It then applies tags with
`client.add_tags_to_file(filename, tags)`, using the matching source filename.
Each tag is a `SourceClient.FileTag` with a name and description.

below with their expected tags.

| Source File | Tags |
| ----------- | ---- |
| `password_reset.txt` | `account-access`, `employee-onboarding` |
| `vpn_connection.txt` | `networking` |
| `laptop_replacement.txt` | `hardware` |

The example does not clear the source or delete unrelated files. It uses fixed
filenames and tag names rather than generating new names for each synchronization.
If earlier versions created entries such as `tmp.../password_reset.txt`, remove
those obsolete entries manually; this example does not clean them up.
Comment on lines +31 to +34

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The example does not clear the source or delete unrelated files. It uses fixed
filenames and tag names rather than generating new names for each synchronization.
If earlier versions created entries such as `tmp.../password_reset.txt`, remove
those obsolete entries manually; this example does not clean them up.


## Setup

Follow the [general custom source instructions](../README.md):

1. Create a Custom Source template using [run.py](./run.py), then save and publish it.
2. Create a source from the template and synchronize it.
3. Inspect the source's files and confirm that their tags match the table above.
4. Add the source to a collection and vectorize it for retrieval.

No API keys, environment variables, LLM calls, or third-party packages are needed.
The example uses the Python standard library and `sasram` supplied by RAM.

## Adapting the Example

Replace `DOCUMENTS` with your own content, filenames, and tags. For files already
ingested into the source, use `client.add_tags_to_file` without uploading them again.
The API also provides `client.create_tag(tag)` to create a tag separately and
`client.untag_file(filename, tag_names)` to remove selected tags from a file.

File tags label whole documents. They are separate from the record-level
metadata filters demonstrated by the
[metadata filtering agent](../../agents/metadata_filtering_agent/).
This source demonstrates applying tags, not configuring agent retrieval filters.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
This source demonstrates applying tags, not configuring agent retrieval filters.

50 changes: 50 additions & 0 deletions examples/custom_sources/file_tags/run.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,50 @@
from pathlib import Path

from sasram.source import SourceClient


# Each entry contains a source filename, tag name, tag description, and document text.
DOCUMENTS = [
(
"password_reset.txt",
"account-access",
"Account access and password support.",
"Password reset guide\n\n"
"Use the organization's password reset portal to reset a forgotten password. "
"If you cannot complete identity verification, contact the IT help desk.\n",
),
(
"vpn_connection.txt",
"networking",
"Network connectivity and remote access support.",
"VPN connection guide\n\n"
"Connect to the internet, open the approved VPN client, and sign in. "
"If the connection fails, record the error message for the IT help desk.\n",
),
(
"laptop_replacement.txt",
"hardware",
"Device maintenance and replacement support.",
"Laptop replacement guide\n\n"
"Submit a device replacement request through the IT service portal. "
"Include the asset number and a description of the hardware problem.\n",
),
]


def exec(client: SourceClient):
for filename, tag_name, description, content in DOCUMENTS:
# Write directly under /tmp so source names do not include random subdirectories.
path = Path("/tmp") / filename
path.write_text(content, encoding="utf-8")
tags = [SourceClient.FileTag(name=tag_name, description=description)]
# A file can have multiple tags, such as a topic and an intended audience.
if filename == "password_reset.txt":
tags.append(SourceClient.FileTag(
name="employee-onboarding",
description="Guides relevant to new employees.",
))
# Save and tag separately to avoid the tagged-save duplication seen in RAM.
client.save_file(str(path))
# Tag the source filename, not the local /tmp path.
client.add_tags_to_file(filename, tags)
Loading