Getting Started¶
In order to get the aiagent systems running properly, you’ll need to setup some configuration options such as 3rd party api keys, urls, names, etc.
There are 3 ways you can run this project out of the box. Check out the prerequisites for each of them on our details page.
Installation¶
Clone the aiAgent repo into a local folder:
git clone https://gitlab.com/kusog-opensource/aiagent.git
cd aiagent
The project comes with 2 docker files which are used to create docker images, one for the web service and another for the message queue listener. You will need to have docker desktop installed to use that.
When you start the container environment, 7 containers will start under a grouping named aiagent:
service - The main service interface exposing endpoints for aiAgent
smnet-worker-1 - A scalable worker service that listens to work queue to process embedding tasks
elasticsearch - Used as a vector database for content embeddings
postgres - Used for the document storage directory and semantic network relationships
rabbitmq - Used to manage work queues between the service and the smnet-worker
mongodb - Not used by aiAgent but it used by log analysis tool in extended functionality of separate repo. It is safe to stop this container while using the base aiAgent project.
kibana - A web interface to the elastsearch instance. This is a good way to explore the vector database and do basic tasks like delete indexes, etc.
Note that the elasticsearch, postgres, mongodb, rabbitmq and kibana all expose ports that map the standard ports those service use into your local environment. The ports do not need to be exposed locally for aiAgent to work, but you wont be able to use management tools locally to manage the databases such as kibana and pgAdmin.
You can edit the docker-compose.yml file to remove the port mapping to local ports.
You should leave the port open to the aiAgent service so client apps can communicate with it.
Container Data Storage¶
The database containers in the project like postgres, mongodb and elasticsearch are setup to store
their data files directly in a writable layer of the container image. If you execute the
docker-compose down command you will completely remove the image from docker and you will
loose all the data stored there from adding documents. If you want to use this
im production you’ll need to use a writable layer that is more durable or more likely,
use managed services such as AWS OpenSearch, DocumentDb, and Aurora.
Security Considerations¶
The code base as is has no security within it, and is not ready for deployment into a production environment. All users and endpoints can be called anonymously. Obviously that isn’t going to be a good choice for production. Rather than overlay a specific approach to security, aiAgent expects to be used within a production server that has a larger security mechanism in place managing the aiAgent endpoints as well. For example, using AWS API Gateway and AWS Cognito as one example.
Setup your environment file¶
There are sensitive keys and options needed to properly run the apps. The environments folder contains a .env.example file. Do the following:
cp .env.example dev.env
cp .env.example prod.env
Edit the dev.env and prod.env files that should be sitting in the environments folder. When running the containers
the prod.env is used. When running the service directly on local device, dev.env is used
OPENAI_API_KEY=Get your OpenAI Key at https://openai.com
SERPAPI_API_KEY=Optional - Get your serp api key at https://serp.com
AGENT_LOCAL_DEV=True in dev.env - False in prod.env
Note that you do not need to get a serp.com api key unless you want to use aiagent to use data from the internet for user queries.
Setup config¶
Optional - Setup your makefile¶
The makefile has 3 variables at the top which you need to set if you’re going to use the aws cdk deployment feature. You only need to do this if you have an aws account and want to deploy a kubernetes cluster for this service into a new VPC.
awsProfile =--profile [profilename]
awsAccount =[accountnumber]
awsRegion =[deployregion]
Local docker environment¶
To build new docker images
make build
To start the aiAgent docker environment to have a full system up and running on your local machine
make start
To stop the aiAgent docker environment
make stop
To run and debug the cli or web service directly on your developer machine¶
make install
Non container local execution¶
The project comes with a vscode-example folder which includes a launch.json and a tasks.json you can use to debug the cli, web service or queue listener.
Testing Your Installation¶
When running the container environment, you can use a tool like postman or curl to query and upload content through the server.
Run a query before uploading any content:
curl -v http://127.0.0.1:5005/mdelmont/query/has%20mark%20delmont%20ever%20been%20scuba%20diving%3F
You should get a response about not knowing about Mark Delmont.
Upload a document:
curl -F files="@./testdocs/Mark Delmont reflections on scuba diving with son.txt" \
http://localhost:5005/mdelmont/storage/basememory/
And run the same query again:
curl -v http://127.0.0.1:5005/mdelmont/query/has%20mark%20delmont%20ever%20been%20scuba%20diving%3F
You should not get a paragraph outlining how Mark has been scuba diving with a summary about the experience.