Skip to content

Commit a72fca4

Browse files
LnYo-ClyLnYo-Cly
authored
Merge pull request #95 from LnYo-Cly/refactor
Merge agent runtime, coding agent, release updates, and safety fixes.
2 parents 78ca58a + bf8dfa8 commit a72fca4

1,223 files changed

Lines changed: 188688 additions & 4787 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.editorconfig‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
root = true
2+
3+
[*]
4+
charset = utf-8
5+
end_of_line = lf
6+
insert_final_newline = true
7+
indent_style = space
8+
indent_size = 4
9+
10+
[*.md]
11+
trim_trailing_whitespace = false

‎.github/workflows/docs-build.yml‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
name: docs-build
2+
3+
on:
4+
pull_request:
5+
paths:
6+
- 'docs-site/**'
7+
- '.github/workflows/docs-build.yml'
8+
push:
9+
branches: [main, dev]
10+
paths:
11+
- 'docs-site/**'
12+
- '.github/workflows/docs-build.yml'
13+
14+
jobs:
15+
build:
16+
runs-on: ubuntu-latest
17+
defaults:
18+
run:
19+
working-directory: docs-site
20+
21+
steps:
22+
- name: Checkout
23+
uses: actions/checkout@v4
24+
25+
- name: Setup Node
26+
uses: actions/setup-node@v4
27+
with:
28+
node-version: '20'
29+
cache: 'npm'
30+
cache-dependency-path: docs-site/package-lock.json
31+
32+
- name: Install dependencies
33+
run: npm ci
34+
35+
- name: Build docs
36+
run: npm run build

‎.github/workflows/docs-pages.yml‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
name: docs-pages
2+
3+
on:
4+
push:
5+
branches: [main]
6+
paths:
7+
- 'docs-site/**'
8+
- '.github/workflows/docs-pages.yml'
9+
workflow_dispatch:
10+
11+
permissions:
12+
contents: read
13+
pages: write
14+
id-token: write
15+
16+
concurrency:
17+
group: docs-pages
18+
cancel-in-progress: true
19+
20+
jobs:
21+
build:
22+
runs-on: ubuntu-latest
23+
defaults:
24+
run:
25+
working-directory: docs-site
26+
steps:
27+
- name: Checkout
28+
uses: actions/checkout@v4
29+
30+
- name: Setup Node
31+
uses: actions/setup-node@v4
32+
with:
33+
node-version: '20'
34+
cache: 'npm'
35+
cache-dependency-path: docs-site/package-lock.json
36+
37+
- name: Configure Pages
38+
uses: actions/configure-pages@v5
39+
40+
- name: Install dependencies
41+
run: npm ci
42+
43+
- name: Build docs
44+
env:
45+
GITHUB_PAGES: 'true'
46+
run: npm run build
47+
48+
- name: Upload artifact
49+
uses: actions/upload-pages-artifact@v3
50+
with:
51+
path: docs-site/build
52+
53+
deploy:
54+
runs-on: ubuntu-latest
55+
needs: build
56+
environment:
57+
name: github-pages
58+
url: ${{ steps.deployment.outputs.page_url }}
59+
steps:
60+
- name: Deploy to GitHub Pages
61+
id: deployment
62+
uses: actions/deploy-pages@v4

‎.gitignore‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,10 +37,35 @@ build/
3737
### Local tooling ###
3838
.claude/
3939
AGENTS.md
40+
node_modules/
41+
dist/
42+
.rsbuild/
43+
.turbo/
44+
npm-debug.log*
45+
yarn-debug.log*
46+
yarn-error.log*
47+
pnpm-debug.log*
48+
49+
### Scratch / temp ###
50+
*.class
51+
.tmp*/
52+
.tmp*
53+
tmp/
54+
tmp-*/
55+
tmp-*.png
56+
tmp-*.txt
57+
tmp-*.log
4058

4159
### Mac OS ###
4260
.DS_Store
4361
/.idea/
4462
/ai4j/.gitignore
4563
/ai4j/src/main/resources/新建文本文档 (2).txt
4664
/ai4j-spring-boot-stater/.gitignore
65+
.ai4j/
66+
.docs/
67+
docs/
68+
APIResponse.md
69+
AGENT.md
70+
ai4j-release-package.log
71+
javadoc-ai4j.log

‎README-EN.md‎

Lines changed: 194 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,38 @@
1-
![Maven Central](https://img.shields.io/maven-central/v/io.github.lnyo-cly/ai4j?color=blue)
1+
<p align="center">
2+
<img src="https://capsule-render.vercel.app/api?type=waving&color=0:6A5ACD,100:2E86C1&height=180&section=header&text=ai4j&fontSize=46&fontColor=ffffff&animation=fadeIn&desc=Java%20AI%20Agentic%20SDK%20for%20JDK%208%2B&descAlignY=68" alt="ai4j banner" />
3+
</p>
4+
5+
<p align="center">
6+
<a href="https://search.maven.org/artifact/io.github.lnyo-cly/ai4j">
7+
<img src="https://img.shields.io/maven-central/v/io.github.lnyo-cly/ai4j?color=2E86C1&label=Maven%20Central" alt="Maven Central" />
8+
</a>
9+
<a href="https://lnyo-cly.github.io/ai4j/">
10+
<img src="https://img.shields.io/badge/Docs-GitHub%20Pages-0A7EA4" alt="Docs" />
11+
</a>
12+
<a href="https://www.apache.org/licenses/LICENSE-2.0.txt">
13+
<img src="https://img.shields.io/badge/License-Apache%202.0-1F6FEB" alt="License" />
14+
</a>
15+
<img src="https://img.shields.io/badge/JDK-8%2B-2EA043" alt="JDK 8+" />
16+
<img src="https://img.shields.io/badge/Agentic-Enabled-6F42C1" alt="Agentic Enabled" />
17+
<img src="https://img.shields.io/badge/MCP-Supported-0F766E" alt="MCP Supported" />
18+
<img src="https://img.shields.io/badge/RAG-Built--in-B45309" alt="RAG Built-in" />
19+
<img src="https://img.shields.io/badge/CLI%20%2F%20TUI%20%2F%20ACP-Built--in-475569" alt="CLI TUI ACP Built-in" />
20+
</p>
21+
222
# ai4j
3-
Since SpringAI requires JDK 17 and Spring Boot 3, but many applications still use JDK 8 version at present, so AI4J that can support JDK 8 is used to access large models such as OpenAI.
4-
An Java SDK for quickly integrating AI large model applications. It integrates multiple platform large models such as OpenAI, Ollama, Zhipu (ChatGLM), DeepSeek, Moonshot (Kimi), Tencent Hunyuan, Lingyi (01), etc. It provides a unified input and output (aligned with OpenAI), eliminates differences, optimizes function calls (Tool Call), optimizes RAG calls, and supports vector databases (Pinecone). It also supports JDK 1.8, providing users with the ability to quickly integrate AI.
23+
A Java AI Agentic development toolkit for JDK 8+, combining foundational AI capabilities with higher-level agent development capabilities.
24+
It covers multi-provider model access, unified I/O, Tool Calling, MCP, RAG, unified `VectorStore`, ChatMemory, agent runtime, coding agent, CLI / TUI / ACP, and FlowGram integration, helping Java applications grow from basic model integration to more complete agentic application development.
25+
26+
This repository has evolved into a multi-module SDK. In addition to the core `ai4j` module, it now provides `ai4j-agent`, `ai4j-coding`, `ai4j-cli`, `ai4j-spring-boot-starter`, `ai4j-flowgram-spring-boot-starter`, and `ai4j-bom`. If you only need the basic LLM integration layer, start with `ai4j`. If you need agent runtime, coding agent, CLI / ACP, Spring Boot, or FlowGram integration, add the corresponding modules.
27+
28+
## Positioning Compared with Common Java AI Options
29+
30+
| Option | Java baseline | Application style | Primary focus |
31+
| --- | --- | --- | --- |
32+
| `ai4j` | `JDK 8+` | Plain Java / Spring | Unified model access, Tool / MCP / RAG, agent runtime, coding agent, CLI / TUI / ACP |
33+
| `Spring AI` | `Java 17+` | `Spring Boot 3.x` | Spring-native AI integration, model access, Tool Calling, MCP, and RAG |
34+
| `Spring AI Alibaba` | `Java 17+` | `Spring Boot 3.x` | Spring and Alibaba Cloud AI ecosystem integration |
35+
| `LangChain4j` | `Java 17+` | Plain Java / Spring / Quarkus and more | General Java abstractions for LLM, agent, and RAG integration, plus AI Services |
536

637
## Supported platforms
738
+ OpenAi
@@ -21,6 +52,11 @@ An Java SDK for quickly integrating AI large model applications. It integrates m
2152
## Features
2253
+ Supports Spring and ordinary Java applications. Supports applications above Java 8.
2354
+ Multi-platform and multi-service.
55+
+ Provides `ai4j-agent` as the general agent runtime, with ReAct, subagents, agent teams, memory, tracing, and tool loop support.
56+
+ Built-in Coding Agent CLI / TUI with interactive repository sessions, provider profiles, workspace model override, and session/process management.
57+
+ Provides `ai4j-coding` as the coding agent runtime, with workspace-aware tools, outer loop, checkpoint compaction, subagent, and team collaboration support.
58+
+ Provides `ai4j-flowgram-spring-boot-starter` for integrating FlowGram workflows and trace in Spring Boot applications.
59+
+ Provides `ai4j-bom` for version alignment across multiple ai4j modules.
2460
+ Unified input and output.
2561
+ Unified error handling.
2662
+ Supports streaming output. Supports streaming output of function call parameters.
@@ -37,12 +73,140 @@ An Java SDK for quickly integrating AI large model applications. It integrates m
3773
+ [Quick access to open source large models such as qwen2.5 and llama3.1 on the Ollama platform in Java.](https://blog.csdn.net/qq_35650513/article/details/142408092?spm=1001.2014.3001.5501)
3874
+ [Build a legal AI assistant in Java and quickly implement RAG applications.](https://blog.csdn.net/qq_35650513/article/details/142568177?fromshare=blogdetail&sharetype=blogdetail&sharerId=142568177&sharerefer=PC&sharesource=qq_35650513&sharefrom=from_link)
3975

76+
## Coding Agent CLI / TUI
77+
78+
AI4J now includes `ai4j-cli`, which can be used directly as a local coding agent. Current capabilities include:
79+
80+
+ one-shot and persistent sessions
81+
+ CLI and TUI interaction modes
82+
+ provider profile persistence
83+
+ workspace-level model override
84+
+ subagent and agent team collaboration
85+
+ session persistence, resume, fork, history, tree, events, replay
86+
+ team board, team messages, and team resume for collaboration visibility
87+
+ process management and buffered logs
88+
89+
### Build
90+
91+
```powershell
92+
mvn -pl ai4j-cli -am -DskipTests package
93+
```
94+
95+
Artifact:
96+
97+
```text
98+
ai4j-cli/target/ai4j-cli-2.0.0-jar-with-dependencies.jar
99+
```
100+
101+
### one-shot example
102+
103+
```powershell
104+
java -jar .\ai4j-cli\target\ai4j-cli-2.0.0-jar-with-dependencies.jar code `
105+
--provider openai `
106+
--protocol responses `
107+
--model gpt-5-mini `
108+
--prompt "Read README and summarize the project structure"
109+
```
110+
111+
### interactive CLI example
112+
113+
```powershell
114+
java -jar .\ai4j-cli\target\ai4j-cli-2.0.0-jar-with-dependencies.jar code `
115+
--provider zhipu `
116+
--protocol chat `
117+
--model glm-4.7 `
118+
--base-url https://open.bigmodel.cn/api/coding/paas/v4 `
119+
--workspace .
120+
```
121+
122+
### TUI example
123+
124+
```powershell
125+
java -jar .\ai4j-cli\target\ai4j-cli-2.0.0-jar-with-dependencies.jar tui `
126+
--provider zhipu `
127+
--protocol chat `
128+
--model glm-4.7 `
129+
--base-url https://open.bigmodel.cn/api/coding/paas/v4 `
130+
--workspace .
131+
```
132+
133+
### Current protocol rules
134+
135+
The CLI currently exposes only two protocol families:
136+
137+
+ `chat`
138+
+ `responses`
139+
140+
If `--protocol` is omitted, the CLI resolves a default locally from provider/baseUrl:
141+
142+
+ `openai` + official OpenAI host -> `responses`
143+
+ `openai` + custom compatible `baseUrl` -> `chat`
144+
+ `doubao` / `dashscope` -> `responses`
145+
+ other providers -> `chat`
146+
147+
Notes:
148+
149+
+ `auto` is no longer exposed to users
150+
+ legacy `auto` values in existing config files are normalized to explicit protocols on load
151+
152+
### provider profile locations
153+
154+
+ global config: `~/.ai4j/providers.json`
155+
+ workspace config: `<workspace>/.ai4j/workspace.json`
156+
157+
Recommended workflow:
158+
159+
+ keep reusable long-term runtime profiles in the global config
160+
+ let each workspace reference one `activeProfile`
161+
+ use workspace `modelOverride` for temporary model switching
162+
163+
### Common commands
164+
165+
+ `/providers`
166+
+ `/provider`
167+
+ `/provider use <name>`
168+
+ `/provider save <name>`
169+
+ `/provider add <name> --provider <name> [--protocol <chat|responses>] [--model <name>] [--base-url <url>] [--api-key <key>]`
170+
+ `/provider edit <name> [--provider <name>] [--protocol <chat|responses>] [--model <name>|--clear-model] [--base-url <url>|--clear-base-url] [--api-key <key>|--clear-api-key]`
171+
+ `/provider default <name|clear>`
172+
+ `/provider remove <name>`
173+
+ `/model`
174+
+ `/model <name>`
175+
+ `/model reset`
176+
+ `/stream [on|off]`
177+
+ `/processes`
178+
+ `/process status|follow|logs|write|stop ...`
179+
+ `/resume <id>` / `/load <id>` / `/fork ...`
180+
181+
### Documentation entry points
182+
183+
+ [Coding Agent CLI Quickstart](docs-site/docs/getting-started/coding-agent-cli-quickstart.md)
184+
+ [Coding Agent CLI and TUI](docs-site/docs/agent/coding-agent-cli.md)
185+
+ [Multi-Provider Profiles](docs-site/docs/agent/multi-provider-profiles.md)
186+
+ [Coding Agent Command Reference](docs-site/docs/agent/coding-agent-command-reference.md)
187+
+ [Provider Configuration Examples](docs-site/docs/agent/provider-config-examples.md)
188+
40189
## Other support
41190
+ [[Low-cost transit platform] Low-cost ApiKey - Limited-time special offer 0.7:1 - Supports the latest o1 model.](https://api.trovebox.online/)
42191

43192
# Quick start
44193
## Import
194+
### Module selection
195+
+ Use `ai4j` for the core LLM / Tool Call / MCP / RAG capabilities
196+
+ Use `ai4j-agent` for the general agent runtime
197+
+ Use `ai4j-coding` for coding agent, workspace tools, and outer loop
198+
+ Use `ai4j-cli` for the local CLI / TUI / ACP host
199+
+ Use `ai4j-spring-boot-starter` for Spring Boot auto-configuration
200+
+ Use `ai4j-flowgram-spring-boot-starter` for FlowGram workflow integration
201+
+ Use `ai4j-bom` when you want version alignment across multiple modules
202+
45203
### Gradle
204+
```groovy
205+
implementation platform("io.github.lnyo-cly:ai4j-bom:${project.version}")
206+
implementation "io.github.lnyo-cly:ai4j"
207+
implementation "io.github.lnyo-cly:ai4j-agent"
208+
```
209+
46210
```groovy
47211
implementation group: 'io.github.lnyo-cly', name: 'ai4j', version: '${project.version}'
48212
```
@@ -53,6 +217,33 @@ implementation group: 'io.github.lnyo-cly', name: 'ai4j-spring-boot-starter', ve
53217

54218

55219
### Maven
220+
```xml
221+
<dependencyManagement>
222+
<dependencies>
223+
<dependency>
224+
<groupId>io.github.lnyo-cly</groupId>
225+
<artifactId>ai4j-bom</artifactId>
226+
<version>${project.version}</version>
227+
<type>pom</type>
228+
<scope>import</scope>
229+
</dependency>
230+
</dependencies>
231+
</dependencyManagement>
232+
```
233+
234+
```xml
235+
<!-- Recommended for multi-module usage -->
236+
<dependency>
237+
<groupId>io.github.lnyo-cly</groupId>
238+
<artifactId>ai4j-agent</artifactId>
239+
</dependency>
240+
241+
<dependency>
242+
<groupId>io.github.lnyo-cly</groupId>
243+
<artifactId>ai4j-coding</artifactId>
244+
</dependency>
245+
```
246+
56247
```xml
57248
<!-- Non-Spring application -->
58249
<dependency>

0 commit comments

Comments
 (0)