@skroyc/librarian 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +176 -0
- package/LICENSE +210 -0
- package/README.md +614 -0
- package/biome.jsonc +9 -0
- package/dist/agents/context-schema.d.ts +17 -0
- package/dist/agents/context-schema.d.ts.map +1 -0
- package/dist/agents/context-schema.js +16 -0
- package/dist/agents/context-schema.js.map +1 -0
- package/dist/agents/react-agent.d.ts +38 -0
- package/dist/agents/react-agent.d.ts.map +1 -0
- package/dist/agents/react-agent.js +719 -0
- package/dist/agents/react-agent.js.map +1 -0
- package/dist/agents/tool-runtime.d.ts +7 -0
- package/dist/agents/tool-runtime.d.ts.map +1 -0
- package/dist/agents/tool-runtime.js +2 -0
- package/dist/agents/tool-runtime.js.map +1 -0
- package/dist/cli.d.ts +4 -0
- package/dist/cli.d.ts.map +1 -0
- package/dist/cli.js +172 -0
- package/dist/cli.js.map +1 -0
- package/dist/config.d.ts +4 -0
- package/dist/config.d.ts.map +1 -0
- package/dist/config.js +243 -0
- package/dist/config.js.map +1 -0
- package/dist/index.d.ts +41 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +470 -0
- package/dist/index.js.map +1 -0
- package/dist/tools/file-finding.tool.d.ts +24 -0
- package/dist/tools/file-finding.tool.d.ts.map +1 -0
- package/dist/tools/file-finding.tool.js +198 -0
- package/dist/tools/file-finding.tool.js.map +1 -0
- package/dist/tools/file-listing.tool.d.ts +12 -0
- package/dist/tools/file-listing.tool.d.ts.map +1 -0
- package/dist/tools/file-listing.tool.js +132 -0
- package/dist/tools/file-listing.tool.js.map +1 -0
- package/dist/tools/file-reading.tool.d.ts +9 -0
- package/dist/tools/file-reading.tool.d.ts.map +1 -0
- package/dist/tools/file-reading.tool.js +112 -0
- package/dist/tools/file-reading.tool.js.map +1 -0
- package/dist/tools/grep-content.tool.d.ts +27 -0
- package/dist/tools/grep-content.tool.d.ts.map +1 -0
- package/dist/tools/grep-content.tool.js +229 -0
- package/dist/tools/grep-content.tool.js.map +1 -0
- package/dist/utils/file-utils.d.ts +2 -0
- package/dist/utils/file-utils.d.ts.map +1 -0
- package/dist/utils/file-utils.js +28 -0
- package/dist/utils/file-utils.js.map +1 -0
- package/dist/utils/logger.d.ts +32 -0
- package/dist/utils/logger.d.ts.map +1 -0
- package/dist/utils/logger.js +177 -0
- package/dist/utils/logger.js.map +1 -0
- package/dist/utils/path-utils.d.ts +2 -0
- package/dist/utils/path-utils.d.ts.map +1 -0
- package/dist/utils/path-utils.js +9 -0
- package/dist/utils/path-utils.js.map +1 -0
- package/package.json +84 -0
- package/src/agents/context-schema.ts +61 -0
- package/src/agents/react-agent.ts +928 -0
- package/src/agents/tool-runtime.ts +21 -0
- package/src/cli.ts +206 -0
- package/src/config.ts +309 -0
- package/src/index.ts +628 -0
- package/src/tools/file-finding.tool.ts +324 -0
- package/src/tools/file-listing.tool.ts +212 -0
- package/src/tools/file-reading.tool.ts +154 -0
- package/src/tools/grep-content.tool.ts +325 -0
- package/src/utils/file-utils.ts +39 -0
- package/src/utils/logger.ts +295 -0
- package/src/utils/path-utils.ts +17 -0
- package/tsconfig.json +37 -0
- package/tsconfig.test.json +17 -0
package/README.md
ADDED
|
@@ -0,0 +1,614 @@
|
|
|
1
|
+
# Librarian CLI - Technology Research Agent
|
|
2
|
+
|
|
3
|
+
A powerful CLI tool that enables AI coding agents to query specific technology repositories and receive detailed technical responses through autonomous exploration.
|
|
4
|
+
|
|
5
|
+
## Overview
|
|
6
|
+
|
|
7
|
+
Librarian CLI allows AI coding agents to:
|
|
8
|
+
|
|
9
|
+
- Query specific technology repositories with detailed technical questions
|
|
10
|
+
- Receive autonomous exploration through a ReAct agent that reads and analyzes the codebase
|
|
11
|
+
- Get streaming markdown responses with technical insights and explanations
|
|
12
|
+
- Works out-of-the-box with OpenCode Zen (no LLM configuration required by default)
|
|
13
|
+
- Supports multiple LLM providers through LangChain's unified interface
|
|
14
|
+
|
|
15
|
+
## Features
|
|
16
|
+
|
|
17
|
+
- **Repository Management**: Auto-clone and sync from Git before each query
|
|
18
|
+
- **LangChain-Powered Agent**: Advanced AI agent using LangChain's createAgent for intelligent exploration
|
|
19
|
+
- **Unified Model Abstraction**: Support for OpenAI, Anthropic, Google, OpenAI-compatible, Anthropic-compatible, Claude CLI, and Gemini CLI APIs through LangChain (OpenCode Zen integration - no LLM required by default)
|
|
20
|
+
- **Dynamic Prompt Construction**: Context-aware system prompts based on technology/group selection
|
|
21
|
+
- **Sandboxed Tool Execution**: Secure file operations within isolated working directories
|
|
22
|
+
- **Integrated Toolset**: Built-in tools for file listing, reading, grep, and glob search
|
|
23
|
+
- **Grouped Technologies**: Organize tech stacks by groups (default, langchain, etc.)
|
|
24
|
+
- **Streamlined CLI**: Simple commands for exploration and listing available technologies
|
|
25
|
+
- **Robust Configuration**: YAML-based config with validation and path resolution
|
|
26
|
+
|
|
27
|
+
## Installation
|
|
28
|
+
|
|
29
|
+
### NPM Installation
|
|
30
|
+
|
|
31
|
+
```bash
|
|
32
|
+
# Install globally
|
|
33
|
+
npm install -g @skroyc/librarian
|
|
34
|
+
|
|
35
|
+
# Or install locally
|
|
36
|
+
npm install @skroyc/librarian
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
### Bun Installation
|
|
40
|
+
|
|
41
|
+
```bash
|
|
42
|
+
# Install globally
|
|
43
|
+
bun add -g @skroyc/librarian
|
|
44
|
+
|
|
45
|
+
# Or install locally
|
|
46
|
+
bun add @skroyc/librarian
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
### Quick Try
|
|
50
|
+
|
|
51
|
+
```bash
|
|
52
|
+
# Build and run directly with Nix
|
|
53
|
+
nix run github:SkrOYC/librarian -- --help
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
### Nix Installation
|
|
57
|
+
|
|
58
|
+
This project supports building with Nix using [bun2nix](https://github.com/nix-community/bun2nix).
|
|
59
|
+
|
|
60
|
+
#### Prerequisites
|
|
61
|
+
|
|
62
|
+
Ensure you have Nix with flakes enabled:
|
|
63
|
+
|
|
64
|
+
```bash
|
|
65
|
+
# Add to ~/.config/nix/nix.conf or /etc/nix/nix.conf
|
|
66
|
+
experimental-features = nix-command flakes
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
#### Option 1: NixOS System-wide
|
|
70
|
+
|
|
71
|
+
Add the librarian flake to your system configuration:
|
|
72
|
+
|
|
73
|
+
```nix
|
|
74
|
+
# In your /etc/nixos/flake.nix
|
|
75
|
+
{
|
|
76
|
+
inputs = {
|
|
77
|
+
nixpkgs.url = "github:nixos/nixpkgs?ref=nixos-unstable";
|
|
78
|
+
librarian.url = "github:SkrOYC/librarian";
|
|
79
|
+
};
|
|
80
|
+
|
|
81
|
+
outputs = inputs: {
|
|
82
|
+
# ... your existing nixosConfiguration ...
|
|
83
|
+
nixosConfigurations.yourhost = inputs.nixpkgs.lib.nixosSystem {
|
|
84
|
+
system = "x86_64-linux";
|
|
85
|
+
modules = [
|
|
86
|
+
# Your existing modules
|
|
87
|
+
({ pkgs, ... }: {
|
|
88
|
+
nixpkgs.overlays = [ inputs.librarian.overlays.default ];
|
|
89
|
+
environment.systemPackages = [ pkgs.librarian ];
|
|
90
|
+
})
|
|
91
|
+
];
|
|
92
|
+
};
|
|
93
|
+
};
|
|
94
|
+
}
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
Then rebuild:
|
|
98
|
+
```bash
|
|
99
|
+
sudo nixos-rebuild switch
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
#### Option 2: Home Manager (Recommended for multi-user systems)
|
|
103
|
+
|
|
104
|
+
Add to your Home Manager configuration:
|
|
105
|
+
|
|
106
|
+
```nix
|
|
107
|
+
# In ~/.config/nixpkgs/home.nix or within your home-manager module
|
|
108
|
+
{ inputs, pkgs, ... }:
|
|
109
|
+
|
|
110
|
+
{
|
|
111
|
+
home = {
|
|
112
|
+
packages = [ pkgs.librarian ];
|
|
113
|
+
};
|
|
114
|
+
|
|
115
|
+
# Or if using flake-based Home Manager
|
|
116
|
+
programs.home-manager.enable = true;
|
|
117
|
+
home-manager.users.youruser = { pkgs, ... }: {
|
|
118
|
+
home.packages = [ pkgs.librarian ];
|
|
119
|
+
};
|
|
120
|
+
}
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
With flakes:
|
|
124
|
+
```nix
|
|
125
|
+
# In your home-manager flake
|
|
126
|
+
{
|
|
127
|
+
inputs = {
|
|
128
|
+
nixpkgs.url = "github:nixos/nixpkgs?ref=nixos-unstable";
|
|
129
|
+
home-manager.url = "github:nix-community/home-manager";
|
|
130
|
+
librarian.url = "github:SkrOYC/librarian";
|
|
131
|
+
};
|
|
132
|
+
|
|
133
|
+
outputs = inputs: {
|
|
134
|
+
homeManagerModules = {
|
|
135
|
+
my-home = { pkgs, ... }: {
|
|
136
|
+
home.packages = [ pkgs.librarian ];
|
|
137
|
+
};
|
|
138
|
+
};
|
|
139
|
+
};
|
|
140
|
+
}
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
Then:
|
|
144
|
+
```bash
|
|
145
|
+
home-manager switch
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
#### Option 3: nix profile (User-wide, any Linux/macOS)
|
|
149
|
+
|
|
150
|
+
Install to your user profile:
|
|
151
|
+
|
|
152
|
+
```bash
|
|
153
|
+
# Install latest version
|
|
154
|
+
nix profile install github:SkrOYC/librarian
|
|
155
|
+
|
|
156
|
+
# Or pin to a specific version
|
|
157
|
+
nix profile install github:SkrOYC/librarian?ref=v0.1.0
|
|
158
|
+
|
|
159
|
+
# Update
|
|
160
|
+
nix profile upgrade librarian
|
|
161
|
+
|
|
162
|
+
# List installed packages
|
|
163
|
+
nix profile list
|
|
164
|
+
|
|
165
|
+
# Remove
|
|
166
|
+
nix profile remove librarian
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
#### Option 4: Flake Overlay (For your own flakes)
|
|
170
|
+
|
|
171
|
+
Use librarian as an overlay in your flake:
|
|
172
|
+
|
|
173
|
+
```nix
|
|
174
|
+
# In your flake.nix
|
|
175
|
+
{
|
|
176
|
+
inputs = {
|
|
177
|
+
nixpkgs.url = "github:nixos/nixpkgs?ref=nixos-unstable";
|
|
178
|
+
librarian.url = "github:SkrOYC/librarian";
|
|
179
|
+
};
|
|
180
|
+
|
|
181
|
+
outputs = inputs: {
|
|
182
|
+
packages = inputs.nixpkgs.lib.genAttrs [ "x86_64-linux" "aarch64-linux" ] (system: {
|
|
183
|
+
default = import inputs.nixpkgs {
|
|
184
|
+
inherit system;
|
|
185
|
+
overlays = [ inputs.librarian.overlays.default ];
|
|
186
|
+
}.librarian;
|
|
187
|
+
});
|
|
188
|
+
};
|
|
189
|
+
}
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
#### Building from Source
|
|
193
|
+
|
|
194
|
+
```bash
|
|
195
|
+
# Build the package (requires Nix flakes enabled)
|
|
196
|
+
nix build .#default
|
|
197
|
+
|
|
198
|
+
# The binary will be at ./result/bin/librarian
|
|
199
|
+
./result/bin/librarian --help
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
#### Darwin/macOS Support
|
|
203
|
+
|
|
204
|
+
Librarian supports macOS on both x86_64 and Apple Silicon:
|
|
205
|
+
|
|
206
|
+
```bash
|
|
207
|
+
# Run directly
|
|
208
|
+
nix run github:SkrOYC/librarian -- --help
|
|
209
|
+
|
|
210
|
+
# Install to profile
|
|
211
|
+
nix profile install github:SkrOYC/librarian
|
|
212
|
+
```
|
|
213
|
+
|
|
214
|
+
Note: Full system installation on macOS requires [nix-darwin](https://github.com/LnL7/nix-darwin):
|
|
215
|
+
|
|
216
|
+
## Quick Start
|
|
217
|
+
|
|
218
|
+
### 1. Configure Technologies
|
|
219
|
+
|
|
220
|
+
Create a configuration file at `~/.config/librarian/config.yaml`:
|
|
221
|
+
|
|
222
|
+
```yaml
|
|
223
|
+
repos_path: "~/.local/share/librarian/repos"
|
|
224
|
+
technologies:
|
|
225
|
+
default:
|
|
226
|
+
react:
|
|
227
|
+
repo: "https://github.com/facebook/react.git"
|
|
228
|
+
# Branch must be optional
|
|
229
|
+
branch: "main"
|
|
230
|
+
description: "JavaScript library for building user interfaces"
|
|
231
|
+
nodejs:
|
|
232
|
+
repo: "https://github.com/nodejs/node.git"
|
|
233
|
+
branch: "main"
|
|
234
|
+
description: "JavaScript runtime environment"
|
|
235
|
+
langchain:
|
|
236
|
+
langchain-javascript:
|
|
237
|
+
repo: "https://github.com/langchain-ai/langchainjs"
|
|
238
|
+
description: "LangChain is a framework for building LLM-powered..."
|
|
239
|
+
langgraph-javascript:
|
|
240
|
+
repo: "https://github.com/langchain-ai/langgraphjs"
|
|
241
|
+
description: "LangGraph is low-level orchestration framework..."
|
|
242
|
+
# Optional: Uncomment and configure LLM provider if you want to override OpenCode Zen
|
|
243
|
+
# aiProvider:
|
|
244
|
+
# type: openai # Options: openai, anthropic, google, openai-compatible, anthropic-compatible, claude-code, gemini-cli
|
|
245
|
+
# apiKey: # API key (loaded from .env as LIBRARIAN_API_KEY if not provided)
|
|
246
|
+
# model: gpt-5.2
|
|
247
|
+
# baseURL: # Optional for openai-compatible providers
|
|
248
|
+
```
|
|
249
|
+
|
|
250
|
+
### 2. Explore a Technology
|
|
251
|
+
|
|
252
|
+
```bash
|
|
253
|
+
# Query an specific tech
|
|
254
|
+
librarian explore "How does React handle state management?" --tech react
|
|
255
|
+
|
|
256
|
+
# Query a whole group (all technologies under it)
|
|
257
|
+
librarian explore "How does LangChain handle memory management?" --group langchain
|
|
258
|
+
```
|
|
259
|
+
|
|
260
|
+
### 3. List Available Technologies
|
|
261
|
+
|
|
262
|
+
```bash
|
|
263
|
+
# List all technologies
|
|
264
|
+
librarian list
|
|
265
|
+
# Returns this:
|
|
266
|
+
# group
|
|
267
|
+
# tech1: description
|
|
268
|
+
# tech2: description
|
|
269
|
+
# e.g.:
|
|
270
|
+
# default
|
|
271
|
+
# react: JavaScript library for building user interfaces
|
|
272
|
+
# nodejs: JavaScript runtime environment
|
|
273
|
+
# langchain
|
|
274
|
+
# langchain-javascript: LangChain is a framework for building...
|
|
275
|
+
# langgraph-javascript: LangGraph is low-level orchestration framework...
|
|
276
|
+
|
|
277
|
+
# List technologies in a specific group
|
|
278
|
+
librarian list --group langchain
|
|
279
|
+
# Returns this:
|
|
280
|
+
# langchain
|
|
281
|
+
# langchain-javascript: LangChain is a framework for building...
|
|
282
|
+
# langgraph-javascript: LangGraph is low-level orchestration framework...
|
|
283
|
+
```
|
|
284
|
+
|
|
285
|
+
## Commands
|
|
286
|
+
|
|
287
|
+
### `explore <query> --tech <technology>`
|
|
288
|
+
|
|
289
|
+
Execute agentic research on specified technology using a LangChain-powered agent. The agent operates in a sandboxed environment at `{repos_path}/{group}/{technology}` and streams the response to stdout.
|
|
290
|
+
|
|
291
|
+
**Options:**
|
|
292
|
+
|
|
293
|
+
- `--tech, -t <technology>`: Technology name
|
|
294
|
+
|
|
295
|
+
**Examples:**
|
|
296
|
+
|
|
297
|
+
```bash
|
|
298
|
+
librarian explore "Explain the virtual DOM implementation" --tech react
|
|
299
|
+
librarian explore "How are errors handled in this codebase?" --tech default:nodejs
|
|
300
|
+
```
|
|
301
|
+
|
|
302
|
+
### `explore <query> --group <group>`
|
|
303
|
+
|
|
304
|
+
Execute agentic research on whole group using a LangChain-powered agent. The agent operates in a sandboxed environment at `{repos_path}/{group}` with access to all technologies in the group.
|
|
305
|
+
|
|
306
|
+
**Options:**
|
|
307
|
+
|
|
308
|
+
- `--group, -g <group>`: Group name
|
|
309
|
+
|
|
310
|
+
**Examples:**
|
|
311
|
+
|
|
312
|
+
```bash
|
|
313
|
+
librarian explore "What are common patterns across React libraries?" --group default
|
|
314
|
+
librarian explore "What are middlewares in the langchain ecosystem?" --group langchain
|
|
315
|
+
```
|
|
316
|
+
|
|
317
|
+
### `list --group [group]`
|
|
318
|
+
|
|
319
|
+
List available technologies with descriptions.
|
|
320
|
+
|
|
321
|
+
**Options:**
|
|
322
|
+
|
|
323
|
+
- `--group, -g [group]`: Filter by technology group (default: all groups)
|
|
324
|
+
|
|
325
|
+
**Examples:**
|
|
326
|
+
|
|
327
|
+
```bash
|
|
328
|
+
librarian list
|
|
329
|
+
librarian list --group langchain
|
|
330
|
+
```
|
|
331
|
+
|
|
332
|
+
### `--help/-h`
|
|
333
|
+
|
|
334
|
+
Display help information for all commands.
|
|
335
|
+
|
|
336
|
+
## Configuration
|
|
337
|
+
|
|
338
|
+
### Configuration File Location
|
|
339
|
+
|
|
340
|
+
The configuration file must be located at `~/.config/librarian/config.yaml`.
|
|
341
|
+
|
|
342
|
+
### Configuration Schema
|
|
343
|
+
|
|
344
|
+
```yaml
|
|
345
|
+
repos_path: "~/.local/share/librarian/repos" # Shared directory for all technologies
|
|
346
|
+
technologies:
|
|
347
|
+
default: # Default group
|
|
348
|
+
react:
|
|
349
|
+
repo: "https://github.com/facebook/react.git"
|
|
350
|
+
branch: "main" # Optional, defaults to main/master
|
|
351
|
+
description: "JavaScript library for building user interfaces"
|
|
352
|
+
nodejs:
|
|
353
|
+
repo: "https://github.com/nodejs/node.git"
|
|
354
|
+
branch: "main"
|
|
355
|
+
description: "JavaScript runtime environment"
|
|
356
|
+
langchain: # Custom group
|
|
357
|
+
langchain-javascript:
|
|
358
|
+
repo: "https://github.com/langchain-ai/langchainjs"
|
|
359
|
+
description: "LangChain is a framework for building LLM-powered applications..."
|
|
360
|
+
langgraph-javascript:
|
|
361
|
+
repo: "https://github.com/langchain-ai/langgraphjs"
|
|
362
|
+
description: "LangGraph is low-level orchestration framework..."
|
|
363
|
+
# Optional: Uncomment and configure LLM provider if you want to override OpenCode Zen
|
|
364
|
+
# aiProvider:
|
|
365
|
+
# type: openai # Options: openai, anthropic, google, openai-compatible, anthropic-compatible, claude-code, gemini-cli
|
|
366
|
+
# apiKey: # API key (loaded from .env as LIBRARIAN_API_KEY if not provided)
|
|
367
|
+
# model: gpt-5.2
|
|
368
|
+
# baseURL: # Optional for openai-compatible providers
|
|
369
|
+
```
|
|
370
|
+
|
|
371
|
+
**Note**: The system works out-of-the-box with OpenCode Zen integration (no LLM configuration required by default). When configured, the system supports multiple providers through LangChain's unified interface.
|
|
372
|
+
|
|
373
|
+
### Repository Path Structure
|
|
374
|
+
|
|
375
|
+
Repositories are cloned to: `{repos_path}/{group}/{technology}`
|
|
376
|
+
|
|
377
|
+
**Agent Working Directory Sandboxing:**
|
|
378
|
+
|
|
379
|
+
- For `--tech` commands: Agent operates in `{repos_path}/{group}/{technology}`
|
|
380
|
+
- For `--group` commands: Agent operates in `{repos_path}/{group}`
|
|
381
|
+
|
|
382
|
+
This ensures all file paths are relative to the target directory and tool execution is securely isolated.
|
|
383
|
+
|
|
384
|
+
Example:
|
|
385
|
+
|
|
386
|
+
- `~/.local/share/librarian/repos/default/react/` (single tech exploration)
|
|
387
|
+
- `~/.local/share/librarian/repos/langchain/` (group-wide exploration)
|
|
388
|
+
|
|
389
|
+
## Architecture
|
|
390
|
+
|
|
391
|
+
### Core Components
|
|
392
|
+
|
|
393
|
+
1. **CLI Entry Point** (`src/cli.ts`)
|
|
394
|
+
- Command parsing with Commander.js
|
|
395
|
+
- Configuration loading and validation
|
|
396
|
+
- Error handling and exit codes
|
|
397
|
+
|
|
398
|
+
2. **Core Librarian** (`src/index.ts`)
|
|
399
|
+
- Main class for orchestrating operations
|
|
400
|
+
- Technology resolution
|
|
401
|
+
- Repository synchronization logic
|
|
402
|
+
|
|
403
|
+
3. **Repository Manager** (`src/repo/`)
|
|
404
|
+
- Git clone/pull operations
|
|
405
|
+
- Repository synchronization
|
|
406
|
+
- Local path management
|
|
407
|
+
|
|
408
|
+
4. **Agent Orchestrator** (`src/agent/`)
|
|
409
|
+
- LangChain createAgent-based implementation
|
|
410
|
+
- Dynamic system prompt construction based on group/tech context
|
|
411
|
+
- Tool integration with sandboxed execution environment
|
|
412
|
+
- Memory management with LangGraph
|
|
413
|
+
|
|
414
|
+
5. **LLM Provider** (`src/llm/`)
|
|
415
|
+
- LangChain unified model abstraction through `initChatModel`
|
|
416
|
+
- Multi-provider support via LangChain integrations
|
|
417
|
+
- Dynamic model switching without code changes
|
|
418
|
+
- Response streaming and structured output handling
|
|
419
|
+
|
|
420
|
+
### Agent Tools
|
|
421
|
+
|
|
422
|
+
The Librarian agent includes four core tools for repository exploration:
|
|
423
|
+
|
|
424
|
+
- **File Listing**: List files and directories within the sandboxed working directory
|
|
425
|
+
- **File Reading**: Read file contents with support for various file types
|
|
426
|
+
- **Grep Search**: Search file contents using regex patterns
|
|
427
|
+
- **Glob Search**: Find files by name patterns using glob syntax
|
|
428
|
+
|
|
429
|
+
All tools operate within the agent's isolated working directory, ensuring secure and context-aware file operations.
|
|
430
|
+
|
|
431
|
+
## Technology Management
|
|
432
|
+
|
|
433
|
+
### Adding New Technologies
|
|
434
|
+
|
|
435
|
+
1. Edit your `~/.config/librarian/config.yaml` file
|
|
436
|
+
2. Add your technology under the appropriate group
|
|
437
|
+
3. Specify the GitHub repository URL, branch, and description
|
|
438
|
+
4. Ensure the technology name is unique within its group
|
|
439
|
+
|
|
440
|
+
### Repository Management
|
|
441
|
+
|
|
442
|
+
- **Auto-Clone**: Repositories are automatically cloned when first accessed
|
|
443
|
+
- **Auto-Update**: Repositories are pulled for updates before each query
|
|
444
|
+
- **Path Resolution**: Repositories follow the pattern `{repos_path}/{group}/{technology}`
|
|
445
|
+
- **Branch Support**: Specify any branch (defaults to main/master if not specified)
|
|
446
|
+
|
|
447
|
+
## LLM Provider Configuration
|
|
448
|
+
|
|
449
|
+
Librarian uses LangChain's unified model abstraction and works out-of-the-box with OpenCode Zen (no LLM configuration required by default). Seamless switching between providers is possible through configuration. No code changes required when changing models.
|
|
450
|
+
|
|
451
|
+
By default, the system uses OpenCode Zen:
|
|
452
|
+
|
|
453
|
+
```yaml
|
|
454
|
+
aiProvider:
|
|
455
|
+
type: openai-compatible
|
|
456
|
+
model: grok-code
|
|
457
|
+
baseURL: "https://opencode.ai/zen/v1"
|
|
458
|
+
```
|
|
459
|
+
|
|
460
|
+
### OpenAI
|
|
461
|
+
|
|
462
|
+
```yaml
|
|
463
|
+
aiProvider:
|
|
464
|
+
type: openai
|
|
465
|
+
apiKey: # API key (loaded from .env as LIBRARIAN_API_KEY if not provided)
|
|
466
|
+
model: gpt-5.2
|
|
467
|
+
```
|
|
468
|
+
|
|
469
|
+
### Anthropic
|
|
470
|
+
|
|
471
|
+
```yaml
|
|
472
|
+
aiProvider:
|
|
473
|
+
type: anthropic
|
|
474
|
+
apiKey: # API key (loaded from .env as LIBRARIAN_API_KEY if not provided)
|
|
475
|
+
model: claude-opus-4-5-20251101
|
|
476
|
+
```
|
|
477
|
+
|
|
478
|
+
### Google
|
|
479
|
+
|
|
480
|
+
```yaml
|
|
481
|
+
aiProvider:
|
|
482
|
+
type: google
|
|
483
|
+
apiKey: # API key (loaded from .env as LIBRARIAN_API_KEY if not provided)
|
|
484
|
+
model: gemini-3-pro-preview
|
|
485
|
+
```
|
|
486
|
+
|
|
487
|
+
### OpenAI-Compatible
|
|
488
|
+
|
|
489
|
+
```yaml
|
|
490
|
+
aiProvider:
|
|
491
|
+
type: openai-compatible
|
|
492
|
+
model: your-model-name
|
|
493
|
+
baseURL: "https://your-provider.com/v1"
|
|
494
|
+
apiKey: # Optional API key (loaded from .env as LIBRARIAN_API_KEY if required by provider)
|
|
495
|
+
```
|
|
496
|
+
|
|
497
|
+
### Anthropic-Compatible
|
|
498
|
+
|
|
499
|
+
```yaml
|
|
500
|
+
aiProvider:
|
|
501
|
+
type: anthropic-compatible
|
|
502
|
+
model: your-model-name
|
|
503
|
+
baseURL: "https://your-anthropic-compatible-provider.com/v1"
|
|
504
|
+
apiKey: # API key (loaded from .env as LIBRARIAN_API_KEY if not provided)
|
|
505
|
+
```
|
|
506
|
+
|
|
507
|
+
### Claude Code (CLI-based)
|
|
508
|
+
|
|
509
|
+
```yaml
|
|
510
|
+
aiProvider:
|
|
511
|
+
type: claude-code
|
|
512
|
+
model: claude-sonnet-4-5 # Model name passed to Claude CLI
|
|
513
|
+
```
|
|
514
|
+
|
|
515
|
+
**Note**: For Claude Code provider, ensure the `claude` CLI is installed and available in your PATH.
|
|
516
|
+
|
|
517
|
+
### Gemini CLI (CLI-based)
|
|
518
|
+
|
|
519
|
+
```yaml
|
|
520
|
+
aiProvider:
|
|
521
|
+
type: gemini-cli
|
|
522
|
+
model: gemini-3-pro-preview # Model name passed to Gemini CLI
|
|
523
|
+
```
|
|
524
|
+
|
|
525
|
+
**Note**: For Gemini CLI provider, ensure the `gemini` CLI is installed and available in your PATH.
|
|
526
|
+
|
|
527
|
+
**Note**: The same configuration interface works across all providers thanks to LangChain's `initChatModel` abstraction and OpenCode Zen integration.
|
|
528
|
+
|
|
529
|
+
## Error Handling
|
|
530
|
+
|
|
531
|
+
- **Fatal Errors**: CLI exits with appropriate error codes
|
|
532
|
+
- **Repository Issues**: Clear error messages for missing or inaccessible repositories
|
|
533
|
+
- **LLM Errors**: Graceful handling of API failures and rate limits
|
|
534
|
+
- **Configuration Errors**: Validation errors with helpful guidance
|
|
535
|
+
|
|
536
|
+
## Development
|
|
537
|
+
|
|
538
|
+
### Project Setup
|
|
539
|
+
|
|
540
|
+
```bash
|
|
541
|
+
# Clone the repository
|
|
542
|
+
git clone https://github.com/SkrOYC/librarian.git
|
|
543
|
+
cd librarian
|
|
544
|
+
|
|
545
|
+
# Install dependencies with Bun (recommended)
|
|
546
|
+
bun install
|
|
547
|
+
|
|
548
|
+
# OR install dependencies with npm
|
|
549
|
+
npm install
|
|
550
|
+
|
|
551
|
+
# Build the project with Bun
|
|
552
|
+
bun run build
|
|
553
|
+
|
|
554
|
+
# OR build with npm
|
|
555
|
+
npm run build
|
|
556
|
+
|
|
557
|
+
# Run tests with Bun
|
|
558
|
+
bun run test
|
|
559
|
+
|
|
560
|
+
# OR run tests with npm
|
|
561
|
+
npm run test
|
|
562
|
+
```
|
|
563
|
+
|
|
564
|
+
### NPM Publishing
|
|
565
|
+
|
|
566
|
+
```bash
|
|
567
|
+
# Login to npm (if not already logged in)
|
|
568
|
+
npm login
|
|
569
|
+
|
|
570
|
+
# Dry run to verify package contents
|
|
571
|
+
npm pack --dry-run
|
|
572
|
+
|
|
573
|
+
# Publish to npm
|
|
574
|
+
npm publish
|
|
575
|
+
|
|
576
|
+
# Publish with specific tag (e.g., beta, next)
|
|
577
|
+
npm publish --tag beta
|
|
578
|
+
```
|
|
579
|
+
|
|
580
|
+
### Dependencies
|
|
581
|
+
|
|
582
|
+
#### Core
|
|
583
|
+
|
|
584
|
+
- `commander`: CLI argument parsing
|
|
585
|
+
- `yaml`: Configuration file parsing
|
|
586
|
+
- `isomorphic-git`: Git operations
|
|
587
|
+
- `zod`: Runtime validation
|
|
588
|
+
|
|
589
|
+
#### Agent System
|
|
590
|
+
|
|
591
|
+
- `langchain`: Core LangChain framework (createAgent, initChatModel, tool)
|
|
592
|
+
- `@langchain/langgraph`: Memory management with MemorySaver
|
|
593
|
+
- `@langchain/openai`: OpenAI provider integration
|
|
594
|
+
- `@langchain/anthropic`: Anthropic provider integration
|
|
595
|
+
- `@langchain/google-genai`: Google provider integration
|
|
596
|
+
- `zod`: Tool schema validation and structured responses
|
|
597
|
+
|
|
598
|
+
## Contributing
|
|
599
|
+
|
|
600
|
+
1. Fork the repository
|
|
601
|
+
2. Create a feature branch
|
|
602
|
+
3. Make your changes
|
|
603
|
+
4. Add tests for new functionality
|
|
604
|
+
5. Submit a pull request
|
|
605
|
+
|
|
606
|
+
## License
|
|
607
|
+
|
|
608
|
+
Apache 2.0
|
|
609
|
+
|
|
610
|
+
## Support
|
|
611
|
+
|
|
612
|
+
For support and questions:
|
|
613
|
+
|
|
614
|
+
- Create an issue on GitHub
|
package/biome.jsonc
ADDED
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
import { z } from 'zod';
|
|
2
|
+
export declare const contextSchema: z.ZodObject<{
|
|
3
|
+
workingDir: z.ZodString;
|
|
4
|
+
environment: z.ZodOptional<z.ZodString>;
|
|
5
|
+
group: z.ZodString;
|
|
6
|
+
technology: z.ZodString;
|
|
7
|
+
}, z.core.$strip>;
|
|
8
|
+
export type Context = z.infer<typeof contextSchema>;
|
|
9
|
+
export interface AgentContext {
|
|
10
|
+
workingDir: string;
|
|
11
|
+
environment?: string;
|
|
12
|
+
group: string;
|
|
13
|
+
technology: string;
|
|
14
|
+
}
|
|
15
|
+
export type { AgentContext as AgentContextType };
|
|
16
|
+
export declare function createContext(workingDir: string, group: string, technology: string, environment?: string): Context;
|
|
17
|
+
//# sourceMappingURL=context-schema.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"context-schema.d.ts","sourceRoot":"","sources":["../../src/agents/context-schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAQxB,eAAO,MAAM,aAAa;;;;;iBASxB,CAAC;AAMH,MAAM,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAMpD,MAAM,WAAW,YAAY;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;CACpB;AAGD,YAAY,EAAE,YAAY,IAAI,gBAAgB,EAAE,CAAC;AAWjD,wBAAgB,aAAa,CAC3B,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,MAAM,EAClB,WAAW,CAAC,EAAE,MAAM,GACnB,OAAO,CAOT"}
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
import { z } from 'zod';
|
|
2
|
+
export const contextSchema = z.object({
|
|
3
|
+
workingDir: z.string().describe("The absolute path to sandbox directory"),
|
|
4
|
+
environment: z.string().optional().describe("Optional environment identifier"),
|
|
5
|
+
group: z.string().describe("The technology group name"),
|
|
6
|
+
technology: z.string().describe("The technology/repo name"),
|
|
7
|
+
});
|
|
8
|
+
export function createContext(workingDir, group, technology, environment) {
|
|
9
|
+
return contextSchema.parse({
|
|
10
|
+
workingDir,
|
|
11
|
+
group,
|
|
12
|
+
technology,
|
|
13
|
+
environment,
|
|
14
|
+
});
|
|
15
|
+
}
|
|
16
|
+
//# sourceMappingURL=context-schema.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"context-schema.js","sourceRoot":"","sources":["../../src/agents/context-schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAQxB,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,CAAC,MAAM,CAAC;IAEpC,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,wCAAwC,CAAC;IAEzE,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,iCAAiC,CAAC;IAE9E,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,2BAA2B,CAAC;IAEvD,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,0BAA0B,CAAC;CAC5D,CAAC,CAAC;AA+BH,MAAM,UAAU,aAAa,CAC3B,UAAkB,EAClB,KAAa,EACb,UAAkB,EAClB,WAAoB;IAEpB,OAAO,aAAa,CAAC,KAAK,CAAC;QACzB,UAAU;QACV,KAAK;QACL,UAAU;QACV,WAAW;KACZ,CAAC,CAAC;AACL,CAAC"}
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
import type { z } from "zod";
|
|
2
|
+
import type { AgentContext } from "./context-schema.js";
|
|
3
|
+
export interface ReactAgentConfig {
|
|
4
|
+
aiProvider: {
|
|
5
|
+
type: "openai" | "anthropic" | "google" | "openai-compatible" | "anthropic-compatible" | "claude-code" | "gemini-cli";
|
|
6
|
+
apiKey: string;
|
|
7
|
+
model?: string;
|
|
8
|
+
baseURL?: string;
|
|
9
|
+
};
|
|
10
|
+
workingDir: string;
|
|
11
|
+
technology?: {
|
|
12
|
+
name: string;
|
|
13
|
+
repository: string;
|
|
14
|
+
branch: string;
|
|
15
|
+
};
|
|
16
|
+
contextSchema?: z.ZodType | undefined;
|
|
17
|
+
}
|
|
18
|
+
export declare class ReactAgent {
|
|
19
|
+
private readonly aiModel?;
|
|
20
|
+
private readonly tools;
|
|
21
|
+
private agent?;
|
|
22
|
+
private readonly config;
|
|
23
|
+
private readonly contextSchema?;
|
|
24
|
+
constructor(config: ReactAgentConfig);
|
|
25
|
+
createDynamicSystemPrompt(): string;
|
|
26
|
+
private createGeminiTempDir;
|
|
27
|
+
private setupGeminiConfig;
|
|
28
|
+
private buildGeminiEnv;
|
|
29
|
+
private cleanupGeminiTempDir;
|
|
30
|
+
private streamClaudeCli;
|
|
31
|
+
private streamGeminiCli;
|
|
32
|
+
private parseGeminiStreamLine;
|
|
33
|
+
private createAIModel;
|
|
34
|
+
initialize(): Promise<void>;
|
|
35
|
+
queryRepository(_repoPath: string, query: string, context?: AgentContext): Promise<string>;
|
|
36
|
+
streamRepository(_repoPath: string, query: string, context?: AgentContext): AsyncGenerator<string, void, unknown>;
|
|
37
|
+
}
|
|
38
|
+
//# sourceMappingURL=react-agent.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"react-agent.d.ts","sourceRoot":"","sources":["../../src/agents/react-agent.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAe7B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAKxD,MAAM,WAAW,gBAAgB;IAEhC,UAAU,EAAE;QACX,IAAI,EACD,QAAQ,GACR,WAAW,GACX,QAAQ,GACR,mBAAmB,GACnB,sBAAsB,GACtB,aAAa,GACb,YAAY,CAAC;QAChB,MAAM,EAAE,MAAM,CAAC;QACf,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,OAAO,CAAC,EAAE,MAAM,CAAC;KACjB,CAAC;IAEF,UAAU,EAAE,MAAM,CAAC;IAEnB,UAAU,CAAC,EAAE;QACZ,IAAI,EAAE,MAAM,CAAC;QACb,UAAU,EAAE,MAAM,CAAC;QACnB,MAAM,EAAE,MAAM,CAAC;KACf,CAAC;IAEF,aAAa,CAAC,EAAE,CAAC,CAAC,OAAO,GAAG,SAAS,CAAC;CACtC;AAED,qBAAa,UAAU;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAsD;IAC/E,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA0B;IAChD,OAAO,CAAC,KAAK,CAAC,CAAiC;IAC/C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAmB;IAC1C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAwB;gBAE3C,MAAM,EAAE,gBAAgB;IA2BpC,yBAAyB,IAAI,MAAM;YAmSrB,mBAAmB;YAMnB,iBAAiB;IA+B/B,OAAO,CAAC,cAAc;YAaR,oBAAoB;YAUnB,eAAe;YAqFf,eAAe;IA2E9B,OAAO,CAAC,qBAAqB;IAU7B,OAAO,CAAC,aAAa;IA8DrB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IA8CrB,eAAe,CACpB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,YAAY,GACpB,OAAO,CAAC,MAAM,CAAC;IAwEX,gBAAgB,CACtB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,YAAY,GACpB,cAAc,CAAC,MAAM,EAAE,IAAI,EAAE,OAAO,CAAC;CAqExC"}
|