Skip to content

Commit 0ad592e

Browse files
lukaszsocha2lukaszsocha2
committed
add docs
1 parent dd19b9a commit 0ad592e

36 files changed

+7502
-0
lines changed

‎docs/sdk/ai.md‎

Lines changed: 148 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,148 @@
1+
AI
2+
==
3+
4+
AI allows to send an intelligence request to supported large language models and returns
5+
an answer based on the provided prompt and items.
6+
7+
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
8+
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
9+
10+
- [AI](#ai)
11+
- [Send AI request](#send-ai-request)
12+
- [Send AI text generation request](#send-ai-text-generation-request)
13+
- [Get AI Agent default configuration](#get-ai-agent-default-configuration)
14+
- [Extract metadata freeform](#extract-metadata-freeform)
15+
- [Extract metadata structured](#extract-metadata-structured)
16+
17+
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
18+
19+
Send AI request
20+
--------------------------
21+
22+
To send an AI request, call static
23+
[`sendAIRequest(String prompt, List<BoxAIItem> items, Mode mode)`][send-ai-request] method.
24+
In the request you have to provide a prompt, a list of items that your prompt refers to and a mode of the request.
25+
There are two modes available: `SINGLE_ITEM_QA` and `MULTI_ITEM_QA`, which specifies if this request refers to
26+
for a single or multiple items.
27+
28+
<!-- sample post_ai_ask -->
29+
```java
30+
BoxAIResponse response = BoxAI.sendAIRequest(
31+
api,
32+
"What is the content of the file?",
33+
Collections.singletonList("123456", BoxAIItem.Type.FILE),
34+
BoxAI.Mode.SINGLE_ITEM_QA
35+
);
36+
```
37+
38+
You can also provide a list of dialogue history entries to provide additional context to the LLM in generating the response, AI Agent configuration and flag to indicate whether citations should be returned.
39+
40+
NOTE: The AI endpoint may return a 412 status code if you use for your request a file which has just been updated to the box.
41+
It usually takes a few seconds for the file to be indexed and available for the AI endpoint.
42+
43+
[send-ai-request]: https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxAI.html#sendAIRequest-com.box.sdk.BoxAPIConnection-java.lang.String-java.util.List-com.box.sdk.BoxAI.Mode-
44+
45+
Send AI text generation request
46+
--------------
47+
48+
To send an AI request specifically focused on the creation of new text, call static
49+
[`sendAITextGenRequest(String prompt, List<BoxAIItem> items, List<BoxAIDialogueEntry> dialogueHistory)`][send-ai-text-gen-request] method.
50+
In the request you have to provide a prompt, a list of items that your prompt refers to and optionally a dialogue history,
51+
which provides additional context to the LLM in generating the response.
52+
53+
<!-- sample post_ai_text_gen -->
54+
```java
55+
List<BoxAIDialogueEntry> dialogueHistory = new ArrayList<>();
56+
dialogueHistory.add(
57+
new BoxAIDialogueEntry(
58+
"Make my email about public APIs sound more professional",
59+
"Here is the first draft of your professional email about public APIs.",
60+
BoxDateFormat.parse("2013-05-16T15:26:57-07:00")
61+
)
62+
);
63+
BoxAIResponse response = BoxAI.sendAITextGenRequest(
64+
api,
65+
"Write an email to a client about the importance of public APIs.",
66+
Collections.singletonList(new BoxAIItem("123456", BoxAIItem.Type.FILE)),
67+
dialogueHistory
68+
);
69+
```
70+
71+
You can also provide an AI Agent configuration to customize the behavior of the AI response generation.
72+
73+
[send-ai-text-gen-request]: https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxAI.html#sendAITextGenRequest-com.box.sdk.BoxAPIConnection-java.lang.String-java.util.List-java.util.List-
74+
75+
Get AI Agent default configuration
76+
--------------------------
77+
78+
To get the default configuration of the AI Agent, call static
79+
[`getAiAgentDefaultConfig(BoxAPIConnection api, BoxAIAgent.Mode mode, String language, String model)`][get-ai-agent-default-config] method.
80+
In the request you have to provide the mode of the AI Agent, the language and the model, with the model is required while the language and mode are optional.
81+
82+
<!-- sample get_ai_agent_default -->
83+
```java
84+
BoxAIAgentConfig config = BoxAI.getAiAgentDefaultConfig(
85+
api,
86+
BoxAIAgent.Mode.ASK,
87+
"en",
88+
"openai__gpt_3_5_turbo"
89+
);
90+
```
91+
92+
[get-ai-agent-default-config]: http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxAI.html#getAiAgentDefaultConfig-com.box.sdk.BoxAPIConnection-com.box.sdk.ai.BoxAIAgent.Mode-java.lang.String-java.lang.String-
93+
94+
Extract metadata freeform
95+
--------------------------
96+
97+
To send an AI request to supported Large Language Models (LLMs) and extract metadata in form of key-value pairs, call static
98+
[`extractMetadataFreeform(BoxAPIConnection api, String prompt, List<BoxAIItem> items)`][extract-metadata-freeform] method.
99+
In the request you have to provide a prompt, a list of items that your prompt refers to and an optional agent configuration.
100+
101+
<!-- sample post_ai_extract -->
102+
```java
103+
BoxAIResponse response = BoxAI.extractMetadataFreeform(
104+
api,
105+
"firstName, lastName, location, yearOfBirth, company",
106+
Collections.singletonList(new BoxAIItem("123456", BoxAIItem.Type.FILE))
107+
);
108+
```
109+
110+
[extract-metadata-freeform]: https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxAI.html#extractMetadataFreeform-com.box.sdk.BoxAPIConnection-java.lang.String-java.util.List-
111+
112+
Extract metadata structured
113+
--------------------------
114+
115+
Sends an AI request to supported Large Language Models (LLMs) and returns extracted metadata as a set of key-value pairs. For this request, you need to use an already defined metadata template or define a schema yourself.
116+
117+
To send an AI request to extract metadata from files with a predefined metadata template, call static
118+
[`extractMetadataStructured extractMetadataStructured(BoxAPIConnection api, List<BoxAIItem> items, BoxAIExtractMetadataTemplate template)`][extract-metadata-structured-metadata-template] method.
119+
120+
<!-- sample post_ai_extract_structured -->
121+
```java
122+
BoxAIExtractMetadataTemplate template = new BoxAIExtractMetadataTemplate("templateKey", "enterprise");
123+
BoxAIExtractStructuredResponse result = BoxAI.extractMetadataStructured(
124+
api,
125+
Collections.singletonList(new BoxAIItem("123456", BoxAIItem.Type.FILE)),
126+
template
127+
);
128+
JsonObject sourceJson = result.getSourceJson();
129+
```
130+
131+
To send an AI request to extract metadata from files with custom fields, call static
132+
[`extractMetadataStructured extractMetadataStructured(BoxAPIConnection api, List<BoxAIItem> items, List<BoxAIExtractField> fields)`][extract-metadata-structured-fields] method.
133+
134+
<!-- sample post_ai_extract_structured_fields -->
135+
```java
136+
List<BoxAIExtractField> fields = new ArrayList<>();
137+
fields.add(new BoxAIExtractField("firstName"));
138+
139+
BoxAIExtractStructuredResponse result = BoxAI.extractMetadataStructured(
140+
api,
141+
Collections.singletonList(new BoxAIItem("123456", BoxAIItem.Type.FILE)),
142+
fields
143+
);
144+
JsonObject sourceJson = result.getSourceJson();
145+
```
146+
147+
[extract-metadata-structured-metadata-template]: https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxAI.html#extractMetadataStructured-com.box.sdk.BoxAPIConnection-java.util.List-com.box.sdk.ai.metadata.BoxAIExtractMetadataTemplate-
148+
[extract-metadata-structured-fields]: https://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxAI.html#extractMetadataStructured-com.box.sdk.BoxAPIConnection-java.util.List-java.util.List-

‎docs/sdk/android.md‎

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
# Android
2+
3+
The Java SDK should be compatible with modern Android applications written in both Java and Kotlin.
4+
5+
To use the Java SDK in an android application add it to the project's gradle file in the `dependencies` block.
6+
7+
For Groovy
8+
9+
```groovy
10+
// build.gradle
11+
12+
dependencies {
13+
implementation "com.box:box-java-sdk:3.8.0"
14+
}
15+
```
16+
17+
For Kotlin
18+
19+
```kotlin
20+
// build.gradle.kts
21+
22+
dependencies {
23+
implementation("com.box:box-java-sdk:3.8.0")
24+
}
25+
```
26+
27+
## Kotlin
28+
29+
The Java SDK can also be used in Kotlin Android applications through interoperability thanks to the Kotlin design.
30+
You can read more about Kotlin and Java interoperability [here](https://kotlinlang.org/docs/java-interop.html)
31+
32+
The following example creates an API connection with a developer token:
33+
34+
```kotlin
35+
val api = BoxAPIConnection("myToken")
36+
```
37+
38+
The following example shows how to get current user
39+
40+
```kotlin
41+
val userID = "33333"
42+
val api = BoxAPIConnection("myToken")
43+
val user = BoxUser(api, userID)
44+
val userInfo = user.getInfo()
45+
```
46+
47+
If you are using an IntelliJ-based IDE, you can copy our samples located in the [docs](/doc/) directory
48+
and paste them into your file. The IDE should ask you to convert the pasted Java sample to Kotlin. Most samples still work after conversion using this approach.
49+
50+
Note that the current Java SDK does not support Kotlin coroutines. By default, you cannot run network calls on the main thread
51+
in an Android application. There are various ways to overcome this. For example, if you are in a viewModel context, you can run the SDK method as a
52+
coroutine using viewModelScope.
53+
54+
```kotlin
55+
viewModelScope.launch {
56+
val result = withContext(Dispatchers.IO) {
57+
/*
58+
SDK code goes here
59+
*/
60+
}
61+
// here you can access the result and load it to the viewModel
62+
}
63+
```
64+
65+
The following example shows how to get the current items in the root folder, sorted by name in ascending order with additional
66+
"created_by" and "name" fields returned from the API. The items are then loaded to the custom data class defined earlier.
67+
68+
```kotlin
69+
// data class definition used in viewModel
70+
data class Item(
71+
val isFolder: Boolean,
72+
val name: String,
73+
val createdBy: String
74+
)
75+
76+
// viewModel init code
77+
viewModelScope.launch {
78+
val result = withContext(Dispatchers.IO) {
79+
val res = BoxFolder(BoxAPIConnection("myToken"), "0")
80+
val iterator: Iterator<BoxItem.Info> =
81+
res.getChildren("name", BoxFolder.SortDirection.ASC, "created_by", "name")
82+
.iterator()
83+
val items = mutableListOf<Item>()
84+
85+
when (val itemInfo = iterator.next()) {
86+
is BoxFile.Info -> items.add(Item(false, "File " + itemInfo.name, itemInfo.createdBy.name))
87+
is BoxFolder.Info -> items.add(Item(true, "Folder " + itemInfo.name, itemInfo.createdBy.name))
88+
}
89+
items
90+
}
91+
}
92+
```
93+
94+
If you are familiar with Kotlin syntax, you might have noticed that we could have used the `.map` function (or a similar function) to map the API result to a list of items. Due to current limitations, using `.map` and similar operations on collections is not always possible and may
95+
lead to unexpected results. The preferred way is to use an explicit iterator to iterate over the collections returned by the SDK.
96+
97+
If you find any problem related to the Java SDK in Kotlin-based app feel free to open an issue.

0 commit comments

Comments
 (0)