Skip to content

Commit 612ffe3

Browse files
clemaitoroclemaitoro
committed
feat: add files/docs generated by AIx SDLC
1 parent 435e3a2 commit 612ffe3

File tree

104 files changed

+27273
-0
lines changed

Some content is hidden

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

104 files changed

+27273
-0
lines changed

‎.cg-aix-sdlc/ai-context/README.md‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
# LangBuilder - AI Context Documentation
2+
3+
This directory contains AI-optimized context files for coding assistants working with the LangBuilder codebase.
4+
5+
## Quick Start
6+
7+
**New to the codebase?** Start with these files in order:
8+
9+
1. **[codebase-primer.md](./codebase-primer.md)** - Project overview and navigation guide
10+
2. **[architecture-summary.md](./architecture-summary.md)** - System architecture and patterns
11+
3. **[context-bundle.md](./context-bundle.md)** - All-in-one compact reference
12+
13+
## File Index
14+
15+
| File | Purpose | Best For |
16+
|------|---------|----------|
17+
| [codebase-primer.md](./codebase-primer.md) | Project structure and entry points | First-time orientation |
18+
| [architecture-summary.md](./architecture-summary.md) | System layers and patterns | Understanding design |
19+
| [api-quick-reference.md](./api-quick-reference.md) | REST API endpoints | API development |
20+
| [database-quick-reference.md](./database-quick-reference.md) | SQLModel schemas and queries | Database work |
21+
| [patterns-and-conventions.md](./patterns-and-conventions.md) | Code style and patterns | Writing new code |
22+
| [common-tasks.md](./common-tasks.md) | Step-by-step how-tos | Feature development |
23+
| [troubleshooting.md](./troubleshooting.md) | Error solutions | Debugging issues |
24+
| [context-bundle.md](./context-bundle.md) | Compact all-in-one | Token-limited contexts |
25+
26+
## Usage for AI Assistants
27+
28+
### Claude Code / Cursor
29+
Include relevant files via `@` mentions:
30+
```
31+
@codebase-primer.md How do I add a new component?
32+
```
33+
34+
### GitHub Copilot
35+
Reference files in comments:
36+
```python
37+
# See .cg-aix-sdlc/ai-context/patterns-and-conventions.md
38+
class MyComponent(LCModelComponent):
39+
...
40+
```
41+
42+
### ChatGPT / Claude Web
43+
Copy content from `context-bundle.md` into conversation.
44+
45+
## Key Information
46+
47+
### Project Stats
48+
- **Version**: 1.6.5
49+
- **Python**: 3.10 - 3.14
50+
- **Components**: 455+
51+
- **LLM Providers**: 24
52+
- **Vector Stores**: 19
53+
54+
### Technology Stack
55+
| Layer | Technology |
56+
|-------|------------|
57+
| Backend | FastAPI, LangChain 0.3.x |
58+
| Frontend | React 18, TypeScript 5.4 |
59+
| Database | SQLModel + Alembic |
60+
| Canvas | @xyflow/react |
61+
| State | Zustand |
62+
63+
### Key Paths
64+
```
65+
langbuilder/src/backend/base/langbuilder/
66+
├── api/ # FastAPI routes
67+
├── components/ # AI components
68+
├── graph/ # Execution engine
69+
└── services/ # Business logic
70+
71+
langbuilder/src/frontend/src/
72+
├── stores/ # Zustand stores
73+
├── pages/ # React pages
74+
└── CustomNodes/ # Flow canvas
75+
```
76+
77+
## Updating These Files
78+
79+
When making significant changes to the codebase:
80+
81+
1. Update relevant context files to reflect changes
82+
2. Keep `context-bundle.md` under ~2000 tokens
83+
3. Ensure code examples match current implementation
84+
4. Update version numbers when releasing
85+
86+
## Generated By
87+
88+
CloudGeometry AIx SDLC Documentation System
89+
90+
---
91+
*Last updated: 2026-01-21*

‎.cg-aix-sdlc/ai-context/api-quick-reference.md‎

Lines changed: 189 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,189 @@
1+
# LangBuilder - API Quick Reference
2+
3+
## Base URLs
4+
- API v1: `/api/v1`
5+
- API v2: `/api/v2`
6+
- OpenAI Compatible: `/v1`
7+
- Health: `/health`
8+
9+
## Authentication
10+
11+
### Login
12+
```http
13+
POST /api/v1/login
14+
Content-Type: application/x-www-form-urlencoded
15+
16+
username=user&password=pass
17+
```
18+
19+
Response sets cookies: `access_token_lf`, `refresh_token_lf`
20+
21+
### Using API Key
22+
```http
23+
GET /api/v1/flows
24+
x-api-key: lb-xxxxxxxx
25+
```
26+
27+
## Core Endpoints
28+
29+
### Flows (CRUD)
30+
```http
31+
# List flows
32+
GET /api/v1/flows
33+
GET /api/v1/flows?folder_id={uuid}&header_flows=true
34+
35+
# Get single flow
36+
GET /api/v1/flows/{flow_id}
37+
38+
# Create flow
39+
POST /api/v1/flows
40+
Content-Type: application/json
41+
{"name": "My Flow", "data": {"nodes": [], "edges": []}}
42+
43+
# Update flow
44+
PATCH /api/v1/flows/{flow_id}
45+
{"name": "Updated Name", "data": {...}}
46+
47+
# Delete flow
48+
DELETE /api/v1/flows/{flow_id}
49+
50+
# Batch operations
51+
POST /api/v1/flows/batch/
52+
POST /api/v1/flows/upload/ (multipart/form-data)
53+
DELETE /api/v1/flows?flow_ids=[uuid1,uuid2]
54+
```
55+
56+
### Build/Chat
57+
```http
58+
# Start build (returns SSE stream)
59+
POST /api/v1/build/{flow_id}/flow
60+
Content-Type: application/json
61+
{"inputs": {"input_value": "Hello"}}
62+
63+
# Stream events
64+
GET /api/v1/build/{flow_id}/events
65+
66+
# Cancel build
67+
POST /api/v1/build/{flow_id}/cancel
68+
```
69+
70+
### Run Endpoint
71+
```http
72+
# Execute flow via endpoint name
73+
POST /api/v1/run/{endpoint_name}
74+
{"input_value": "query", "tweaks": {}}
75+
76+
# Webhook trigger
77+
POST /api/v1/webhook/{flow_id}
78+
```
79+
80+
### Files
81+
```http
82+
# Upload file
83+
POST /api/v1/files/upload/{flow_id}
84+
Content-Type: multipart/form-data
85+
86+
# List files
87+
GET /api/v1/files/{flow_id}
88+
89+
# Download file
90+
GET /api/v1/files/download/{file_id}
91+
```
92+
93+
### Folders
94+
```http
95+
GET /api/v1/folders/
96+
POST /api/v1/folders/
97+
PATCH /api/v1/folders/{folder_id}
98+
DELETE /api/v1/folders/{folder_id}
99+
```
100+
101+
### Users
102+
```http
103+
GET /api/v1/users/whoami
104+
PATCH /api/v1/users/{user_id}
105+
```
106+
107+
### Variables (Credentials)
108+
```http
109+
GET /api/v1/variables/
110+
POST /api/v1/variables/
111+
DELETE /api/v1/variables/{variable_id}
112+
```
113+
114+
## V2 Endpoints
115+
116+
### Files (Enhanced)
117+
```http
118+
GET /api/v2/files/
119+
POST /api/v2/files/
120+
DELETE /api/v2/files/{file_id}
121+
```
122+
123+
### MCP Servers
124+
```http
125+
GET /api/v2/mcp/servers
126+
```
127+
128+
## OpenAI Compatible
129+
```http
130+
# List models
131+
GET /v1/models
132+
133+
# Chat completions (pass flow_id as model)
134+
POST /v1/chat/completions
135+
{
136+
"model": "{flow_id}",
137+
"messages": [{"role": "user", "content": "Hello"}],
138+
"stream": true
139+
}
140+
```
141+
142+
## Response Formats
143+
144+
### Success
145+
```json
146+
{"id": "uuid", "name": "Flow Name", ...}
147+
```
148+
149+
### Paginated
150+
```json
151+
{
152+
"items": [...],
153+
"total": 100,
154+
"page": 1,
155+
"page_size": 20,
156+
"pages": 5
157+
}
158+
```
159+
160+
### Error
161+
```json
162+
{
163+
"detail": "Error message"
164+
}
165+
```
166+
167+
### SSE Stream (Build Events)
168+
```
169+
data: {"event": "vertices_sorted", "data": {...}}
170+
data: {"event": "build_start", "data": {...}}
171+
data: {"event": "end_vertex", "data": {...}}
172+
data: {"event": "end", "data": {...}}
173+
```
174+
175+
## Common HTTP Status Codes
176+
- `200`: Success
177+
- `201`: Created
178+
- `400`: Bad Request (validation error)
179+
- `401`: Unauthorized
180+
- `403`: Forbidden
181+
- `404`: Not Found
182+
- `422`: Unprocessable Entity
183+
- `500`: Internal Server Error
184+
185+
## Rate Limiting
186+
Not enforced by default. Configure via reverse proxy (Traefik/Nginx).
187+
188+
---
189+
*AI Context Document - CloudGeometry AIx SDLC*

‎.cg-aix-sdlc/ai-context/architecture-summary.md‎

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
# LangBuilder - Architecture Summary
2+
3+
## System Layers
4+
5+
```
6+
┌─────────────────────────────────────────────────────────────┐
7+
│ Frontend (React) │
8+
│ Flow Canvas (XYFlow) → Zustand Stores → API Client │
9+
├─────────────────────────────────────────────────────────────┤
10+
│ API Layer (FastAPI) │
11+
│ v1 Routers (18) │ v2 Routers (2) │ OpenAI Compat Router │
12+
├─────────────────────────────────────────────────────────────┤
13+
│ Services Layer │
14+
│ Auth │ Flow │ Chat │ Database │ Cache │ Storage │
15+
├─────────────────────────────────────────────────────────────┤
16+
│ Graph Engine │
17+
│ Vertex → Edge → Topological Sort → Parallel Execution │
18+
├─────────────────────────────────────────────────────────────┤
19+
│ Component Registry │
20+
│ 455+ Components: LLMs │ Embeddings │ VectorStores │ Tools │
21+
├─────────────────────────────────────────────────────────────┤
22+
│ Data Layer │
23+
│ SQLModel ORM → Alembic Migrations → SQLite/PostgreSQL │
24+
└─────────────────────────────────────────────────────────────┘
25+
```
26+
27+
## Data Flow
28+
29+
```
30+
User Action (Frontend)
31+
↓
32+
API Request (FastAPI Router)
33+
↓
34+
Service Layer (Business Logic)
35+
↓
36+
Graph Engine (for Flow execution)
37+
↓
38+
Component Execution (LangChain)
39+
↓
40+
Database/Cache Operations
41+
↓
42+
Response (JSON/SSE Stream)
43+
```
44+
45+
## Key Patterns
46+
47+
### 1. Component Pattern
48+
Components are declarative Python classes with inputs/outputs that generate UI automatically:
49+
50+
```python
51+
class OpenAIModelComponent(LCModelComponent):
52+
display_name = "OpenAI"
53+
inputs = [
54+
SecretStrInput(name="api_key", ...),
55+
DropdownInput(name="model_name", ...),
56+
]
57+
58+
def build_model(self) -> LanguageModel:
59+
return ChatOpenAI(...)
60+
```
61+
62+
### 2. Graph Execution
63+
Workflows are DAGs executed with topological sorting:
64+
- Vertices execute in parallel when independent
65+
- Results propagate through edges
66+
- State is tracked per-vertex for debugging
67+
68+
### 3. Service Factory
69+
Services are injected via FastAPI dependencies:
70+
71+
```python
72+
async def get_flow_service(
73+
session: AsyncSession = Depends(get_session)
74+
) -> FlowService:
75+
return FlowService(session)
76+
```
77+
78+
### 4. Zustand Stores (Frontend)
79+
State management with minimal boilerplate:
80+
81+
```typescript
82+
const useFlowStore = create<FlowStoreType>((set, get) => ({
83+
nodes: [],
84+
edges: [],
85+
addNode: (node) => set((state) => ({ nodes: [...state.nodes, node] })),
86+
}));
87+
```
88+
89+
## Important Modules
90+
91+
| Module | Purpose | Location |
92+
|--------|---------|----------|
93+
| `api/router.py` | Route registration | `backend/base/langbuilder/api/` |
94+
| `graph/graph/base.py` | Graph execution engine | `backend/base/langbuilder/graph/` |
95+
| `services/database/` | DB models & CRUD | `backend/base/langbuilder/services/` |
96+
| `components/` | All AI components | `backend/base/langbuilder/components/` |
97+
| `flowStore.ts` | Flow state management | `frontend/src/stores/` |
98+
99+
## Integration Points
100+
101+
### LLM Providers (24)
102+
OpenAI, Anthropic, Google, Azure, AWS Bedrock, Ollama, Groq, etc.
103+
104+
### Vector Stores (19)
105+
Chroma, Pinecone, Qdrant, PGVector, Milvus, FAISS, etc.
106+
107+
### External Tools
108+
MCP Protocol, Jira, Confluence, HubSpot, Salesforce, etc.
109+
110+
## Authentication
111+
- JWT tokens (access + refresh)
112+
- Cookie-based sessions
113+
- Auto-login mode for development
114+
- API key authentication for endpoints
115+
116+
---
117+
*AI Context Document - CloudGeometry AIx SDLC*

0 commit comments

Comments
 (0)