issue #12 - Adapter documentation, README file

README.md

@@ -20,7 +20,8 @@ pip install -r requirements.txt
 
 ### Use as a library
 
-Use this URL to add this project as a dependency:
+Use this URL to add this project as a dependency (NOTE - TODO: update instructions for ForgeJo repo after pulp repo is up & running for python artifacts)
+
 
 ```
 git+https://git.cleverthis.com/cleverthis/clevermicro/amq-adapter-python.git@develop#egg=amq_adapter
@@ -50,8 +51,50 @@ build the distributable archive (will be located in `./dist` directory)
 `python -m build --wheel`
 
 
-# TODO: how to use?
+# Integrating with actual CleverThis Service
+
+The following steps are required to integrate with the CleverThis service. This example uses ClverSwarm as specific use case,
+other python-based services would follow identical pattern.
+
+## Prerequisites
+IMPORTANT: AMQ Adapter relies on the service to use FastAPI to implement its REST endpoints
+and that those endpoints are properly annotated with FastAPI annotations.
+AMQ Adapter will look for these annotations to recognize the service API entry points and
+will automatically use the annotation to map the actual function to the incoming request the very same way FastAPI does.
+
+
+1. **Install the amq-adapter library**, as indicated above
+2. **Ensure the needed dependencies were installed** together with the amq-adapter. This is the list of dependencies:
 ```
+aiohttp~=3.11.11
+fastapi==0.115.6
+aio_pika~=9.5.5
+opentelemetry-api
+opentelemetry-sdk
+opentelemetry-exporter-otlp
+opentelemetry-exporter-prometheus
+opentelemetry-instrumentation-pika
+python_multipart
+```
+
+Go to amq-dapter-python repo source code, and copy the service specific directory, e.g. `<git-root>/cleverswarm`
+directory to your service's sources. For the CleverSwarm service, the file is `cleverswarm/clever_swarm.py`, 
+and contains the AMQ Adapter to CleverSwarm service custom facade, implemented as
+```python
+class CleverSwarmAmqpAdapter(CleverThisServiceAdapter):
+```
+
+to instatiate and initialize the AMQ adapter, add following line to the init routine of the CleverThis service:
+```python
+    adapter = CleverSwarmAmqpAdapter(AMQConfiguration("./application.properties.local"))
+```
+and ensure that the `adapter` stays in the context of the service, so it is not garbage collected.
+
+At version 0.2.21, AMQ Adapter uses local configuration file, relative path to which is passed 
+to the AMQConfiguration constructor. This may change in the future, when the central configuration service
+will become available in CleverMicro, but for now please ensure correct relative path wrt the current working directory.
+
+For the config entries, please refer to the wiki page:  [AMQ Adapter Config](https://docs.cleverthis.com/en/architecture/microservices/amq-adapter-configuration)
 ```
 ## Donating