monocle-apptrace 0.0.1__tar.gz

monocle_apptrace-0.0.1/.gitignore

@@ -0,0 +1,15 @@
+# Python
+*~
+*.log
+*.pyc
+*.pyo
+*.pyt
+*.pytc
+*.egg-info
+.*.swp
+storage
+traces.txt
+dist
+.tox
+.DS_Store
+Pipfile**

monocle_apptrace-0.0.1/CODEOWNERS.md

@@ -0,0 +1,10 @@
+#MAINTAINERS
+Following is the current list of maintainers on this project
+
+The maintainers are listed in alphabetical order.
+
+- [@prasad-okahu] (https://github.com/prasad-okahu) (Prasad Mujumdar)
+- [@oi-raanne] (https://github.com/oi-raanne) (Ravi Anne)
+- [@akshay-okahu](https://github.com/akshay-okahu) (Akshay Yadav)
+- [@anshul7665] (https://github.com/anshul7665) (Anshul Sharma)
+- [@kshitiz-okahu] (https://github.com/kshitiz-okahu) (Kshitiz Vijayvargiya)

monocle_apptrace-0.0.1/CODE_OF_CONDUCT.md

@@ -0,0 +1,3 @@
+# Monocle Code of Conduct
+
+In the interest of fostering an open and welcoming environment, we as contributors and maintainers agree to abide by the Code of Conduct available at https://lfprojects.org/policies/code-of-conduct/

monocle_apptrace-0.0.1/CONTRIBUTING.md

@@ -0,0 +1,28 @@
+# Contributing to Monocle
+Contributions to Monocle are welcome from everyone. The following are a set of guidelines for contributing to Monocle. Following these guidelines makes contributing to this project easy and transparent. These are mostly guidelines, not rules. Use your best judgment, and feel free to propose changes to this document in a pull request. Please refer to our code of conduct when making contributions. 
+
+## How can you contribute?
+### Contributing code
+If you encounter a bug, you can
+- (Recommended) File an issue about the bug.
+- Provide clear and concrete ways/scripts to reproduce the bug.
+- Provide possible solutions for the bug.
+- Pull a request to fix the bug.
+
+If you're interested in existing issues, you can
+- (Recommended) Provide answers for issue labeled question.
+- Provide help for issues labeled bug, improvement, and enhancement by
+-- (Recommended) Ask questions, reproduce the issue, or provide solutions.
+-- Pull a request to fix the issue.
+
+If you require a new feature or major enhancement, you can
+- (Recommended) File an issue about the feature/enhancement with reasons.
+- Pull a request to implement the feature.
+
+If you are a reviewer/approver of Monocle, you can
+- Participate in PR review process.
+- Instruct newcomers in the community to complete the PR process.
+
+If you want to become a contributor of Monocle, submit your pull requests. All contributions to this project must be accompanied by acknowledgment of, and agreement to, the [Developer Certificate of Origin](https://github.com/apps/dco). All submissions will be reviewed as quickly as possible.
+
+ 

monocle_apptrace-0.0.1/COPYRIGHT.template

@@ -0,0 +1,2 @@
+Copyright Contributors to the Monocle project.
+SPDX-License-Identifier: Apache-2.0

monocle_apptrace-0.0.1/LICENSE

@@ -0,0 +1,51 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files.
+
+"Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below).
+
+"Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions:
+
+You must give any other recipients of the Work or Derivative Works a copy of this License; and
+You must cause any modified files to carry prominent notices stating that You changed the files; and
+You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and
+If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License.
+You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS

monocle_apptrace-0.0.1/MAINTAINER.md

@@ -0,0 +1,10 @@
+#MAINTAINERS
+Following is the current list of maintainers on this project
+
+The maintainers are listed in alphabetical order.
+
+- [@prasad-okahu] (https://github.com/prasad-okahu) (Prasad Mujumdar)
+- [@oi-raanne] (https://github.com/oi-raanne) (Ravi Anne)
+- [@akshay-okahu](https://github.com/akshay-okahu) (Akshay Yadav)
+- [@anshul7665] (https://github.com/anshul7665) (Anshul Sharma)
+- [@kshitiz-okahu] (https://github.com/kshitiz-okahu) (Kshitiz Vijayvargiya)

monocle_apptrace-0.0.1/Monocle_User_Guide.md

@@ -0,0 +1,154 @@
+#Monocle User Guide
+
+## Monocle Concepts
+### Traces
+Traces are the full view of a single end-to-end application KPI, for example Chatbot application to provide a response to end user’s question. Traces consist of various metadata about the application run including status, start time, duration, input/outputs etc. They also include a list of individual steps aka “spans with details about that step.
+It’s typically the workflow code components of an application that generate the traces for application runs. 
+### Spans
+Spans are the individual steps executed by the application to perform a GenAI related task”, for example app retrieving vectors from DB, app querying LLM for inference etc. The span includes the type of operation, start time, duration and metadata relevant to that step e.g., Model name, parameters and model endpoint/server for an inference request.
+It’s typically the workflow code components of an application that generate the traces for application runs.
+
+## Setup Monocle
+- You can download Monocle library releases from Pypi
+``` 
+    > pip install monocle_apptrace
+```
+- You can locally build and install Monocle library from source
+```
+> pip install .
+```
+- Install the optional test dependencies listed against dev in pyproject.toml in editable mode
+```
+> pip install -e ".[dev]"
+```
+
+## Using Monocle with your application to generate traces
+### Enable Monocle tracing
+You need to import monocle package and invoke the API ``setup_monocle_telemetry(workflow=<workflow-name>)`` to enable the tracing. The 'workflow-name' is what you define to identify the give application workflow, for example "customer-chatbot". Monocle trace will include this name in every trace. The trace output will include a list of spans in the traces. You can print the output on the console or send it to an HTTP endpoint.
+
+### Using Monocle's out of box support of genAI technology components
+Monocle community has done the hard work of figuring out what to trace and how to extract relevant details from multiple genAI technology components. For example, if you have a python app coded using LlamaIndex and using models hostsed in OpenAI, Monocle can seamlessly trace your app. All you need to do enable Monocle tracing.
+#### Example - Enable Monocle tracing in your application
+```python
+from monocle_apptrace.instrumentor import setup_monocle_telemetry
+from opentelemetry.sdk.trace.export import BatchSpanProcessor, ConsoleSpanExporter
+from langchain.chains import LLMChain
+from langchain_openai import OpenAI
+from langchain.prompts import PromptTemplate
+
+# Call the setup Monocle telemetry method
+setup_monocle_telemetry(workflow_name = "simple_math_app",
+        span_processors=[BatchSpanProcessor(ConsoleSpanExporter())])
+
+llm = OpenAI()
+prompt = PromptTemplate.from_template("1 + {number} = ")
+
+chain = LLMChain(llm=llm, prompt=prompt)
+chain.invoke({"number":2})
+
+# Request callbacks: Finally, let's use the request `callbacks` to achieve the same result
+chain = LLMChain(llm=llm, prompt=prompt)
+chain.invoke({"number":2}, {"callbacks":[handler]})
+    
+```
+### Leveraging Monocle's extensibility to handle customization 
+When the out of box features from app frameworks are not sufficent, the app developers have to add custom code. For example, if you are extending a LLM class in LlamaIndex to use a model hosted in NVIDIA Triton. This new class is not know to Monocle. You can specify this new class method part of Monocle enabling API and it will be able to trace it.
+
+#### Default configuration of instrumented methods in Monocle
+The following files comprise of default configuration of instrumented methods and span names corresponding to them, for each framework respectively. 
+- [src/monocle_apptrace/langchain/__init__.py](src/monocle_apptrace/langchain/__init__.py),
+- [src/monocle_apptrace/llamaindex/__init__.py](src/monocle_apptrace/llamaindex/__init__.py),
+- [src/monocle_apptrace/haystack/__init__.py](src/monocle_apptrace/haystack/__init__.py)
+
+Following configuration instruments  ```invoke(..)``` of ```RunnableSequence```, aka chain or worflow in Langchain parlance, to emit the span.
+```
+    {
+        "package": "langchain.schema.runnable",
+        "object": "RunnableSequence",
+        "method": "invoke",
+        "span_name": "langchain.workflow",
+        "wrapper": task_wrapper
+    }
+```
+#### Example - Monitoring custom methods with Monocle
+```python
+from monocle_apptrace.wrapper import WrapperMethod,task_wrapper,atask_wrapper
+from opentelemetry.sdk.trace.export import BatchSpanProcessor, ConsoleSpanExporter
+
+# extend the default wrapped methods list as follows
+app_name = "simple_math_app"
+setup_monocle_telemetry(
+        workflow_name=app_name,
+        span_processors=[BatchSpanProcessor(ConsoleSpanExporter())],
+        wrapper_methods=[
+            WrapperMethod(
+                package="langchain.schema.runnable",
+                object="RunnableParallel",
+                method="invoke",
+                span_name="langchain.workflow",
+                wrapper=task_wrapper),
+            WrapperMethod(
+                package="langchain.schema.runnable",
+                object="RunnableParallel",
+                method="ainvoke",
+                span_name="langchain.workflow",
+                wrapper=atask_wrapper)
+        ])
+
+```
+
+### Going beyond supported genAI components
+- If you are using an application framework, model hosting service/infra etc. that's not currently supported by Monocle, please submit a github issue to add that support. 
+- Monocle community is working on adding an SDK to enable applications to generate their own traces.  
+
+## Understanding the trace output
+
+### Trace span json 
+
+Monocle generates spans which adhere to [Tracing API | OpenTelemetry](https://opentelemetry.io/docs/specs/otel/trace/api/#span) format. The trace output is an array of spans. Each trace has a unique id. Every span has in the trace has this parent ```trace_id```. Please note that ```trace_id``` groups related spans and is auto generated with-in Monocle.
+
+| Span JSON      | Description     |
+| ------------- | ------------- |
+| {||
+|  "```name```": "langchain.workflow",|span name and is configurable in [__init.py__](src/monocle_apptrace/langchain/__init__.py) or in ```setup_okahu_telemetry(...)```|
+|  "```context```": {|this gets autogenerated|
+| &ensp;    "```trace_id```": "0xe5269f0e534efa098b240f974220d6b7",||
+| &ensp;       "```span_id```": "0x30b13075eca52f44",||
+| &ensp;       "```trace_state```": "[]"||
+| &ensp;   },||
+|"```kind```": "SpanKind.INTERNAL",| an enum that describes what this span is about. Default value is SpanKind.INTERNAL, as current enums do not cover ML apps |
+|"```parent_id```": null,|if null, this is root span|
+|"```start_time```": "2024-07-16T17:05:15.544861Z",||
+|"```end_time```": "2024-07-16T17:05:43.502007Z",||
+|"```status```": {||
+|&ensp;  "```status_code```": "UNSET"| status of span to OK or ERROR. Default is UNSET|
+|&ensp; },||
+|"```attributes```": {||
+|&ensp; "workflow_name": "ml_rag_app",|defines the name of the service being set in ```setup_okahu_telemetry(...)``` during initialization of instrumentation|
+|&ensp; "workflow_type": "workflow.langchain"|type of framework that generated this span|
+|&ensp; },||
+|"```events```": [|captures the log records|
+|&ensp; {||
+|&ensp;&emsp;  "```name```": "input",|name of the event. If the span is about LLM, then this will be 'input'. For vector store retrieval, this would be 'context_input'|
+|&ensp;&emsp;  "```timestamp```": "2024-07-16T17:05:15.544874Z",||
+|&ensp;&emsp;  "```attributes```": {|captures the 'input' attributes. Based on the workflow of the ML framework being used, the attributes change|
+|&emsp;&emsp;&emsp;    "question": "What is Task Decomposition?",|represents LLM query|
+|&emsp;&emsp;&emsp;    "q_a_pairs": "..." |represents questions and answers for a few shot LLM prompting |
+|&emsp;&emsp;              }||
+|&emsp;         },||
+|&emsp; {||
+|&emsp;&emsp;  "```name```": "output",|represents 'ouput' event of LLM|
+|&emsp;&emsp; "```timestamp```": "2024-07-16T17:05:43.501996Z",||
+|&emsp;&emsp;"```attributes```": {||
+|&emsp;&emsp;&emsp; "response": "Task Decomposition is ..."|response to LLM query. |
+|&emsp;&emsp;&emsp;}||
+|&emsp;&emsp;}||
+|&emsp;    ],||
+|&emsp; "```links```": [],|unused. Ideally this links other causally-related spans,<br/> but as spans are grouped by ```trace_id```, and ```parent_id``` links to parent span, this is unused|
+|&emsp;   "```resource```": {|represents the service name or server or machine or container which generated the span|
+|&emsp;&emsp;&emsp;  "```attributes```": {||
+|&emsp;&emsp;&emsp;&emsp;  "service.name": "ml_rag_app"|only service.name is being populated and defaults to the value of 'workflow_name' |
+|&emsp;&emsp;&emsp;  },||
+|&emsp;&emsp;"```schema_url```": ""|unused|
+|&emsp;&emsp;     }||
+|} | |

monocle_apptrace-0.0.1/Monocle_committer_guide.md

@@ -0,0 +1,26 @@
+# Monocle Committer Guide
+This document provide details for Monocle committers tasks
+
+## Build and publishing python packages
+### Building the package
+
+```
+> python3 -m build 
+```
+### Publishing the package
+
+```
+> python3 -m pip install --upgrade twine
+> python3 -m twine upload --repository testpypi dist/*
+```
+### Installing the package
+
+The steps to set the credential can be found here:
+https://packaging.python.org/en/latest/specifications/pypirc/
+
+After setup of credentials, follow the commands below to publish the package to testpypi:
+
+```
+> python3 -m pip install pipenv
+> pipenv install monocle-observability
+```

monocle_apptrace-0.0.1/Monocle_contributor_guide.md

@@ -0,0 +1 @@
+Coming soon ...

monocle_apptrace-0.0.1/NOTICE

@@ -0,0 +1,4 @@
+Monocle
+Copyright 2018-2021 Monocle Project Authors
+
+Licensed under Apache License 2.0.  See LICENSE for terms.

monocle_apptrace-0.0.1/PKG-INFO

@@ -0,0 +1,76 @@
+Metadata-Version: 2.3
+Name: monocle_apptrace
+Version: 0.0.1
+Summary: package with monocle genAI tracing
+Project-URL: Homepage, https://github.com/monocle2ai/monocle
+Project-URL: Issues, https://github.com/monocle2ai/monocle/issues
+License-File: LICENSE
+License-File: NOTICE
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.8
+Requires-Dist: opentelemetry-api>=1.21.0
+Requires-Dist: opentelemetry-instrumentation
+Requires-Dist: opentelemetry-sdk>=1.21.0
+Requires-Dist: requests
+Requires-Dist: wrapt>=1.14.0
+Provides-Extra: dev
+Requires-Dist: datasets==2.20.0; extra == 'dev'
+Requires-Dist: faiss-cpu==1.8.0; extra == 'dev'
+Requires-Dist: instructorembedding==1.0.1; extra == 'dev'
+Requires-Dist: langchain-chroma==0.1.1; extra == 'dev'
+Requires-Dist: langchain-community==0.2.5; extra == 'dev'
+Requires-Dist: langchain-openai==0.1.8; extra == 'dev'
+Requires-Dist: langchain==0.2.5; extra == 'dev'
+Requires-Dist: llama-index-embeddings-huggingface==0.2.0; extra == 'dev'
+Requires-Dist: llama-index-vector-stores-chroma==0.1.9; extra == 'dev'
+Requires-Dist: llama-index==0.10.30; extra == 'dev'
+Requires-Dist: numpy==1.26.4; extra == 'dev'
+Requires-Dist: pytest==8.0.0; extra == 'dev'
+Requires-Dist: sentence-transformers==2.6.1; extra == 'dev'
+Requires-Dist: types-requests==2.31.0.20240106; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# monocle genAI observability
+### Background
+Generative AI (GenAI) is the type of AI used to create content such as conversations, images, or video based on prior learning from existing content. GenAI relies on foundational models, which are exceptionally large ML models trained on vast amounts of generalized and unlabeled data to perform variety of general tasks such as understanding language and generating new text, audio or images from user provided prompts in a human language. Foundational models (FM) work by using learned patterns and relationships from the training data to predict the next item in a sequence given a prompt. It is cheaper and faster for data scientists to use foundational models as starting points rather than building models from scratch to build ML apps.  
+Large Language Models (LLMs) are a class of foundational models trained on text data used to perform a variety of tasks such as understanding language, reasoning over text, and generating new text based on user prompts in a human language. Examples of LLMs include ChatGPT, Llama, and Claude. 
+LLM-based AI apps leverage understanding language, reasoning & text generation to augment or automate complex tasks that typically require human intervention such as summarizing legal documents, triaging customer support tickets, or more.  
+Typically, AI developers build LLM-based AI apps that automate complex workflows by combining multiple LLMs and components such as prompts, vectors, or agents that each solve a discrete task that are connected by chains or pipelines in different ways using LLM (Large Language Model) orchestration frameworks.  
+When deployed to production, different parts of multi-component distributed LLM-based AI apps run on a combination of different kinds of AI infrastructure such as LLM-as-a-Service, GPU (graphics processing units) clouds, managed services from cloud, or custom-engineered AI stack. Typically, these systems are managed in production by IT DevOps engineers.  
+AI developers code, monitor, debug and optimize the resources in an LLM-based AI application. IT DevOps engineers monitor, troubleshoot, and optimize the services in the AI infra that the LLM-based AI application runs on. 
+
+## Introducing “Monocle – An eye for A.I.”
+The goal of project Monocle is to help GenAI developer to trace their applications. A typical GenAI application comprises of several technology components like application code/workflow, models, inferences services, vector databases etc. Understanding the dependencies and tracking application quickly becomes a difficult task. Monocle can be integrated into application code with very little to no code changes. Monocle supports tracing all GenAI technology components, application frameworks, LLM hosting services. We do all the hard work of finding what needs to be instrumented and how to instrument it. This enables the enlightened applications to generate detailed traces without any additional efforts from the developers.
+The traces are compatible with OpenTelemetry format. They are further enriched to contain lot more attribute relevant to GenAI applications like prompts. The project will have out of box support to store the traces locally and a extensibility for a third party store which can be implemented by end user or a supplied by third party vendors.    
+
+## Monocle integration
+### genAI Appliation frameworks
+- Langchain
+- LlamaIndex
+- Haystack
+### LLMs
+- OpenAI
+- Azure OpenAI
+- NVIDIA Triton
+
+## Getting started
+### Try Monocle with your python genAI application
+- Get latest Monocle python brary 
+```
+    pip install monocle_apptrace
+```
+- Enable Monocle tracing in your app by adding following
+```
+    setup_okahu_telemetry(workflow_name="your-app-name")
+```
+Please refer to [Monocle user guide](Monocle_User_Guide.md) for more details
+
+## Get involved
+### Provide feedback
+- Submit issues and enhancements requests via Github issues
+
+### Contribute
+- Monocle is community based open source project. We welcome your contributions. Please refer to the CONTRIBUTING and CODE_OF_CONDUCT for guidelines. The [contributor's guide](CONTRIBUTING.md) provides technical details of the project.
+

monocle_apptrace-0.0.1/README.md

@@ -0,0 +1,42 @@
+# monocle genAI observability
+### Background
+Generative AI (GenAI) is the type of AI used to create content such as conversations, images, or video based on prior learning from existing content. GenAI relies on foundational models, which are exceptionally large ML models trained on vast amounts of generalized and unlabeled data to perform variety of general tasks such as understanding language and generating new text, audio or images from user provided prompts in a human language. Foundational models (FM) work by using learned patterns and relationships from the training data to predict the next item in a sequence given a prompt. It is cheaper and faster for data scientists to use foundational models as starting points rather than building models from scratch to build ML apps.  
+Large Language Models (LLMs) are a class of foundational models trained on text data used to perform a variety of tasks such as understanding language, reasoning over text, and generating new text based on user prompts in a human language. Examples of LLMs include ChatGPT, Llama, and Claude. 
+LLM-based AI apps leverage understanding language, reasoning & text generation to augment or automate complex tasks that typically require human intervention such as summarizing legal documents, triaging customer support tickets, or more.  
+Typically, AI developers build LLM-based AI apps that automate complex workflows by combining multiple LLMs and components such as prompts, vectors, or agents that each solve a discrete task that are connected by chains or pipelines in different ways using LLM (Large Language Model) orchestration frameworks.  
+When deployed to production, different parts of multi-component distributed LLM-based AI apps run on a combination of different kinds of AI infrastructure such as LLM-as-a-Service, GPU (graphics processing units) clouds, managed services from cloud, or custom-engineered AI stack. Typically, these systems are managed in production by IT DevOps engineers.  
+AI developers code, monitor, debug and optimize the resources in an LLM-based AI application. IT DevOps engineers monitor, troubleshoot, and optimize the services in the AI infra that the LLM-based AI application runs on. 
+
+## Introducing “Monocle – An eye for A.I.”
+The goal of project Monocle is to help GenAI developer to trace their applications. A typical GenAI application comprises of several technology components like application code/workflow, models, inferences services, vector databases etc. Understanding the dependencies and tracking application quickly becomes a difficult task. Monocle can be integrated into application code with very little to no code changes. Monocle supports tracing all GenAI technology components, application frameworks, LLM hosting services. We do all the hard work of finding what needs to be instrumented and how to instrument it. This enables the enlightened applications to generate detailed traces without any additional efforts from the developers.
+The traces are compatible with OpenTelemetry format. They are further enriched to contain lot more attribute relevant to GenAI applications like prompts. The project will have out of box support to store the traces locally and a extensibility for a third party store which can be implemented by end user or a supplied by third party vendors.    
+
+## Monocle integration
+### genAI Appliation frameworks
+- Langchain
+- LlamaIndex
+- Haystack
+### LLMs
+- OpenAI
+- Azure OpenAI
+- NVIDIA Triton
+
+## Getting started
+### Try Monocle with your python genAI application
+- Get latest Monocle python brary 
+```
+    pip install monocle_apptrace
+```
+- Enable Monocle tracing in your app by adding following
+```
+    setup_okahu_telemetry(workflow_name="your-app-name")
+```
+Please refer to [Monocle user guide](Monocle_User_Guide.md) for more details
+
+## Get involved
+### Provide feedback
+- Submit issues and enhancements requests via Github issues
+
+### Contribute
+- Monocle is community based open source project. We welcome your contributions. Please refer to the CONTRIBUTING and CODE_OF_CONDUCT for guidelines. The [contributor's guide](CONTRIBUTING.md) provides technical details of the project.
+

monocle_apptrace-0.0.1/SECURITY.md

@@ -0,0 +1,9 @@
+# Security Policy
+
+## Supported Versions
+
+Please upgrade to latest stable version of Monocle which will have know security issues addressed.
+
+## Reporting a Vulnerability
+
+Please report security vulnerabilities privately to the Monocle [maintainer team] (https://github.com/monocle2ai/monocle/blob/main/MAINTAINER.md). Please do not post security vulnerabilities to the public issue tracker.

monocle_apptrace-0.0.1/pyproject.toml

@@ -0,0 +1,79 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "monocle_apptrace"
+version = "0.0.1"
+authors = []
+description = "package with monocle genAI tracing"
+readme = "README.md"
+requires-python = ">=3.8"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+   'requests',
+   'wrapt>=1.14.0',
+   'opentelemetry-api>=1.21.0',
+   'opentelemetry-sdk>=1.21.0',
+   'opentelemetry-instrumentation',
+]
+
+[tool.pytest.ini_options]
+pythonpath = [
+  "src"
+]
+
+[project.optional-dependencies]
+dev = [
+  'langchain-openai==0.1.8',
+  'langchain-chroma==0.1.1',
+  'langchain-community==0.2.5',
+  'langchain==0.2.5',
+  'datasets==2.20.0',
+  'numpy==1.26.4',
+  'types-requests==2.31.0.20240106',
+  'InstructorEmbedding==1.0.1',
+  'sentence-transformers==2.6.1',
+  'faiss-cpu==1.8.0',
+  'pytest==8.0.0',
+  'llama-index==0.10.30',
+  'llama-index-embeddings-huggingface==0.2.0',
+  'llama-index-vector-stores-chroma==0.1.9'
+]
+
+[project.urls]
+Homepage = "https://github.com/monocle2ai/monocle"
+Issues = "https://github.com/monocle2ai/monocle/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/monocle_apptrace"]
+
+[tool.hatch.build.targets.sdist]
+ignore-vcs = true
+
+[tool.hatch.build]
+exclude = [
+  "/.*",
+  "*.txt",
+  "Pipfile",
+  "/data",
+  "/docs",
+  "/tests",
+  "*.yml",
+]
+
+[tool.pylint]
+max-line-length = 120
+disable = [
+    "C0103", # (invalid-name)
+    "C0114", # (missing-module-docstring)
+    "C0115", # (missing-class-docstring)
+    "C0116", # (missing-function-docstring)
+    "R0903", # (too-few-public-methods)
+    "R0913", # (too-many-arguments)
+    "W0105", # (pointless-string-statement)
+]

monocle_apptrace-0.0.1/src/monocle_apptrace/README.md

@@ -0,0 +1,77 @@
+#Monocle User Guide
+
+## Monocle Concepts
+### Traces
+Traces are the full view of a single end-to-end application KPI eg Chatbot application to provide a response to end user’s question. Traces consists of various metadata about the application run including status, start time, duration, input/outputs etc. It also includes a list of individual steps aka “spans with details about that step.
+It’s typically the workflow code components of an application that generate the traces for application runs. 
+### Spans
+Spans are the individual steps executed by the application to perform a GenAI related task” eg app retrieving vectors from DB, app querying LLM for inference etc. The span includes the type of operation, start time, duration and metadata relevant to that step eg Model name, parameters and model endpoint/server for an inference request.
+It’s typically the workflow code components of an application that generate the traces for application runs.
+
+## Setup Monocle
+- You can download Monocle library releases from Pypi
+``` 
+    > python3 -m pip install pipenv
+    > pip install monocle-observability
+```
+- You can locally build and install Monocle library from source
+```
+> pip install .
+> pip install -e ".[dev]"
+
+> python3 -m pip install pipenv
+> pipenv install build
+```
+
+## Examples 
+### Enable Monocle tracing in your application
+```python
+from monocle_apptrace.instrumentor import setup_monocle_telemetry
+from opentelemetry.sdk.trace.export import BatchSpanProcessor, ConsoleSpanExporter
+from langchain.chains import LLMChain
+from langchain_openai import OpenAI
+from langchain.prompts import PromptTemplate
+
+# Call the setup Monocle telemetry method
+setup_monocle_telemetry(workflow_name = "simple_math_app",
+        span_processors=[BatchSpanProcessor(ConsoleSpanExporter())])
+
+llm = OpenAI()
+prompt = PromptTemplate.from_template("1 + {number} = ")
+
+chain = LLMChain(llm=llm, prompt=prompt)
+chain.invoke({"number":2})
+
+# Request callbacks: Finally, let's use the request `callbacks` to achieve the same result
+chain = LLMChain(llm=llm, prompt=prompt)
+chain.invoke({"number":2}, {"callbacks":[handler]})
+    
+```
+
+### Monitoring custom methods with Monocle
+
+```python
+from monocle_apptrace.wrapper import WrapperMethod,task_wrapper,atask_wrapper
+from opentelemetry.sdk.trace.export import BatchSpanProcessor, ConsoleSpanExporter
+
+# extend the default wrapped methods list as follows
+app_name = "simple_math_app"
+setup_monocle_telemetry(
+        workflow_name=app_name,
+        span_processors=[BatchSpanProcessor(ConsoleSpanExporter())],
+        wrapper_methods=[
+            WrapperMethod(
+                package="langchain.schema.runnable",
+                object="RunnableParallel",
+                method="invoke",
+                span_name="langchain.workflow",
+                wrapper=task_wrapper),
+            WrapperMethod(
+                package="langchain.schema.runnable",
+                object="RunnableParallel",
+                method="ainvoke",
+                span_name="langchain.workflow",
+                wrapper=atask_wrapper)
+        ])
+
+```

monocle_apptrace-0.0.1/src/monocle_apptrace/__init__.py

@@ -0,0 +1,2 @@
+
+