divi 0.0.1b1__tar.gz → 0.0.1b2__tar.gz

divi-0.0.1b2/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,38 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+1. Go to '...'
+2. Click on '....'
+3. Scroll down to '....'
+4. See error
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Screenshots**
+If applicable, add screenshots to help explain your problem.
+
+**Desktop (please complete the following information):**
+ - OS: [e.g. iOS]
+ - Browser [e.g. chrome, safari]
+ - Version [e.g. 22]
+
+**Smartphone (please complete the following information):**
+ - Device: [e.g. iPhone6]
+ - OS: [e.g. iOS8.1]
+ - Browser [e.g. stock browser, safari]
+ - Version [e.g. 22]
+
+**Additional context**
+Add any other context about the problem here.

divi-0.0.1b2/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,20 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

divi-0.0.1b2/.github/pull_request_template.md

@@ -0,0 +1,12 @@
+<!-- Thanks for contributing to divine-agent! 🥳
+Given this is a project maintained by volunteers, please read this template to not waste your time, or ours! 😇 -->
+
+# Summary
+
+<!-- Write a small summary about what is happening here. -->
+
+# Checklist
+
+- [ ] I understand that this PR may be closed in case there was no previous discussion. (This doesn't apply to typos!)
+- [ ] I've added a test for each change that was introduced, and I tried as much as possible to make a single atomic change.
+- [ ] I've updated the documentation accordingly.

{divi-0.0.1b1 → divi-0.0.1b2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: divi
-Version: 0.0.1b1
+Version: 0.0.1b2
 Summary: The Agent Platform for Observability & Evaluation
 License-File: LICENSE
 Requires-Python: >=3.11

{divi-0.0.1b1 → divi-0.0.1b2}/README.md

@@ -10,6 +10,10 @@
 </a>
 </p>
 
+<p align="center">
+    <a href="./docs/README_ZH.md">中文</a> / English
+</p>
+
 divine-agent is an observability tool for LLM-based agents, offering tracing, evaluation, and usage statistics.
 
 ---
@@ -27,7 +31,7 @@ Requires Python 3.11+
 pip install divi
 ```
 
-## Usage
+## Trace
 
 1. Get API Key from [Web](https://www.divine-agent.com/dashboard/api-keys).
 2. Create a `.env` file and add the following line:
@@ -36,7 +40,7 @@ pip install divi
   ```
 3. Run the following code:
   ```python
-  from divi import Score, obs_openai, observable
+  from divi import obs_openai, observable
   from dotenv import load_dotenv
   from openai import OpenAI
 
@@ -48,7 +52,6 @@ pip install divi
           self.client = obs_openai(
               OpenAI(),
               name="Pirate",
-              scores=[Score.instruction_adherence],
           )
 
       @observable(name="Talk with pirate")

{divi-0.0.1b1 → divi-0.0.1b2}/apps/docs/docs.json

@@ -15,7 +15,11 @@
         "groups": [
           {
             "group": "Get Started",
-            "pages": ["en/introduction", "en/quickstart/trace"]
+            "pages": [
+              "en/introduction",
+              "en/quickstart/trace",
+              "en/quickstart/evaluation"
+            ]
           }
         ]
       },
@@ -24,7 +28,11 @@
         "groups": [
           {
             "group": "快速开始",
-            "pages": ["zh/introduction", "zh/quickstart/trace"]
+            "pages": [
+              "zh/introduction",
+              "zh/quickstart/trace",
+              "zh/quickstart/evaluation"
+            ]
           }
         ]
       }

divi-0.0.1b2/apps/docs/en/quickstart/evaluation.mdx

@@ -0,0 +1,34 @@
+---
+title: 'Evaluation'
+description: 'Evaluate your agents in one line'
+---
+import PirateEval from '/snippets/evaluation/pirate-eval.mdx';
+import PirateCustomEval from '/snippets/evaluation/pirate-custom-eval.mdx';
+
+<img className="block dark:hidden" src="/images/pirate-eval-example.png" />
+<img className="hidden dark:block" src="/images/pirate-eval-example-dark.png" />
+
+## Behavior Evaluation
+
+> Automate evaluation of instruction adherence and task completion for your [traced](./trace) Pirate agent.
+
+<PirateEval />
+
+## Custom Configuration
+
+| Property        | Type   | Default             | Description         |
+|-----------------|--------|---------------------|---------------------|
+| `model`         | str    | gpt-4o              | Model name used for evaluation |
+| `temperature`   | float  | 0.5                 | Temperature parameter for evaluation |
+| `n_rounds`      | int    | 5                   | Number of evaluation rounds |
+| `max_concurrency` | int  | 10                  | Maximum number of concurrent requests |
+| `api_key`       | str    | OPENAI_API_KEY      | API key for evaluation |
+| `base_url`      | str    | OPENAI_BASE_URL     | Service URL for evaluation |
+
+By default, `api_key` and `base_url` will use values from environment variables, and other options are configured as shown in the table above. You can customize the settings as follows:
+
+<PirateCustomEval />
+
+## Notes
+
+<Warning>The current evaluation functionality depends on OpenAI's [structured output](https://platform.openai.com/docs/guides/structured-outputs). Please ensure that your chosen [model](https://platform.openai.com/docs/models) supports this feature. We strongly recommend using `gpt-4o` or newer models to ensure evaluation effectiveness and compatibility.</Warning>

divi-0.0.1b2/apps/docs/en/quickstart/trace.mdx

@@ -0,0 +1,36 @@
+---
+title: 'Trace'
+description: 'Start observe your agents in under 5 minutes'
+---
+
+import PirateExample from '/snippets/pirate-example.mdx';
+
+<img className="block dark:hidden" src="/images/pirate-example.png" />
+<img className="hidden dark:block" src="/images/pirate-example-dark.png" />
+
+<Steps>
+    <Step title="Create an Account">
+        Create an account on [Divine Agent](https://www.divine-agent.com/signup?source=docs).
+    </Step>
+    <Step title="Install Divi">
+        Install the Divine Agent Python package:
+        ```shell
+        pip install divi
+        ```
+    </Step>
+    <Step title="Get API Key">
+      Get API Key from [Web](https://www.divine-agent.com/dashboard/api-keys).
+    </Step>
+    <Step title="Set up Environment">
+        Create a `.env` file and add the following line:
+        ```env
+        DIVI_API_KEY=your_api_key
+        OPENAI_BASE_URL=https://api.openai.com/v1
+        OPENAI_API_KEY=your_llm_api_key
+        ```
+    </Step>
+    <Step title="Trace Pirate Agent">
+        Run the following code:
+        <PirateExample />
+    </Step>
+</Steps>

divi-0.0.1b2/apps/docs/snippets/evaluation/pirate-custom-eval.mdx

@@ -0,0 +1,40 @@
+```python Pirate Example {2,15-18} [expandable]
+from divi import obs_openai, observable
+from divi.evaluation import EvaluatorConfig, Score
+from dotenv import load_dotenv
+from openai import OpenAI
+
+load_dotenv()
+
+
+class Pirate:
+    def __init__(self):
+        self.client = obs_openai(
+            OpenAI(),
+            name="Pirate",
+            scores=[Score.instruction_adherence, Score.task_completion],
+            eval=EvaluatorConfig(
+                model="gpt-4.1",
+                n_rounds=2,
+            ),
+        )
+
+    @observable(name="Talk with pirate")
+    def talk(self, message: str):
+        """Talk like a pirate."""
+        res = self.client.chat.completions.create(
+            model="gpt-4o",
+            messages=[
+                {"role": "developer", "content": "Talk like a pirate."},
+                {
+                    "role": "user",
+                    "content": message,
+                },
+            ],
+        )
+        return res.choices[0].message.content
+
+
+pirate = Pirate()
+pirate.talk("How do I check if a Python object is an instance of a class?")
+```

divi-0.0.1b2/apps/docs/snippets/evaluation/pirate-eval.mdx

@@ -0,0 +1,36 @@
+```python Pirate Example {2,14} [expandable]
+from divi import obs_openai, observable
+from divi.evaluation import Score
+from dotenv import load_dotenv
+from openai import OpenAI
+
+load_dotenv()
+
+
+class Pirate:
+    def __init__(self):
+        self.client = obs_openai(
+            OpenAI(),
+            name="Pirate",
+            scores=[Score.instruction_adherence, Score.task_completion],
+        )
+
+    @observable(name="Talk with pirate")
+    def talk(self, message: str):
+        """Talk like a pirate."""
+        res = self.client.chat.completions.create(
+            model="gpt-4o",
+            messages=[
+                {"role": "developer", "content": "Talk like a pirate."},
+                {
+                    "role": "user",
+                    "content": message,
+                },
+            ],
+        )
+        return res.choices[0].message.content
+
+
+pirate = Pirate()
+pirate.talk("How do I check if a Python object is an instance of a class?")
+```

divi-0.0.1b2/apps/docs/snippets/pirate-example.mdx

@@ -0,0 +1,34 @@
+```python Pirate Example {1,10-13,15} [expandable]
+from divi import obs_openai, observable
+from dotenv import load_dotenv
+from openai import OpenAI
+
+load_dotenv()
+
+
+class Pirate:
+    def __init__(self):
+        self.client = obs_openai(
+            OpenAI(),
+            name="Pirate",
+        )
+
+    @observable(name="Talk with pirate")
+    def talk(self, message: str):
+        """Talk like a pirate."""
+        res = self.client.chat.completions.create(
+            model="gpt-4o",
+            messages=[
+                {"role": "developer", "content": "Talk like a pirate."},
+                {
+                    "role": "user",
+                    "content": message,
+                },
+            ],
+        )
+        return res.choices[0].message.content
+
+
+pirate = Pirate()
+pirate.talk("How do I check if a Python object is an instance of a class?")
+```

divi-0.0.1b2/apps/docs/zh/quickstart/evaluation.mdx

@@ -0,0 +1,34 @@
+---
+title: '评估'
+description: '一行代码完成智能体评估'
+---
+import PirateEval from '/snippets/evaluation/pirate-eval.mdx';
+import PirateCustomEval from '/snippets/evaluation/pirate-custom-eval.mdx';
+
+<img className="block dark:hidden" src="/images/pirate-eval-example.png" />
+<img className="hidden dark:block" src="/images/pirate-eval-example-dark.png" />
+
+## 行为评估
+
+> 自动化评估[跟踪](./trace)的海盗 (Pirate) 智能体的指令遵从性和任务完成度。
+
+<PirateEval />
+
+## 自定义设置
+
+| Property        | Type   | Default             | Description         |
+|-----------------|--------|:-------------------:|---------------------|
+| `model`         | str    | gpt-4o              | 用于评估的模型名称     |
+| `temperature`   | float  | 0.5                 | 评估过程中的温度参数    |
+| `n_rounds`      | int    | 5                   | 评估的轮数            |
+| `max_concurrency` | int  | 10                  | 最大并发请求数         |
+| `api_key`       | str    | OPENAI_API_KEY      | 用于评估的 API 密钥    |
+| `base_url`      | str    | OPENAI_BASE_URL     | 评估所用的服务商 URL   |
+
+默认情况下，`api_key` 与 `base_url` 会使用环境变量中的值，其他选项配置如上表所示。您可以通过以下方式自定义设置：
+
+<PirateCustomEval />
+
+## 注意事项
+
+<Warning>当前评估功能依赖于 OpenAI 的[结构化输出](https://platform.openai.com/docs/guides/structured-outputs)，请确保您所选择的[模型](https://platform.openai.com/docs/models)支持该功能，我们强烈建议使用 `gpt-4o` 或更新版本的模型以确保评估效果和兼容性。</Warning>

divi-0.0.1b2/apps/docs/zh/quickstart/trace.mdx

@@ -0,0 +1,36 @@
+---
+title: '追踪'
+description: '5 分钟内开启智能体追踪'
+---
+
+import PirateExample from '/snippets/pirate-example.mdx';
+
+<img className="block dark:hidden" src="/images/pirate-example.png" />
+<img className="hidden dark:block" src="/images/pirate-example-dark.png" />
+
+<Steps>
+    <Step title="创建账户">
+        在 [Divine Agent](https://www.divine-agent.com/signup?source=docs) 上创建一个账户。
+    </Step>
+    <Step title="安装 Divi">
+        安装 Divine Agent Python 包:
+        ```shell
+        pip install divi
+        ```
+    </Step>
+    <Step title="获取 API Key">
+      从 [Web](https://www.divine-agent.com/dashboard/api-keys) 获取 API Key。
+    </Step>
+    <Step title="设置环境">
+        创建一个 `.env` 文件并添加以下行:
+        ```env
+        DIVI_API_KEY=your_api_key
+        OPENAI_BASE_URL=https://api.openai.com/v1
+        OPENAI_API_KEY=your_llm_api_key
+        ```
+    </Step>
+    <Step title="追踪 Pirate Agent">
+        运行以下代码:
+        <PirateExample />
+    </Step>
+</Steps>

{divi-0.0.1b1 → divi-0.0.1b2}/divi/__init__.py

@@ -13,5 +13,5 @@ _auth: Optional[Auth] = None
 _datapark: Optional[DataPark] = None
 _evaluator: Optional[Evaluator] = None
 
-__version__ = "0.0.1b1"
+__version__ = "0.0.1b2"
 __all__ = ["obs_openai", "observable"]

{divi-0.0.1b1 → divi-0.0.1b2}/divi/signals/span.py

@@ -1,3 +1,4 @@
+import atexit
 import os
 import time
 from enum import Enum
@@ -62,6 +63,8 @@ class Span:
         """Start the span by recording the current time in nanoseconds."""
         self.start_time_unix_nano = time.time_ns()
         self.upsert_span()
+        # Register the end method to be called at exit
+        atexit.register(self.end)
 
     def end(self):
         """End the span by recording the end time in nanoseconds."""
@@ -69,6 +72,8 @@ class Span:
             raise ValueError("Span must be started before ending.")
         self.end_time_unix_nano = time.time_ns()
         self.upsert_span()
+        # Unregister the end method
+        atexit.unregister(self.end)
 
     def _add_node(self, trace_id: UUID4, parent_id: Optional[bytes] = None):
         """Add node for obs tree."""

{divi-0.0.1b1 → divi-0.0.1b2}/divi/signals/trace.py

@@ -1,3 +1,4 @@
+import atexit
 from datetime import UTC, datetime
 from typing import Optional
 from uuid import uuid4
@@ -63,6 +64,8 @@ class Trace:
         """Start the trace by recording the current time in nanoseconds."""
         self.start_time = datetime.now(UTC).isoformat()
         self.upsert_trace()
+        # Register the end method to be called on exit
+        atexit.register(self.end)
 
     def end(self):
         """End the trace by recording the end time in nanoseconds."""
@@ -70,6 +73,8 @@ class Trace:
             raise ValueError("Span must be started before ending.")
         self.end_time = datetime.now(UTC).isoformat()
         self.upsert_trace()
+        # Unregister the end method to prevent multiple calls
+        atexit.unregister(self.end)
 
     def upsert_trace(self):
         """Upsert trace with datapark."""

divi-0.0.1b2/docs/CODE_OF_CONDUCT.md

@@ -0,0 +1,128 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+jikaifang2002@gmail.com.
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series
+of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or
+permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior,  harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within
+the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.0, available at
+https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct
+enforcement ladder](https://github.com/mozilla/diversity).
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq. Translations are available at
+https://www.contributor-covenant.org/translations.

divi-0.0.1b2/docs/CONTRIBUTING.md

@@ -0,0 +1,3 @@
+# CONTRIBUTING
+
+> Thanks for contributing to divine-agent.

divi-0.0.1b2/docs/README_ZH.md

@@ -0,0 +1,77 @@
+<p align="center">
+  <a href="https://divine-agent.com/"><img width="128" height="128" src="https://raw.githubusercontent.com/Kaikaikaifang/divine-agent/main/docs/images/thinking-angel.png" alt='Divine Agent'></a>
+</p>
+
+<p align="center"><strong>神明代理人</strong> <em>– 全栈开源的智能体可观测方案，简单、清晰。</em></p>
+
+<p align="center">
+<a href="https://pypi.org/project/divi/">
+    <img src="https://img.shields.io/pypi/v/divi.svg" alt="Package version">
+</a>
+</p>
+
+<p align="center">
+中文 / <a href="./docs/README.md">English</a>
+</p>
+
+神明代理人 (Divine Agent) 是一个智能体可观测工具，提供追踪、评估和用量统计功能。
+
+---
+
+> [!IMPORTANT]
+> **神明代理人目前处于实验性阶段**，随时可能进行重大变更。本项目正处于活跃开发阶段，接口和功能模块可能在没有事先通知的情况下发生变更。
+>
+> 在正式稳定版本发布前，不建议在生产环境中使用该组件。
+
+## 安装
+
+建议 Python 版本 3.11+
+
+```shell
+pip install divi
+```
+
+## 追踪
+
+1. 从[官网](https://www.divine-agent.com/dashboard/api-keys)获取 API Key.
+2. 创建 `.env` 文件并添加以下行:
+  ```env
+  DIVI_API_KEY=your_divi_api_key
+  OPENAI_BASE_URL=https://api.deepseek.com
+  OPENAI_API_KEY=your_llm_api_key
+  ```
+3. 运行以下代码:
+  ```python
+  from divi import obs_openai, observable
+  from dotenv import load_dotenv
+  from openai import OpenAI
+
+  load_dotenv()
+
+
+  class Wukong:
+      def __init__(self):
+          self.client = obs_openai(
+              OpenAI(),
+              name="Wukong",
+          )
+
+      @observable(name="Talk with Wukong")
+      def talk(self, message: str):
+          """Talk like Wukong."""
+          res = self.client.chat.completions.create(
+              model="deepseek-chat",
+              messages=[
+                  {"role": "system", "content": "像孙悟空一样说话。"},
+                  {
+                      "role": "user",
+                      "content": message,
+                  },
+              ],
+          )
+          return res.choices[0].message.content
+
+
+  wukong = Wukong()
+  wukong.talk("如何检查一个 Python 对象是否是某个类的实例？")
+  ```