Skip to content

RULES: Unnecessary template rule removed, md table made yaml #650

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Sep 1, 2025
Merged

RULES: Unnecessary template rule removed, md table made yaml #650

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
124 changes: 100 additions & 24 deletions ai/.rules/rest_api_extract_parameters.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -202,30 +202,106 @@ Response:

Map diverse API documentation terms to consistent `dlt` parameters. Identify the API's term first, then find the corresponding `dlt` key.

| Concept | Common API Terms | dlt Parameter Key(s) | Notes |
|---------------------|-----------------------------------------------------|----------------------|--------------------------------------------|
| **Client** | | | |
| Base URL | Base URL, API Endpoint, Root URL, Service URL | `client.base_url` | Include version path (e.g., `/v1/`) |
| API Key (value) | API Key, Access Token, Secret, Token, Key | `client.auth.api_key`| (Handled via Secret Handling patterns) |
| API Key (param name)| `api_key`, `token`, `key`, `access_token` | `client.auth.name` | Query param name or Header name |
| API Key (location) | Query parameter, Header | `client.auth.location`| `query` or `header` |
| Bearer Token | Bearer Token, JWT | `client.auth.token` | (Handled via Secret Handling patterns) |
| **Pagination** | | | **Define per-resource if strategies differ!** |
| Next Cursor (source)| `next_cursor`, `next_page`, `nextToken`, `marker` | `paginator.cursor_path`| JSON path in response |
| Next Cursor (param) | `cursor`, `page_token`, `after`, `next`, `marker` | `paginator.cursor_param`| Query param name to send cursor |
| Offset (param) | `offset`, `skip`, `start`, `startIndex` | `paginator.offset_param`| Query param name |
| Page Number (param) | `page`, `page_number`, `pageNum` | `paginator.page_param`| Query param name |
| Page Size (param) | `limit`, `per_page`, `page_size`, `count`, `maxItems` | `paginator.limit_param`| Query param name |
| Total Items (source)| `total`, `total_count`, `total_results`, `count` | `paginator.total_path`| Optional JSON path in response |
| Link Header Relation| `next`, `last` | `paginator.next_url_path`| `rel` value in `Link` header |
| **Incremental** | | | **Define per-resource if strategies differ!** |
| Timestamp (param) | `since`, `updated_since`, `modified_since`, `from`| `incremental.start_param`| Query param name |
| Timestamp (source) | `updated_at`, `modified`, `last_updated`, `ts` | `incremental.cursor_path`| JSON path in response item |
| ID/Sequence (param) | `since_id`, `min_id`, `after_id`, `sequence` | `incremental.start_param`| Query param name |
| ID/Sequence (source)| `id`, `event_id`, `sequence_id`, `_id` | `incremental.cursor_path`| JSON path in response item |
| Initial Value | N/A | `incremental.initial_value`| Start value for first run |
| **Data** | | | |
| Data Array Path | `data`, `results`, `items`, `records`, `entries` | `endpoint.data_selector`| JSON path to the list of items |
```yaml
client:
base_url:
Copy link
Collaborator Author

@anuunchin anuunchin Aug 26, 2025

Choose a reason for hiding this comment

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

@zilto
maybe there should be another field concept_name:
so that we have something like

client:
   base_url:
      concept_name: "Base URL" 
      common_api_terms: ["Base URL", "API Endpoint", "Root URL", "Service URL"]

Otherwise, the names look like strictly defined variables 👀

Copy link
Collaborator

@zilto zilto Aug 26, 2025

Choose a reason for hiding this comment

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

I think it's fine given base_url is described via multiple common_api_terms

common_api_terms: ["Base URL", "API Endpoint", "Root URL", "Service URL"]
dlt_parameter: "client.base_url"
notes: "Include version path (e.g., /v1/)"

auth:
api_key_value:
common_api_terms: ["API Key", "Access Token", "Secret", "Token", "Key"]
dlt_parameter: "client.auth.api_key"
notes: "Handled via Secret Handling patterns"

api_key_param_name:
common_api_terms: ["api_key", "token", "key", "access_token"]
dlt_parameter: "client.auth.name"
notes: "Query param name or Header name"

api_key_location:
common_api_terms: ["Query parameter", "Header"]
dlt_parameter: "client.auth.location"
notes: "query or header"

bearer_token:
common_api_terms: ["Bearer Token", "JWT"]
dlt_parameter: "client.auth.token"
notes: "Handled via Secret Handling patterns"

pagination:
note: "Define per-resource if strategies differ!"

next_cursor_source:
common_api_terms: ["next_cursor", "next_page", "nextToken", "marker"]
dlt_parameter: "paginator.cursor_path"
notes: "JSON path in response"

next_cursor_param:
common_api_terms: ["cursor", "page_token", "after", "next", "marker"]
dlt_parameter: "paginator.cursor_param"
notes: "Query param name to send cursor"

offset_param:
common_api_terms: ["offset", "skip", "start", "startIndex"]
dlt_parameter: "paginator.offset_param"
notes: "Query param name"

page_number_param:
common_api_terms: ["page", "page_number", "pageNum"]
dlt_parameter: "paginator.page_param"
notes: "Query param name"

page_size_param:
common_api_terms: ["limit", "per_page", "page_size", "count", "maxItems"]
dlt_parameter: "paginator.limit_param"
notes: "Query param name"

total_items_source:
common_api_terms: ["total", "total_count", "total_results", "count"]
dlt_parameter: "paginator.total_path"
notes: "Optional JSON path in response"

link_header_relation:
common_api_terms: ["next", "last"]
dlt_parameter: "paginator.next_url_path"
notes: "rel value in Link header"

incremental:
note: "Define per-resource if strategies differ!"

timestamp_param:
common_api_terms: ["since", "updated_since", "modified_since", "from"]
dlt_parameter: "incremental.start_param"
notes: "Query param name"

timestamp_source:
common_api_terms: ["updated_at", "modified", "last_updated", "ts"]
dlt_parameter: "incremental.cursor_path"
notes: "JSON path in response item"

id_sequence_param:
common_api_terms: ["since_id", "min_id", "after_id", "sequence"]
dlt_parameter: "incremental.start_param"
notes: "Query param name"

id_sequence_source:
common_api_terms: ["id", "event_id", "sequence_id", "_id"]
dlt_parameter: "incremental.cursor_path"
notes: "JSON path in response item"

initial_value:
common_api_terms: ["N/A"]
dlt_parameter: "incremental.initial_value"
notes: "Start value for first run"

data:
data_array_path:
common_api_terms: ["data", "results", "items", "records", "entries"]
dlt_parameter: "endpoint.data_selector"
notes: "JSON path to the list of items"
```

## 7. Verification Checklist

Expand Down
9 changes: 0 additions & 9 deletions ai/.rules/rule.md
View file
Open in desktop

This file was deleted.

130 changes: 100 additions & 30 deletions ai/amp/AGENT.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -467,30 +467,106 @@ Response:

Map diverse API documentation terms to consistent `dlt` parameters. Identify the API's term first, then find the corresponding `dlt` key.

| Concept | Common API Terms | dlt Parameter Key(s) | Notes |
|---------------------|-----------------------------------------------------|----------------------|--------------------------------------------|
| **Client** | | | |
| Base URL | Base URL, API Endpoint, Root URL, Service URL | `client.base_url` | Include version path (e.g., `/v1/`) |
| API Key (value) | API Key, Access Token, Secret, Token, Key | `client.auth.api_key`| (Handled via Secret Handling patterns) |
| API Key (param name)| `api_key`, `token`, `key`, `access_token` | `client.auth.name` | Query param name or Header name |
| API Key (location) | Query parameter, Header | `client.auth.location`| `query` or `header` |
| Bearer Token | Bearer Token, JWT | `client.auth.token` | (Handled via Secret Handling patterns) |
| **Pagination** | | | **Define per-resource if strategies differ!** |
| Next Cursor (source)| `next_cursor`, `next_page`, `nextToken`, `marker` | `paginator.cursor_path`| JSON path in response |
| Next Cursor (param) | `cursor`, `page_token`, `after`, `next`, `marker` | `paginator.cursor_param`| Query param name to send cursor |
| Offset (param) | `offset`, `skip`, `start`, `startIndex` | `paginator.offset_param`| Query param name |
| Page Number (param) | `page`, `page_number`, `pageNum` | `paginator.page_param`| Query param name |
| Page Size (param) | `limit`, `per_page`, `page_size`, `count`, `maxItems` | `paginator.limit_param`| Query param name |
| Total Items (source)| `total`, `total_count`, `total_results`, `count` | `paginator.total_path`| Optional JSON path in response |
| Link Header Relation| `next`, `last` | `paginator.next_url_path`| `rel` value in `Link` header |
| **Incremental** | | | **Define per-resource if strategies differ!** |
| Timestamp (param) | `since`, `updated_since`, `modified_since`, `from`| `incremental.start_param`| Query param name |
| Timestamp (source) | `updated_at`, `modified`, `last_updated`, `ts` | `incremental.cursor_path`| JSON path in response item |
| ID/Sequence (param) | `since_id`, `min_id`, `after_id`, `sequence` | `incremental.start_param`| Query param name |
| ID/Sequence (source)| `id`, `event_id`, `sequence_id`, `_id` | `incremental.cursor_path`| JSON path in response item |
| Initial Value | N/A | `incremental.initial_value`| Start value for first run |
| **Data** | | | |
| Data Array Path | `data`, `results`, `items`, `records`, `entries` | `endpoint.data_selector`| JSON path to the list of items |
```yaml
client:
base_url:
common_api_terms: ["Base URL", "API Endpoint", "Root URL", "Service URL"]
dlt_parameter: "client.base_url"
notes: "Include version path (e.g., /v1/)"

auth:
api_key_value:
common_api_terms: ["API Key", "Access Token", "Secret", "Token", "Key"]
dlt_parameter: "client.auth.api_key"
notes: "Handled via Secret Handling patterns"

api_key_param_name:
common_api_terms: ["api_key", "token", "key", "access_token"]
dlt_parameter: "client.auth.name"
notes: "Query param name or Header name"

api_key_location:
common_api_terms: ["Query parameter", "Header"]
dlt_parameter: "client.auth.location"
notes: "query or header"

bearer_token:
common_api_terms: ["Bearer Token", "JWT"]
dlt_parameter: "client.auth.token"
notes: "Handled via Secret Handling patterns"

pagination:
note: "Define per-resource if strategies differ!"

next_cursor_source:
common_api_terms: ["next_cursor", "next_page", "nextToken", "marker"]
dlt_parameter: "paginator.cursor_path"
notes: "JSON path in response"

next_cursor_param:
common_api_terms: ["cursor", "page_token", "after", "next", "marker"]
dlt_parameter: "paginator.cursor_param"
notes: "Query param name to send cursor"

offset_param:
common_api_terms: ["offset", "skip", "start", "startIndex"]
dlt_parameter: "paginator.offset_param"
notes: "Query param name"

page_number_param:
common_api_terms: ["page", "page_number", "pageNum"]
dlt_parameter: "paginator.page_param"
notes: "Query param name"

page_size_param:
common_api_terms: ["limit", "per_page", "page_size", "count", "maxItems"]
dlt_parameter: "paginator.limit_param"
notes: "Query param name"

total_items_source:
common_api_terms: ["total", "total_count", "total_results", "count"]
dlt_parameter: "paginator.total_path"
notes: "Optional JSON path in response"

link_header_relation:
common_api_terms: ["next", "last"]
dlt_parameter: "paginator.next_url_path"
notes: "rel value in Link header"

incremental:
note: "Define per-resource if strategies differ!"

timestamp_param:
common_api_terms: ["since", "updated_since", "modified_since", "from"]
dlt_parameter: "incremental.start_param"
notes: "Query param name"

timestamp_source:
common_api_terms: ["updated_at", "modified", "last_updated", "ts"]
dlt_parameter: "incremental.cursor_path"
notes: "JSON path in response item"

id_sequence_param:
common_api_terms: ["since_id", "min_id", "after_id", "sequence"]
dlt_parameter: "incremental.start_param"
notes: "Query param name"

id_sequence_source:
common_api_terms: ["id", "event_id", "sequence_id", "_id"]
dlt_parameter: "incremental.cursor_path"
notes: "JSON path in response item"

initial_value:
common_api_terms: ["N/A"]
dlt_parameter: "incremental.initial_value"
notes: "Start value for first run"

data:
data_array_path:
common_api_terms: ["data", "results", "items", "records", "entries"]
dlt_parameter: "endpoint.data_selector"
notes: "JSON path to the list of items"
```

## 7. Verification Checklist

Expand Down Expand Up @@ -708,9 +784,3 @@ The presence of a field in the JSON that looks like a cryptic token (often base6
API docs using terminology like “cursor”, “continuation token”, “next token”, or showing request examples with parameters such as after, nextToken, cursor, etc.
Choose JSONResponseCursorPaginator if the API’s pagination is driven by such tokens in the response body. You will configure cursor_path to point at the JSON field containing the token (e.g. "cursors.next" as default, or "next_cursor", etc.), and cursor_param to the name of the query parameter the API expects (commonly "cursor" or "after"). The paginator will then automatically extract the token and append it as ?cursor=<token> (or your specified param name) on subsequent calls​

## Example markdown

# Example markdown

This is where you can write your first rule.

Loading