Skip to content

Commit 6c1c544

Browse files
qiuosierqiuosier
authored
Merge pull request #656 from VipulMascarenhas/aihub_api_doc_update
Update AI hub api documentation
2 parents 6bd3742 + 53fb8b5 commit 6c1c544

File tree

4 files changed

+275
-9
lines changed

4 files changed

+275
-9
lines changed

‎ai-hub/ai-document-converter/README.md‎

Lines changed: 144 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -24,12 +24,152 @@ This application can be deployed using an [Oracle Resource Manager](https://doc
2424

2525
## APIs
2626

27+
### URLs
28+
Once the stack is successfully deployed, you can find the URLs for accessing the APIs in the Application Information section.
29+
30+
![Document Converter Stack](imgs/doc_converter_stack_successful.png)
31+
2732
The APIs include:
28-
* Converting a PDF from object storage to Markdown.
29-
* Converting a PDF file uploaded as file object to Markdown.
33+
* Converting a PDF from object storage to Markdown - Copy `API Endpoint - Convert from OSS` URL.
34+
* Converting a PDF file uploaded as file object to Markdown - Copy `API Endpoint - Convert from File` URL
35+
* MCP supported endpoint - Copy `MCP Endpoint` URL
36+
37+
Please see the API reference available in the `Playground UI URL` for more details and try them out.
38+
39+
40+
### Invoking Endpoints
41+
42+
To invoke the endpoints, you can use the following code.
43+
44+
#### Set up auth
45+
46+
```python
47+
import requests
48+
from pathlib import Path
49+
import oci
50+
51+
config = oci.config.from_file(
52+
"~/.oci/config"
53+
)
54+
token_file = config["security_token_file"]
55+
56+
with open(token_file, "r") as f:
57+
token = f.read()
58+
59+
private_key = oci.signer.load_private_key_from_file(config["key_file"])
60+
auth = oci.auth.signers.SecurityTokenSigner(token, private_key)
61+
62+
```
63+
64+
#### Converting PDF to Markdown from object storage
65+
66+
```python
67+
68+
# copy this URL from the Application information in the stack for this API
69+
url = "<api_endpoint_url>"
70+
71+
payload = {
72+
"document": "oci://bucket-name@namespace/prefix/file.pdf",
73+
"format": "markdown",
74+
"page": 1 # remove this param to process all pages of PDF
75+
}
76+
response = requests.post(url, json=payload, auth=auth,)
77+
print("Status:", response.status_code)
78+
print("Response:", response.json())
79+
80+
```
81+
82+
#### Converting PDF to Markdown using file upload
83+
84+
```python
85+
86+
# Load PDF into memory
87+
file_path = Path("~/Documents/dataset/file.pdf").expanduser()
88+
file_content = file_path.read_bytes()
89+
90+
# Compose request
91+
files = {
92+
"file": (file_path.name, file_content, "application/pdf")
93+
}
94+
params = {
95+
"page": 1
96+
}
97+
# set params to empty if you want to process all pages
98+
#params = {}
99+
headers = {}
100+
101+
# copy this URL from the Application information in the stack for this API
102+
url = "<api_endpoint_url>"
103+
response = requests.post(
104+
url=url,
105+
data=file_content,
106+
auth=auth,
107+
params=params,
108+
headers=headers
109+
)
110+
111+
```
112+
113+
#### MCP example using Accelerated Data Science
114+
115+
You can use ADS package to connect with the MCP endpoints. Follow instructions [here](https://accelerated-data-science.readthedocs.io/en/latest/user_guide/cli/quickstart.html) on how to install ADS.
116+
117+
118+
```python
119+
import asyncio
120+
121+
import ads
122+
from ads.aqua import HttpxOCIAuth
123+
from fastmcp import Client
124+
from fastmcp.client.transports import StreamableHttpTransport
125+
126+
# change profile accordingly
127+
ads.set_auth("security_token", profile="DEFAULT")
128+
129+
# copy this URL from the Application information in the stack for this endpoint
130+
server_url = "mcp_endpoint_url"
131+
132+
transport = StreamableHttpTransport(
133+
server_url, auth=HttpxOCIAuth(ads.auth.default_signer().get("signer"))
134+
)
135+
client = Client(
136+
transport=transport,
137+
)
138+
139+
async def main():
140+
async with client:
141+
tools = await client.list_tools()
142+
print("Available tools:")
143+
for tool in tools:
144+
print("-" * 30)
145+
print(tool.name)
146+
147+
print("=" * 30)
148+
149+
# will print the following tool names:
150+
# convert_route_convert_post : object storage api tool
151+
# list_apis_list_get : list avaiable endpoints api tool
152+
# convert_from_file_convert_file_post : file upload api tool, currently not supported
153+
154+
# call specific tool
155+
payload = {
156+
"document": "oci://bucket-name@namespace/prefix/file.pdf",
157+
"format": "markdown",
158+
"page": 1 # remove this param to process all pages of PDF
159+
}
160+
161+
print("Calling tool: convert_route_convert_post")
162+
result = await client.call_tool(
163+
"convert_route_convert_post", payload
164+
)
165+
print(result.data)
166+
167+
168+
asyncio.run(main())
169+
```
30170

31-
Please see the API reference `/api/docs` for more details to try them out.
171+
Note: File upload option is not supported due to the limitation of the current MCP server.
32172

33173

34174
[magic_button]: https://oci-resourcemanager-plugin.plugins.oci.oraclecloud.com/latest/deploy-to-oracle-cloud.svg
35-
[magic_stack]: https://cloud.oracle.com/resourcemanager/stacks/create?zipUrl=https://github.com/oracle-samples/oci-data-science-ai-samples/releases/download/1.0/ai-document-converter.zip
175+
[magic_stack]: https://cloud.oracle.com/resourcemanager/stacks/create?zipUrl=https://github.com/oracle-samples/oci-data-science-ai-samples/releases/latest/download/ai-document-converter.zip

‎ai-hub/ai-document-converter/imgs/doc_converter_stack_successful.png‎

277 KB
Loading

‎ai-hub/ai-translation/README.md‎

Lines changed: 131 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -21,12 +21,138 @@ This application can be deployed using an [Oracle Resource Manager](https://doc
2121

2222
## APIs
2323

24+
### URLs
25+
Once the stack is successfully deployed, you can find the URLs for accessing the APIs in the Application Information section.
26+
27+
![Document Converter Stack](imgs/ai_translation_app_stack_successful.png)
28+
29+
30+
2431
The APIs include:
25-
* Listing the supported languages
26-
* Text translation supporting streaming and async operations
27-
* Start batch Translation Job
32+
* Listing the supported languages - Copy `API Endpoint - Supported Languages` URL.
33+
* Text translation supporting streaming and async operations - Copy `API Endpoint - Translate` URL.
34+
* Start batch Translation Job - Copy `API Endpoint - Batch Translation Job` URL.
35+
* MCP supported endpoint - Copy `MCP Endpoint` URL
36+
37+
Please see the API reference available in the `Playground UI URL` for more details and try them out.
38+
39+
### Invoking Endpoints
40+
41+
To invoke the endpoints, you can use the following code.
42+
43+
#### Set up auth
44+
45+
```python
46+
import requests
47+
from pathlib import Path
48+
import oci
49+
50+
config = oci.config.from_file(
51+
"~/.oci/config"
52+
)
53+
token_file = config["security_token_file"]
54+
55+
with open(token_file, "r") as f:
56+
token = f.read()
57+
58+
private_key = oci.signer.load_private_key_from_file(config["key_file"])
59+
auth = oci.auth.signers.SecurityTokenSigner(token, private_key)
60+
61+
```
62+
63+
#### Listing the supported languages
64+
65+
```python
66+
67+
# copy this URL from the Application information in the stack for this API
68+
url = "<api_endpoint_url_languages>"
69+
70+
response = requests.get(url, auth=auth)
71+
72+
print("Status:", response.status_code)
73+
print("Response:", response.json())
74+
75+
```
76+
77+
#### Text translation supporting streaming and async operations
78+
79+
For non-streaming case:
80+
```python
81+
82+
# copy this URL from the Application information in the stack for this API
83+
url = "<api_endpoint_url_translate>"
84+
85+
payload = {"text": "hello", "language": "French"}
86+
response = requests.post(url, json=payload, auth=auth, stream=True)
87+
print("Status:", response.status_code)
88+
print("Response:", response.json())
89+
```
90+
91+
For streaming response:
92+
93+
```python
94+
text = "The twilight shimmered over the quiet town as the last train whistled in the distance. A lone cat perched atop a fence, its eyes reflecting the amber glow of a streetlamp. Inside a nearby café, the faint hum of jazz blended with the gentle clinking of cups. Somewhere, a typewriter clicked — each keystroke a heartbeat in the rhythm of a sleepless night. Outside, rain began to fall, soft and steady, painting the cobblestones with fleeting constellations of light."
95+
96+
payload = {
97+
"text": text,
98+
"language": "French",
99+
"stream": True
100+
}
101+
102+
with requests.post(url, json=payload, auth=auth, stream=True) as r:
103+
print("Status:", r.status_code)
104+
r.raise_for_status()
105+
106+
for line in r.iter_lines(decode_unicode=True):
107+
if line:
108+
print(line)
109+
```
110+
111+
#### MCP example using Accelerated Data Science
112+
113+
You can use ADS package to connect with the MCP endpoints. Follow instructions [here](https://accelerated-data-science.readthedocs.io/en/latest/user_guide/cli/quickstart.html) on how to install ADS.
114+
115+
116+
```python
117+
import asyncio
118+
119+
import ads
120+
from ads.aqua import HttpxOCIAuth
121+
from fastmcp import Client
122+
from fastmcp.client.transports import StreamableHttpTransport
123+
124+
125+
ads.set_auth("security_token", profile="DEV")
126+
127+
# copy this URL from the Application information in the stack for this endpoint
128+
server_url = "mcp_endpoint_url"
129+
130+
transport = StreamableHttpTransport(
131+
server_url, auth=HttpxOCIAuth(ads.auth.default_signer().get("signer"))
132+
)
133+
client = Client(
134+
transport=transport,
135+
)
136+
137+
138+
async def main():
139+
async with client:
140+
tools = await client.list_tools()
141+
print("Available tools:")
142+
for tool in tools:
143+
print("-" * 30)
144+
print(tool.name)
145+
146+
print("=" * 30)
147+
print("Calling tool")
148+
result = await client.call_tool(
149+
"api_text_translate_translate_post", {"text": "hello", "language": "French"}
150+
)
151+
print(result.data)
152+
28153

29-
Please see the API reference `/api/docs` for more details and try them out.
154+
asyncio.run(main())
155+
```
30156

31157
[magic_button]: https://oci-resourcemanager-plugin.plugins.oci.oraclecloud.com/latest/deploy-to-oracle-cloud.svg
32-
[magic_stack]: https://cloud.oracle.com/resourcemanager/stacks/create?zipUrl=https://github.com/oracle-samples/oci-data-science-ai-samples/releases/download/1.0/ai-translation.zip
158+
[magic_stack]: https://cloud.oracle.com/resourcemanager/stacks/create?zipUrl=https://github.com/oracle-samples/oci-data-science-ai-samples/releases/latest/download/ai-translation.zip

‎ai-hub/ai-translation/imgs/ai_translation_app_stack_successful.png‎

199 KB
Loading

0 commit comments

Comments
 (0)