Skip to content

Commit 690ab1e

Browse files
AstraBertAstraBert
authored
Merge pull request #10 from run-llama/clelia/readme-and-co
docs: readme
2 parents 6b92df8 + aab1e32 commit 690ab1e

File tree

5 files changed

+120
-3
lines changed

5 files changed

+120
-3
lines changed

‎.gitignore‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,4 +11,5 @@ wheels/
1111
.env
1212

1313
# Caches
14-
*cache/
14+
*cache/
15+
workflows.db

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
The MIT License
2+
3+
Copyright (c) LlamaIndex
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in
13+
all copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
21+
THE SOFTWARE.

‎README.md‎

Lines changed: 93 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,95 @@
11
# Study-Llama
22

3-
LlamaAgents demo with LlamaClassify and LlamaExtract to categorize study notes, extract information from them and perform some basic retrieval (with metadata filtering) over the extracted info.
3+
Study-Llama is a demo application for organizing, extracting, and searching study notes using LlamaAgents, LlamaClassify, and LlamaExtract. It features a Go-based web frontend and a Python backend for advanced note processing.
4+
5+
## Overview
6+
7+
- **Frontend (Go):**
8+
Serves the web interface, handles user authentication, file uploads, and search requests. Renders pages using HTML templates and manages static assets.
9+
- **Backend (Python):**
10+
Provides APIs for classifying notes, extracting information, storing/retrieving data, and performing metadata-filtered vector searches. Handles database operations and vector search.
11+
12+
## How It Works
13+
14+
1. **User Interaction:**
15+
Users access the web UI to sign in, create categories for their study notes, upload notes, and search among them.
16+
17+
2. **Frontend-to-Backend Communication:**
18+
The Go server receives requests from the UI and communicates with the Python backend via HTTP API calls.
19+
- For example, when a user uploads a note, the frontend sends the file and metadata to the backend for processing.
20+
- Search queries are also forwarded to the python backend for vector search.
21+
22+
3. **Backend Processing:**
23+
The Python backend (deployed on LlamaCloud as a LlamaAgent) handles:
24+
- **Classification & Extraction:**
25+
Uses workflows in `classify_and_extract/workflow.py` to classify notes (with LlamaClassify) and extract structured information (with LlamaExtract).
26+
- **Database Operations:**
27+
- **Files:**
28+
Uploaded files and their metadata (name, category, owner) are stored.
29+
- **Classification Rules:**
30+
Custom rules for categorizing notes are stored and retrieved from the database.
31+
- **Vector Search:**
32+
Extracted summaries and FAQs are indexed for semantic search and retrieval.
33+
34+
## Features
35+
36+
- Upload and categorize study notes.
37+
- Extract structured information from notes.
38+
- Search notes with metadata filters.
39+
- User authentication and access control.
40+
- Modern web UI with Go templates.
41+
42+
## Project Structure
43+
44+
- **frontend/**
45+
- `main.go`: Web server entry point.
46+
- `handlers/`: HTTP request handlers.
47+
- `auth/`, `files/`, `rules/`: Business logic and DB operations.
48+
- `static/`: Images and assets.
49+
- `templates/`: HTML templates.
50+
- **src/**
51+
- `study_llama/`: Python backend modules for classification, extraction, search, and database logic.
52+
53+
## Set Up
54+
55+
**Clone this repository:**
56+
57+
```bash
58+
git clone https://github.com/run-llama/study-llama
59+
cd /study-llama
60+
```
61+
62+
**Deploy the LlamaAgent:**
63+
64+
In order for the classify-extract and vector search agent workflows to receive and process queries, they needs to be deployed to the cloud (or at least accessible through a public endpoint). The easiest way to do so is to use [`llamactl`](https://developers.llamaindex.ai/python/llamaagents/llamactl/getting-started/) and deploy the agent workflow as a [LlamaAgent](https://developers.llamaindex.ai/python/llamaagents/overview/):
65+
66+
```bash
67+
uv tool install -U llamactl
68+
llamactl auth # authenticate
69+
llamactl deployments create # create a deployment from the current repository
70+
```
71+
72+
In order for the LlamaAgent to work, you will need the following environment variables in a `.env` file (`llamactl` manages environments autonomously):
73+
74+
- `OPENAI_API_KEY` to interact with GPT-4.1 for email generation
75+
- `LLAMA_CLOUD_API_KEY` and `LLAMA_CLOUD_PROJECT_ID` to get predictions from LlamaClassify and LlamaExtract
76+
- `POSTGRES_CONNECTION_STRING` to connect to the Postgres database with the uploaded files and the classification rules (you can use [Neon](https://neon.com), [Supabase](https://supabase.com), [Prisma](https://prisma.io) or a self-hosted Postgres instance)
77+
- `QDRANT_API_KEY` and `QDRANT_HOST`, to upload sumamries and question/answers to perform vector search and retrieval (you can use [Qdrant Cloud](https://qdrant.tech) or a self-hosted Qdrant instance).
78+
79+
**Deploy the frontend**
80+
81+
Once the agent is deployed, build the Docker image for the frontend (needed to interact with the LlamaAgents we just created), and deploy it through services like [Dokploy](https://dokploy.com) or [Coolify](https://coolify.io).
82+
83+
```bash
84+
docker build . -t your-username/study-llama:prod
85+
# docker login ghcr.io # (uncomment if you wish to use the GitHub container registry)
86+
docker push your-username/study-llama:prod
87+
```
88+
89+
The frontend service uses a few env variables:
90+
91+
- `LLAMA_CLOUD_API_KEY`, `FILES_API_ENDPOINT` (which will presumably be `https://api.cloud.llamaindex.ai/deployments/study-llama/workflows/classify-and-extract/run`) and `SEARCH_API_ENDPOINT` (which will presumably be `https://api.cloud.llamaindex.ai/deployments/study-llama/workflows/search/run`), the API key and the API endpoints to interact with your deployed LlamaAgent
92+
- `POSTGRES_CONNECTION_STRING` to connect to the Postgres database with the uploaded files, the classification rules and the user auth (you can use [Neon](https://neon.com), [Supabase](https://supabase.com), [Prisma](https://prisma.io) or a self-hosted Postgres instance, but it has to be the **same as for the LlamaAgent**)
93+
- `CACHE_TABLE` and `RATE_LIMITING_TABLE`, the table names for the SQLite database taking care of caching and rate limiting.
94+
95+
Services like Dokploy or Coolify offer you to set these environment variables through their own environment management interfaces.

‎frontend/Makefile‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -33,4 +33,7 @@ build-fe: install-deps-fe
3333
GOARCH=arm64 GOOS=darwin go build -o ${BIN}/${BIN_NAME}-darwin-arm64 ${MAIN_PKG}
3434

3535
clean-build-fe:
36-
@rm -rf ${BIN}
36+
@rm -rf ${BIN}
37+
38+
run-fe:
39+
go run main.go

‎workflows.db‎

-12 KB
Binary file not shown.

0 commit comments

Comments
 (0)