basant307/AI_Governance_Project

1# Qwen Code Java SDK2 3The Qwen Code Java SDK is a minimum experimental SDK for programmatic access to Qwen Code functionality. It provides a Java interface to interact with the Qwen Code CLI, allowing developers to integrate Qwen Code capabilities into their Java applications.4 5## Requirements6 7- Java >= 1.88- Maven >= 3.6.0 (for building from source)9- qwen-code >= 0.5.010 11### Dependencies12 13- **Logging**: ch.qos.logback:logback-classic14- **Utilities**: org.apache.commons:commons-lang315- **JSON Processing**: com.alibaba.fastjson2:fastjson216- **Testing**: JUnit 5 (org.junit.jupiter:junit-jupiter)17 18## Installation19 20Add the following dependency to your Maven `pom.xml`:21 22```xml23<dependency>24    <groupId>com.alibaba</groupId>25    <artifactId>qwencode-sdk</artifactId>26    <version>{$version}</version>27</dependency>28```29 30Or if using Gradle, add to your `build.gradle`:31 32```gradle33implementation 'com.alibaba:qwencode-sdk:{$version}'34```35 36## Building and Running37 38### Build Commands39 40```bash41# Compile the project42mvn compile43 44# Run tests45mvn test46 47# Package the JAR48mvn package49 50# Install to local repository51mvn install52```53 54## Quick Start55 56The simplest way to use the SDK is through the `QwenCodeCli.simpleQuery()` method:57 58```java59public static void runSimpleExample() {60    List<String> result = QwenCodeCli.simpleQuery("hello world");61    result.forEach(logger::info);62}63```64 65For more advanced usage with custom transport options:66 67```java68public static void runTransportOptionsExample() {69    TransportOptions options = new TransportOptions()70            .setModel("qwen3-coder-flash")71            .setPermissionMode(PermissionMode.AUTO_EDIT)72            .setCwd("./")73            .setEnv(new HashMap<String, String>() {{put("CUSTOM_VAR", "value");}})74            .setIncludePartialMessages(true)75            .setTurnTimeout(new Timeout(120L, TimeUnit.SECONDS))76            .setMessageTimeout(new Timeout(90L, TimeUnit.SECONDS))77            .setAllowedTools(Arrays.asList("read_file", "write_file", "list_directory"));78 79    List<String> result = QwenCodeCli.simpleQuery("who are you, what are your capabilities?", options);80    result.forEach(logger::info);81}82```83 84For streaming content handling with custom content consumers:85 86```java87public static void runStreamingExample() {88    QwenCodeCli.simpleQuery("who are you, what are your capabilities?",89            new TransportOptions().setMessageTimeout(new Timeout(10L, TimeUnit.SECONDS)), new AssistantContentSimpleConsumers() {90 91                @Override92                public void onText(Session session, TextAssistantContent textAssistantContent) {93                    logger.info("Text content received: {}", textAssistantContent.getText());94                }95 96                @Override97                public void onThinking(Session session, ThinkingAssistantContent thinkingAssistantContent) {98                    logger.info("Thinking content received: {}", thinkingAssistantContent.getThinking());99                }100 101                @Override102                public void onToolUse(Session session, ToolUseAssistantContent toolUseContent) {103                    logger.info("Tool use content received: {} with arguments: {}",104                            toolUseContent, toolUseContent.getInput());105                }106 107                @Override108                public void onToolResult(Session session, ToolResultAssistantContent toolResultContent) {109                    logger.info("Tool result content received: {}", toolResultContent.getContent());110                }111 112                @Override113                public void onOtherContent(Session session, AssistantContent<?> other) {114                    logger.info("Other content received: {}", other);115                }116 117                @Override118                public void onUsage(Session session, AssistantUsage assistantUsage) {119                    logger.info("Usage information received: Input tokens: {}, Output tokens: {}",120                            assistantUsage.getUsage().getInputTokens(), assistantUsage.getUsage().getOutputTokens());121                }122            }.setDefaultPermissionOperation(Operation.allow));123    logger.info("Streaming example completed.");124}125```126 127other examples see src/test/java/com/alibaba/qwen/code/cli/example128 129## Architecture130 131The SDK follows a layered architecture:132 133- **API Layer**: Provides the main entry points through `QwenCodeCli` class with simple static methods for basic usage134- **Session Layer**: Manages communication sessions with the Qwen Code CLI through the `Session` class135- **Transport Layer**: Handles the communication mechanism between the SDK and CLI process (currently using process transport via `ProcessTransport`)136- **Protocol Layer**: Defines data structures for communication based on the CLI protocol137- **Utils**: Common utilities for concurrent execution, timeout handling, and error management138 139## Key Features140 141### Permission Modes142 143The SDK supports different permission modes for controlling tool execution:144 145- **`default`**: Write tools are denied unless approved via `canUseTool` callback or in `allowedTools`. Read-only tools execute without confirmation.146- **`plan`**: Blocks all write tools, instructing AI to present a plan first.147- **`auto-edit`**: Auto-approve edit tools (`edit`, `write_file`, `notebook_edit`) while other tools require confirmation.148- **`yolo`**: All tools execute automatically without confirmation.149 150### Session Event Consumers and Assistant Content Consumers151 152The SDK provides two key interfaces for handling events and content from the CLI:153 154#### SessionEventConsumers Interface155 156The `SessionEventConsumers` interface provides callbacks for different types of messages during a session:157 158- `onSystemMessage`: Handles system messages from the CLI (receives Session and SDKSystemMessage)159- `onResultMessage`: Handles result messages from the CLI (receives Session and SDKResultMessage)160- `onAssistantMessage`: Handles assistant messages (AI responses) (receives Session and SDKAssistantMessage)161- `onPartialAssistantMessage`: Handles partial assistant messages during streaming (receives Session and SDKPartialAssistantMessage)162- `onUserMessage`: Handles user messages (receives Session and SDKUserMessage)163- `onOtherMessage`: Handles other types of messages (receives Session and String message)164- `onControlResponse`: Handles control responses (receives Session and CLIControlResponse)165- `onControlRequest`: Handles control requests (receives Session and CLIControlRequest, returns CLIControlResponse)166- `onPermissionRequest`: Handles permission requests (receives Session and CLIControlRequest<CLIControlPermissionRequest>, returns Behavior)167 168#### AssistantContentConsumers Interface169 170The `AssistantContentConsumers` interface handles different types of content within assistant messages:171 172- `onText`: Handles text content (receives Session and TextAssistantContent)173- `onThinking`: Handles thinking content (receives Session and ThinkingAssistantContent)174- `onToolUse`: Handles tool use content (receives Session and ToolUseAssistantContent)175- `onToolResult`: Handles tool result content (receives Session and ToolResultAssistantContent)176- `onOtherContent`: Handles other content types (receives Session and AssistantContent)177- `onUsage`: Handles usage information (receives Session and AssistantUsage)178- `onPermissionRequest`: Handles permission requests (receives Session and CLIControlPermissionRequest, returns Behavior)179- `onOtherControlRequest`: Handles other control requests (receives Session and ControlRequestPayload, returns ControlResponsePayload)180 181#### Relationship Between the Interfaces182 183**Important Note on Event Hierarchy:**184 185- `SessionEventConsumers` is the **high-level** event processor that handles different message types (system, assistant, user, etc.)186- `AssistantContentConsumers` is the **low-level** content processor that handles different types of content within assistant messages (text, tools, thinking, etc.)187 188**Processor Relationship:**189 190- `SessionEventConsumers` → `AssistantContentConsumers` (SessionEventConsumers uses AssistantContentConsumers to process content within assistant messages)191 192**Event Derivation Relationships:**193 194- `onAssistantMessage` → `onText`, `onThinking`, `onToolUse`, `onToolResult`, `onOtherContent`, `onUsage`195- `onPartialAssistantMessage` → `onText`, `onThinking`, `onToolUse`, `onToolResult`, `onOtherContent`196- `onControlRequest` → `onPermissionRequest`, `onOtherControlRequest`197 198**Event Timeout Relationships:**199 200Each event handler method has a corresponding timeout method that allows customizing the timeout behavior for that specific event:201 202- `onSystemMessage` ↔ `onSystemMessageTimeout`203- `onResultMessage` ↔ `onResultMessageTimeout`204- `onAssistantMessage` ↔ `onAssistantMessageTimeout`205- `onPartialAssistantMessage` ↔ `onPartialAssistantMessageTimeout`206- `onUserMessage` ↔ `onUserMessageTimeout`207- `onOtherMessage` ↔ `onOtherMessageTimeout`208- `onControlResponse` ↔ `onControlResponseTimeout`209- `onControlRequest` ↔ `onControlRequestTimeout`210 211For AssistantContentConsumers timeout methods:212 213- `onText` ↔ `onTextTimeout`214- `onThinking` ↔ `onThinkingTimeout`215- `onToolUse` ↔ `onToolUseTimeout`216- `onToolResult` ↔ `onToolResultTimeout`217- `onOtherContent` ↔ `onOtherContentTimeout`218- `onPermissionRequest` ↔ `onPermissionRequestTimeout`219- `onOtherControlRequest` ↔ `onOtherControlRequestTimeout`220 221**Default Timeout Values:**222 223- `SessionEventSimpleConsumers` default timeout: 180 seconds (Timeout.TIMEOUT_180_SECONDS)224- `AssistantContentSimpleConsumers` default timeout: 60 seconds (Timeout.TIMEOUT_60_SECONDS)225 226**Timeout Hierarchy Requirements:**227 228For proper operation, the following timeout relationships should be maintained:229 230- `onAssistantMessageTimeout` return value should be greater than `onTextTimeout`, `onThinkingTimeout`, `onToolUseTimeout`, `onToolResultTimeout`, and `onOtherContentTimeout` return values231- `onControlRequestTimeout` return value should be greater than `onPermissionRequestTimeout` and `onOtherControlRequestTimeout` return values232 233### Transport Options234 235The `TransportOptions` class allows configuration of how the SDK communicates with the Qwen Code CLI:236 237- `pathToQwenExecutable`: Path to the Qwen Code CLI executable238- `cwd`: Working directory for the CLI process239- `model`: AI model to use for the session240- `permissionMode`: Permission mode that controls tool execution241- `env`: Environment variables to pass to the CLI process242- `maxSessionTurns`: Limits the number of conversation turns in a session243- `coreTools`: List of core tools that should be available to the AI244- `excludeTools`: List of tools to exclude from being available to the AI245- `allowedTools`: List of tools that are pre-approved for use without additional confirmation246- `authType`: Authentication type to use for the session247- `includePartialMessages`: Enables receiving partial messages during streaming responses248- `turnTimeout`: Timeout for a complete turn of conversation249- `messageTimeout`: Timeout for individual messages within a turn250- `resumeSessionId`: ID of a previous session to resume251- `otherOptions`: Additional command-line options to pass to the CLI252 253### Session Control Features254 255- **Session creation**: Use `QwenCodeCli.newSession()` to create a new session with custom options256- **Session management**: The `Session` class provides methods to send prompts, handle responses, and manage session state257- **Session cleanup**: Always close sessions using `session.close()` to properly terminate the CLI process258- **Session resumption**: Use `setResumeSessionId()` in `TransportOptions` to resume a previous session259- **Session interruption**: Use `session.interrupt()` to interrupt a currently running prompt260- **Dynamic model switching**: Use `session.setModel()` to change the model during a session261- **Dynamic permission mode switching**: Use `session.setPermissionMode()` to change the permission mode during a session262 263### Thread Pool Configuration264 265The SDK uses a thread pool for managing concurrent operations with the following default configuration:266 267- **Core Pool Size**: 30 threads268- **Maximum Pool Size**: 100 threads269- **Keep-Alive Time**: 60 seconds270- **Queue Capacity**: 300 tasks (using LinkedBlockingQueue)271- **Thread Naming**: "qwen_code_cli-pool-{number}"272- **Daemon Threads**: false273- **Rejected Execution Handler**: CallerRunsPolicy274 275## Error Handling276 277The SDK provides specific exception types for different error scenarios:278 279- `SessionControlException`: Thrown when there's an issue with session control (creation, initialization, etc.)280- `SessionSendPromptException`: Thrown when there's an issue sending a prompt or receiving a response281- `SessionClosedException`: Thrown when attempting to use a closed session282 283## FAQ / Troubleshooting284 285### Q: Do I need to install the Qwen CLI separately?286 287A: yes, requires Qwen CLI 0.5.5 or higher.288 289### Q: What Java versions are supported?290 291A: The SDK requires Java 1.8 or higher.292 293### Q: How do I handle long-running requests?294 295A: The SDK includes timeout utilities. You can configure timeouts using the `Timeout` class in `TransportOptions`.296 297### Q: Why are some tools not executing?298 299A: This is likely due to permission modes. Check your permission mode settings and consider using `allowedTools` to pre-approve certain tools.300 301### Q: How do I resume a previous session?302 303A: Use the `setResumeSessionId()` method in `TransportOptions` to resume a previous session.304 305### Q: Can I customize the environment for the CLI process?306 307A: Yes, use the `setEnv()` method in `TransportOptions` to pass environment variables to the CLI process.308 309## License310 311Apache-2.0 - see [LICENSE](../../LICENSE) for details.312