Skip to content

Commit 0c7bcc2

Browse files
observerwobserverw
authored
refactor: rename Symbol API to Inspect API (#38)
1 parent bdd8d2c commit 0c7bcc2

19 files changed

+73
-184
lines changed

schema/SymbolCodeInfo.json renamed to schema/InspectCodeInfo.json

File renamed without changes.

schema/SymbolDetailInfo.json renamed to schema/InspectDetailInfo.json

File renamed without changes.

schema/SymbolInfo.json renamed to schema/InspectInfo.json

File renamed without changes.

schema/SymbolRequest.json renamed to schema/InspectRequest.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -105,6 +105,6 @@
105105
"required": [
106106
"locate"
107107
],
108-
"title": "SymbolRequest",
108+
"title": "InspectRequest",
109109
"type": "object"
110110
}

schema/SymbolResponse.json renamed to schema/InspectResponse.json

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -173,7 +173,7 @@
173173
"type": "object"
174174
}
175175
},
176-
"markdown": "\n# Symbol: `{{ info.path | join: \".\" }}` (`{{ info.kind }}`) at `{{ info.file_path }}`\n\n{% if info.code != nil -%}\n## Implementation\n```{{ info.file_path.suffix | remove_first: \".\" }}\n{{ info.code }}\n```\n{%- endif %}\n\n{% if call_hierarchy != nil -%}\n{% if call_hierarchy.incoming.size > 0 -%}\n## Incoming Calls\n{% for item in call_hierarchy.incoming -%}\n- `{{ item.name }}` (`{{ item.kind }}`) at `{{ item.file_path }}:{{ item.range.start.line }}`\n{% endfor -%}\n{%- endif %}\n\n{% if call_hierarchy.outgoing.size > 0 -%}\n## Outgoing Calls\n{% for item in call_hierarchy.outgoing -%}\n- `{{ item.name }}` (`{{ item.kind }}`) at `{{ item.file_path }}:{{ item.range.start.line }}`\n{% endfor -%}\n{%- endif %}\n{%- endif %}\n",
176+
"markdown": "\n# Inspect: `{{ info.path | join: \".\" }}` (`{{ info.kind }}`) at `{{ info.file_path }}`\n\n{% if info.code != nil -%}\n## Implementation\n```{{ info.file_path.suffix | remove_first: \".\" }}\n{{ info.code }}\n```\n{%- endif %}\n\n{% if call_hierarchy != nil -%}\n{% if call_hierarchy.incoming.size > 0 -%}\n## Incoming Calls\n{% for item in call_hierarchy.incoming -%}\n- `{{ item.name }}` (`{{ item.kind }}`) at `{{ item.file_path }}:{{ item.range.start.line }}`\n{% endfor -%}\n{%- endif %}\n\n{% if call_hierarchy.outgoing.size > 0 -%}\n## Outgoing Calls\n{% for item in call_hierarchy.outgoing -%}\n- `{{ item.name }}` (`{{ item.kind }}`) at `{{ item.file_path }}:{{ item.range.start.line }}`\n{% endfor -%}\n{%- endif %}\n{%- endif %}\n",
177177
"properties": {
178178
"info": {
179179
"$ref": "#/$defs/SymbolCodeInfo"
@@ -193,6 +193,6 @@
193193
"required": [
194194
"info"
195195
],
196-
"title": "SymbolResponse",
196+
"title": "InspectResponse",
197197
"type": "object"
198198
}

schema/SymbolScope.json renamed to schema/InspectScope.json

File renamed without changes.

‎schema/inspect.md‎

Lines changed: 21 additions & 68 deletions
Original file line numberDiff line numberDiff line change
@@ -1,89 +1,42 @@
11
# Inspect API
22

3-
## Overview
4-
The Inspect API provides "how to use" information for a specific symbol. While the Symbol API focuses on "what it is" (implementation details), the Inspect API is designed to help Agents understand how to correctly call or interact with a symbol by providing its signature, documentation, and real-world usage examples.
3+
The Inspect API provides detailed information about a specific code symbol,
4+
including its source code and documentation. It is the primary way for an
5+
Agent to understand the implementation and usage of a function, class, or variable.
56

6-
## When to Use
7-
- **Learning to call an API**: When an Agent needs to know the parameters, types, and return values of a function.
8-
- **Understanding usage patterns**: When an Agent wants to see how other parts of the codebase call a specific method to avoid common mistakes.
9-
- **Contextual documentation**: When the Agent needs a high-level summary of a symbol's purpose without reading the entire implementation.
7+
## Example Usage
108

11-
## Key Differences from Symbol API
12-
| Feature | Inspect API | Symbol API |
13-
|---------|-------------|------------|
14-
| **Primary Focus** | How to use the symbol | What the symbol is/does |
15-
| **Content** | Signature, Docstring, Usage Examples | Full Source Code, Implementation |
16-
| **Goal** | Integration & Calling | Understanding Implementation |
17-
| **Context** | External perspective | Internal perspective |
9+
### Scenario 1: Getting function documentation and implementation
1810

19-
## Request Schema
20-
- `locate`: The target symbol to inspect (supports `file_path`, `symbol_path`, `find`, etc.).
21-
- `include_usage`: (Boolean) Whether to include real-world usage examples from the codebase.
22-
- `max_usage_examples`: (Integer) Maximum number of usage examples to return.
11+
Request:
2312

24-
## Response Schema
25-
- `symbol`: Basic information about the symbol (name, kind, location).
26-
- `signature`: The formal signature of the symbol (e.g., function parameters and return types).
27-
- `documentation`: The docstring or comments associated with the symbol.
28-
- `usages`: A list of code snippets showing how the symbol is used elsewhere.
29-
30-
## Example: Inspecting a function
31-
**Request:**
3213
```json
3314
{
3415
"locate": {
35-
"file_path": "src/utils/auth.py",
16+
"file_path": "src/main.py",
3617
"scope": {
37-
"symbol_path": ["verify_token"]
18+
"symbol_path": ["calculate_total"]
3819
}
39-
},
40-
"include_usage": true,
41-
"max_usage_examples": 2
20+
}
4221
}
4322
```
4423

45-
**Response:**
24+
### Scenario 2: Getting class information
25+
26+
Request:
27+
4628
```json
4729
{
48-
"symbol": {
49-
"name": "verify_token",
50-
"kind": "function",
51-
"location": { "uri": "file:///src/utils/auth.py", "range": { ... } }
52-
},
53-
"signature": "def verify_token(token: str, secret: str = None) -> UserPayload",
54-
"documentation": "Verifies a JWT token and returns the decoded payload.\n\n:param token: The JWT string to verify.\n:param secret: Optional secret override.",
55-
"usages": [
56-
{
57-
"file_path": "src/api/middleware.py",
58-
"line": 42,
59-
"code": "payload = verify_token(auth_header.split(' ')[1])"
30+
"locate": {
31+
"file_path": "src/models.py",
32+
"scope": {
33+
"symbol_path": ["User"]
6034
}
61-
]
35+
}
6236
}
6337
```
6438

65-
**Markdown Output:**
66-
```markdown
67-
# Inspect: `verify_token`
68-
69-
**Signature:** `def verify_token(token: str, secret: str = None) -> UserPayload`
70-
71-
---
72-
73-
Verifies a JWT token and returns the decoded payload.
74-
75-
:param token: The JWT string to verify.
76-
:param secret: Optional secret override.
77-
78-
## Usage Examples
79-
80-
### src/api/middleware.py:42
81-
```python
82-
41 | auth_header = request.headers.get('Authorization')
83-
42 | payload = verify_token(auth_header.split(' ')[1])
84-
43 | request.user = payload
85-
```
39+
## References
8640

87-
## See Also
88-
- [Symbol API](./symbol.md)
89-
- [Reference API](./reference.md)
41+
- [InspectRequest.json](./InspectRequest.json)
42+
- [InspectResponse.json](./InspectResponse.json)

schema/symbol.request.json renamed to schema/inspect.request.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -100,6 +100,6 @@
100100
"required": [
101101
"locate"
102102
],
103-
"title": "SymbolRequest",
103+
"title": "InspectRequest",
104104
"type": "object"
105105
}

schema/symbol.response.json renamed to schema/inspect.response.json

Lines changed: 6 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -70,35 +70,13 @@
7070
"type": "string"
7171
}
7272
},
73-
"markdown": "\n# Symbol: `{{ path | join: \".\" }}` (`{{ kind }}`) at `{{ file_path }}`\n\n{% if code != nil -%}\n## Implementation\n```{{ file_path.suffix | remove_first: \".\" }}\n{{ code }}\n```\n{%- endif %}\n",
73+
"markdown": "\n# Inspect: `{{ path | join: \".\" }}` (`{{ kind }}`) at `{{ file_path }}`\n\n{% if code != nil -%}\n## Implementation\n```{{ file_path.suffix | remove_first: \".\" }}\n{{ code }}\n```\n{%- endif %}\n",
7474
"properties": {
75-
"file_path": {
76-
"format": "path",
77-
"title": "File Path",
78-
"type": "string"
79-
},
80-
"name": {
81-
"title": "Name",
82-
"type": "string"
83-
},
84-
"path": {
85-
"items": {
86-
"type": "string"
87-
},
88-
"title": "Path",
89-
"type": "array"
90-
},
91-
"kind": {
92-
"$ref": "#/$defs/SymbolKind"
93-
},
94-
"range": {
95-
"anyOf": [
96-
{
97-
"$ref": "#/$defs/Range"
98-
},
99-
{
100-
"type": "null"
101-
}
75+
...
76+
"title": "InspectResponse",
77+
"type": "object"
78+
}
79+
10280
],
10381
"default": null
10482
},

‎schema/search.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
# Search API
22

33
The Search API provides fast, fuzzy symbol search across the entire workspace.
4-
Results are concise for quick discovery—use the Symbol API to get detailed
4+
Results are concise for quick discovery—use the Inspect API to get detailed
55
information about specific symbols.
66

77
## Example Usage

0 commit comments

Comments
 (0)