arksim 0.0.2__tar.gz

arksim-0.0.2/.editorconfig

@@ -0,0 +1,18 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 4
+
+[*.{yml,yaml,json,toml}]
+indent_size = 2
+
+[*.md]
+trim_trailing_whitespace = false
+
+[Makefile]
+indent_style = tab

arksim-0.0.2/.github/CODEOWNERS

@@ -0,0 +1 @@
+* @arklexai/arksim-maintainers

arksim-0.0.2/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,53 @@
+name: Bug Report
+description: Report a bug in Arksim
+labels: ["bug"]
+body:
+  - type: textarea
+    id: description
+    attributes:
+      label: Describe the bug
+      description: A clear description of the bug.
+    validations:
+      required: true
+  - type: textarea
+    id: steps
+    attributes:
+      label: Steps to reproduce
+      description: Steps to reproduce the behavior.
+      placeholder: |
+        1. Run `arksim simulate config.yaml`
+        2. ...
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+      description: What you expected to happen.
+    validations:
+      required: true
+  - type: textarea
+    id: logs
+    attributes:
+      label: Error output or logs
+      description: Paste any relevant error messages or logs.
+      render: shell
+  - type: input
+    id: version
+    attributes:
+      label: Arksim version
+      placeholder: "0.0.1"
+    validations:
+      required: true
+  - type: input
+    id: python
+    attributes:
+      label: Python version
+      placeholder: "3.11"
+    validations:
+      required: true
+  - type: input
+    id: os
+    attributes:
+      label: Operating system
+      placeholder: "macOS 15, Ubuntu 22.04, etc."

arksim-0.0.2/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Documentation
+    url: https://docs.arklex.ai/overview
+    about: Check the docs before opening an issue.
+  - name: Discussions
+    url: https://github.com/arklexai/arksim/discussions
+    about: Ask questions and share ideas.

arksim-0.0.2/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,23 @@
+name: Feature Request
+description: Suggest a new feature or improvement
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem or motivation
+      description: What problem does this feature solve? Why is it needed?
+    validations:
+      required: true
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed solution
+      description: Describe the feature or change you'd like.
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Any alternative approaches you've thought about.

arksim-0.0.2/.github/dependabot.yml

@@ -0,0 +1,27 @@
+version: 2
+
+updates:
+  - package-ecosystem: pip
+    directory: "/"
+    schedule:
+      interval: weekly
+      day: monday
+    open-pull-requests-limit: 10
+    labels:
+      - dependencies
+      - skip-changelog
+    commit-message:
+      prefix: "deps"
+
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: weekly
+      day: monday
+    open-pull-requests-limit: 5
+    labels:
+      - dependencies
+      - ci
+      - skip-changelog
+    commit-message:
+      prefix: "ci"

arksim-0.0.2/.github/pull_request_template.md

@@ -0,0 +1,39 @@
+## Summary
+
+<!-- Brief description of what this PR does and why. Link any related issues. -->
+
+Closes #
+
+## Changes
+
+<!-- What changed? List the key modifications. -->
+
+-
+
+## Documentation and Changelog
+
+<!-- All PRs must account for docs and changelog. Check every box that applies. -->
+
+- [ ] Added an entry to `CHANGELOG.md` under the `[Unreleased]` section
+- [ ] Updated relevant docs in `docs/` (if behavior, config, or API changed)
+- [ ] Updated `README.md` (if installation, quickstart, or usage changed)
+- [ ] No docs or changelog needed (explain why below)
+
+<!-- If "no docs needed", briefly explain: e.g. "internal refactor, no user-facing change" -->
+
+## How to Test
+
+<!-- Steps a reviewer can follow to verify the changes. -->
+
+- [ ] `ruff check .` passes
+- [ ] `ruff format --check .` passes
+- [ ] `pytest tests/` passes
+- [ ] Manual verification: <!-- describe what you tested -->
+
+## Notes
+
+<!-- Anything reviewers should know: trade-offs, follow-up work, migration steps, etc. -->
+
+## Reviewers
+
+/cc @arklexai/arksim-maintainers

arksim-0.0.2/.github/workflows/ci.yml

@@ -0,0 +1,42 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+      - name: Pre-commit checks
+        run: |
+          pip install pre-commit
+          SKIP=changelog-reminder pre-commit run --all-files
+      - name: Lint
+        run: |
+          pip install ruff
+          ruff check .
+          ruff format --check .
+
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+      - name: Test
+        run: pytest tests/ -v --tb=short

arksim-0.0.2/.github/workflows/pr-checks.yml

@@ -0,0 +1,108 @@
+name: PR checks
+
+on:
+  pull_request:
+    types: [opened, edited, synchronize, reopened, labeled, unlabeled]
+    branches: [main]
+
+permissions:
+  pull-requests: read
+
+jobs:
+  pr-checks:
+    name: PR checks
+    runs-on: ubuntu-latest
+    steps:
+      - name: Validate PR title format
+        uses: actions/github-script@v8
+        with:
+          script: |
+            const title = context.payload.pull_request.title;
+
+            if (title.length > 72) {
+              core.setFailed(
+                `PR title is ${title.length} characters (max 72).\n` +
+                `Title: "${title}"`
+              );
+              return;
+            }
+
+            // Format: <component>: <verb> <description>
+            const pattern = /^[a-z][a-z0-9_-]*: [a-z]+ .+$/;
+            if (!pattern.test(title)) {
+              core.setFailed(
+                `PR title does not match the required format.\n\n` +
+                `Expected: <component>: <verb> <description>\n` +
+                `  - component: lowercase, may contain digits, hyphens, underscores\n` +
+                `  - verb: lowercase imperative (add, fix, update, remove, ...)\n` +
+                `  - description: free text\n\n` +
+                `Examples:\n` +
+                `  arksim: add retry logic to evaluator\n` +
+                `  simulator: fix config loading for empty fields\n` +
+                `  ci: update python version in workflow\n\n` +
+                `Got: "${title}"`
+              );
+            }
+
+      - name: Validate PR description has content
+        uses: actions/github-script@v8
+        with:
+          script: |
+            const body = context.payload.pull_request.body || '';
+
+            // Strip HTML comments
+            let cleaned = body.replace(/<!--[\s\S]*?-->/g, '');
+
+            // Strip markdown headers (lines starting with #)
+            cleaned = cleaned.replace(/^#+\s.*$/gm, '');
+
+            // Strip empty checklist items (unchecked boxes with no real text)
+            cleaned = cleaned.replace(/^- \[ \]\s*$/gm, '');
+
+            // Strip template checklist items that are just tool commands
+            cleaned = cleaned.replace(/^- \[ \] `[^`]+`\s*(passes)?\s*$/gm, '');
+
+            // Strip blank "Closes #" lines
+            cleaned = cleaned.replace(/^Closes\s+#\s*$/gm, '');
+
+            // Strip lone list dashes (empty bullet points)
+            cleaned = cleaned.replace(/^-\s*$/gm, '');
+
+            // Collapse whitespace
+            cleaned = cleaned.replace(/\s+/g, ' ').trim();
+
+            if (cleaned.length < 20) {
+              core.setFailed(
+                `PR description is too short (${cleaned.length} characters of real content, minimum 20).\n\n` +
+                `Please fill out the PR template with a meaningful summary and description.\n` +
+                `Template headers, comments, and empty checkboxes do not count.`
+              );
+            }
+
+      - name: Check CHANGELOG.md was updated
+        uses: actions/github-script@v8
+        with:
+          script: |
+            const labels = context.payload.pull_request.labels.map(l => l.name);
+            if (labels.includes('skip-changelog')) {
+              core.info('skip-changelog label found, skipping check.');
+              return;
+            }
+
+            const { data: files } = await github.rest.pulls.listFiles({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              pull_number: context.payload.pull_request.number,
+              per_page: 100,
+            });
+
+            const changelogUpdated = files.some(f => f.filename === 'CHANGELOG.md');
+            if (!changelogUpdated) {
+              core.setFailed(
+                `CHANGELOG.md was not updated in this PR.\n\n` +
+                `Please add an entry under the [Unreleased] section describing your change.\n` +
+                `Use the appropriate heading: Added, Changed, Fixed, Removed, etc.\n\n` +
+                `If this change does not need a changelog entry (e.g. internal refactor,\n` +
+                `CI-only change), add the "skip-changelog" label to this PR.`
+              );
+            }

arksim-0.0.2/.github/workflows/publish-pypi.yml

@@ -0,0 +1,105 @@
+# Publishes arksim to PyPI.
+#
+# Triggered by pushing a version tag (e.g. v1.2.3).
+
+name: Publish to PyPI
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  # ---------------------------------------------------------------------------
+  # 1. Build wheel and source distribution.
+  # ---------------------------------------------------------------------------
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build wheel and sdist
+        run: |
+          pip install build
+          python -m build
+
+      - name: Verify distribution
+        run: |
+          pip install twine
+          twine check --strict dist/*
+
+      - name: Upload dist artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  # ---------------------------------------------------------------------------
+  # 2. Create GitHub Release with changelog and built dist files.
+  # ---------------------------------------------------------------------------
+  create-release:
+    name: Create GitHub Release
+    runs-on: ubuntu-latest
+    needs: build
+    permissions:
+      contents: write
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Download dist artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Generate changelog
+        id: changelog
+        uses: mikepenz/release-changelog-builder-action@v5
+        with:
+          toTag: ${{ github.ref_name }}
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ github.ref_name }}
+          name: ${{ github.ref_name }}
+          body: ${{ steps.changelog.outputs.changelog }}
+          files: dist/*
+          # Mark as pre-release when the version contains "rc".
+          prerelease: ${{ contains(github.ref_name, 'rc') }}
+
+  # ---------------------------------------------------------------------------
+  # 3. Publish to PyPI via OIDC trusted publisher
+  # ---------------------------------------------------------------------------
+  publish-pypi:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    needs: [build, create-release]
+    environment: pypi
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download dist artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

arksim-0.0.2/.gitignore

@@ -0,0 +1,57 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+*.egg
+dist/
+build/
+*.whl
+
+# Generated by hatch-vcs at build time
+arksim/_version.py
+
+# Environment variables
+.env
+.env.*
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+
+# Linting
+.ruff_cache/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Index and vector store files
+index/
+*.pkl
+*.faiss
+
+# Simulation/evaluation outputs
+conversation*/
+evaluation*/
+results/
+
+# Lock files (generated per environment)
+uv.lock
+
+# Local config overrides
+config_simulate.yaml

arksim-0.0.2/.pre-commit-config.yaml

@@ -0,0 +1,25 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-added-large-files
+        args: ["--maxkb=500"]
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.11.2
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: local
+    hooks:
+      - id: changelog-reminder
+        name: Check CHANGELOG.md updated
+        entry: scripts/check-changelog.sh
+        language: script
+        pass_filenames: false
+        always_run: true

arksim-0.0.2/CHANGELOG.md

@@ -0,0 +1,71 @@
+# Changelog
+
+All notable changes to Arksim will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+<!-- Add your changes here under the appropriate heading. -->
+<!-- Use: Added, Changed, Deprecated, Removed, Fixed, Security -->
+
+### Added
+
+- GitHub Actions workflow to build, release, and publish `arksim` to PyPI on `v*` tag pushes, with dynamic VCS-based versioning via `hatch-vcs`
+
+### Changed
+
+- Refactored `bank-insurance` and `e-commerce` example agents to use the OpenAI Agents SDK and corrected the example server port from `8080` to `8888`
+- Agent configuration is now defined inline in `config.yaml` under the `agent_config` key instead of in separate `agent_config.json` files
+- Updated all documentation and examples to use inline agent configuration
+- UI now passes `agent_config`, `custom_metrics_file_paths`, and `metrics_to_run` from loaded config YAML
+
+### Removed
+
+- Separate `agent_config.json` files from all examples (replaced by inline YAML config)
+- Knowledge Configuration and Data folder sections from agent configuration docs
+
+### Security
+
+- Removed third-party client data from test fixtures and evaluator prompt examples
+- Replaced with generic insurance-domain examples consistent with the public bank-insurance example
+
+### Fixed
+- Example servers: added logging before HTTP error responses, filtered system messages from agent chat history, fixed wrong config filename in e-commerce README
+- Documentation: end-of-file newlines in `docs/insurance-customer-service-agent-evaluation.mdx` and `docs/e-commerce-customer-service-agent-evaluation.mdx`
+- Documentation: trailing whitespace and end-of-file in `docs/simulate-conversation.mdx` and `docs/evaluate-conversation.mdx`
+- Trailing whitespace and missing EOF newlines across 81 files (docs, examples, tests, source)
+- UI file browser: `PROJECT_ROOT` now uses `cwd` for PyPI installs, parent navigation works correctly, YAML files shown in browser
+- Lint: replaced `try/except/pass` with `contextlib.suppress` in example loader
+
+### Added
+
+- Dependabot for automated pip and GitHub Actions dependency updates
+- Pre-commit hooks with ruff, trailing whitespace, end-of-file, YAML, and changelog checks
+- `py.typed` marker for PEP 561 type checking support
+- Top-level lazy exports (`from arksim import run_simulation, Evaluator, ...`)
+- `.editorconfig` for consistent editor settings
+- `Makefile` with common dev commands
+- Issue template chooser linking to docs and discussions
+- Documentation and Changelog checklist in PR template
+
+- CI restructured: separate Lint job, test matrix on Python 3.10 through 3.13, PR checks (title, description, changelog) in one job
+- Dependabot PRs now auto-labeled `skip-changelog` to bypass changelog CI check
+
+## [0.0.1] - 2026-03-02
+
+### Added
+
+- Multi-turn conversation simulation with configurable scenarios
+- Quantitative and qualitative evaluation metrics
+- Chat Completions and A2A agent protocol support
+- CLI (`arksim simulate`, `arksim evaluate`, `arksim simulate-evaluate`)
+- Python SDK with `run_simulation()` and `run_evaluation()`
+- Parallel execution with configurable worker count
+- Example setups for e-commerce and bank insurance use cases
+- OpenAI, Anthropic, Google Gemini, and Azure OpenAI provider support
+- HTML report generation for evaluation results
+
+[Unreleased]: https://github.com/arklexai/arksim/compare/v0.0.1...HEAD
+[0.0.1]: https://github.com/arklexai/arksim/releases/tag/v0.0.1

arksim-0.0.2/CODE_OF_CONDUCT.md

@@ -0,0 +1,42 @@
+# 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, caste, color, 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:
+
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints and experiences
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the community
+- Showing empathy towards other community members
+
+Examples of unacceptable behavior:
+
+- 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 without explicit permission
+- Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the project maintainers at **support@arklex.ai**. All complaints will
+be reviewed and investigated promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the
+[Contributor Covenant](https://www.contributor-covenant.org/), version 2.1.