jvagent 0.1.1__tar.gz

jvagent-0.1.1/.env.example

@@ -0,0 +1,279 @@
+# jvagent Environment Configuration Template
+# Copy to .env and fill in your values. Never commit .env to version control.
+# Overrides app.yaml; env vars take precedence. See app.yaml config section for defaults.
+
+# ============================================================================
+# REQUIRED SECRETS (production)
+# ============================================================================
+
+# JWT Secret (CHANGE IN PRODUCTION!)
+# Generate: openssl rand -hex 32
+JVSPATIAL_JWT_SECRET_KEY=your-jwt-secret-key-change-in-production
+
+# Admin bootstrap (required to create initial admin user)
+JVAGENT_ADMIN_PASSWORD=your-admin-password-here
+
+# OpenAI API Key — OpenAI-compatible APIs and PageIndex tree search.
+OPENAI_API_KEY=your-openai-api-key-here
+# Legacy alias supported as fallback only:
+
+# Ollama Cloud / hosted Ollama
+OLLAMA_API_KEY=your-ollama-api-key-here
+OLLAMA_API_ENDPOINT=your-ollama-compatible-api-endpoint-here
+OLLAMA_MODEL=your-ollama-model
+
+# Secrets are read from environment only.
+# Secret-like keys in agent.yaml context are ignored with a warning.
+
+# Typesense API Key (for vector store actions)
+TYPESENSE_API_KEY=your-typesense-api-key-here
+
+# ============================================================================
+# ADMIN BOOTSTRAP
+# ============================================================================
+# JVAGENT_ADMIN_USERNAME=admin
+# JVAGENT_ADMIN_EMAIL=admin@jvagent.example
+
+# ============================================================================
+# ACTION LOADING (production)
+# ============================================================================
+# When true, skip pip install for action info.yaml dependencies.pip (use image/requirements instead)
+# JVAGENT_DISABLE_RUNTIME_PIP_INSTALL=false
+
+# When true, load_app_config() re-raises if app.yaml config cannot be loaded (fail-fast for CI)
+# JVAGENT_STRICT_CONFIG=false
+
+# When true, log a warning for every ${VAR} in YAML that resolves to an empty string (optional placeholders stay quiet by default)
+# JVAGENT_WARN_EMPTY_PLACEHOLDERS=false
+
+# ============================================================================
+# SERVER
+# ============================================================================
+# JVAGENT_APP_ID=              # Unique app identifier (overrides app node's app_id when set)
+# JVAGENT_HOST=127.0.0.1
+# JVAGENT_PORT=8000
+# JVAGENT_TITLE=jvagent API
+# JVAGENT_DESCRIPTION=jvagent Agentive Platform API
+# JVAGENT_VERSION=0.0.1
+
+# Public origin for webhooks, OAuth callbacks, and absolute media URLs (WhatsApp, Facebook Messenger, Google)
+# Example: https://your-app.example.com or http://localhost:8000
+# JVAGENT_PUBLIC_BASE_URL=https://your-app.example.com
+
+# ============================================================================
+# DATABASE
+# ============================================================================
+# JVSPATIAL_DB_TYPE=json
+# JVSPATIAL_DB_PATH=./jvagent_db
+# (Do not use JVSPATIAL_JSONDB_PATH / JVSPATIAL_SQLITE_PATH — forbidden by jvspatial.)
+
+# MongoDB
+# JVSPATIAL_MONGODB_URI=mongodb://localhost:27017
+# JVSPATIAL_MONGODB_DB_NAME=jvagent_db
+# JVSPATIAL_MONGODB_MAX_POOL_SIZE=10
+# JVSPATIAL_MONGODB_MIN_POOL_SIZE=0
+
+# DynamoDB (AWS Lambda / serverless)
+# JVSPATIAL_DYNAMODB_TABLE_NAME=jvspatial
+# JVSPATIAL_DYNAMODB_REGION=us-east-1
+# JVSPATIAL_DYNAMODB_ENDPOINT_URL=
+# AWS_ACCESS_KEY_ID=
+# AWS_SECRET_ACCESS_KEY=
+
+# ============================================================================
+# LOGGING DATABASE (jvspatial: JVSPATIAL_DB_LOGGING_* / JVSPATIAL_LOG_DB_*)
+# ============================================================================
+# JVSPATIAL_DB_LOGGING_ENABLED=true
+# JVSPATIAL_DB_LOGGING_LEVELS=INTERACTION,ERROR,CRITICAL
+# JVSPATIAL_LOG_DB_TYPE=mongodb
+# JVSPATIAL_LOG_DB_URI=mongodb://localhost:27017
+# JVSPATIAL_LOG_DB_NAME=jvagent_logs
+# JVSPATIAL_LOG_DB_PATH=./jvagent_logs
+# JVSPATIAL_LOG_RETENTION_DEFAULT_DAYS=60  # Log retention in days (0 = indefinite); shared with jvspatial load_env
+
+# DynamoDB logging (when JVSPATIAL_LOG_DB_TYPE=dynamodb)
+# JVSPATIAL_LOG_DB_TABLE_NAME=jvagent_logs
+# JVSPATIAL_LOG_DB_REGION=us-east-1
+# JVSPATIAL_LOG_DB_ENDPOINT_URL=
+
+# ============================================================================
+# AUTHENTICATION
+# ============================================================================
+# JVAGENT_AUTH_ENABLED=true
+# JVSPATIAL_JWT_EXPIRE_MINUTES=60
+# JVAGENT_API_KEY_MANAGEMENT_ENABLED=true
+# JVAGENT_API_KEY_PREFIX=jv_
+# JVAGENT_API_KEY_HEADER=x-api-key
+
+# ============================================================================
+# CORS
+# ============================================================================
+# JVSPATIAL_CORS_ENABLED=true
+# JVSPATIAL_CORS_ORIGINS=http://localhost:3000,http://localhost:5173
+
+# ============================================================================
+# FILE STORAGE
+# ============================================================================
+# JVSPATIAL_FILE_STORAGE_ENABLED=false
+# Public GET for {JVSPATIAL_API_PREFIX}/files/{path} (jvspatial default: true)
+# JVSPATIAL_FILES_PUBLIC_READ=true
+# Prefer JVSPATIAL_FILE_STORAGE_PROVIDER (aligns with app.yaml file_storage.provider).
+# JVSPATIAL_FILE_STORAGE_PROVIDER=local
+# JVSPATIAL_FILES_ROOT_PATH=./.files
+# JVSPATIAL_FILE_STORAGE_BASE_URL=http://localhost:8000
+# JVSPATIAL_FILE_STORAGE_MAX_SIZE=104857600
+
+# S3 (canonical names — do not use *_REGION_NAME / *_ACCESS_KEY_ID / *_SECRET_ACCESS_KEY)
+# JVSPATIAL_S3_BUCKET_NAME=
+# JVSPATIAL_S3_REGION=us-east-1
+# JVSPATIAL_S3_ACCESS_KEY=
+# JVSPATIAL_S3_SECRET_KEY=
+# JVSPATIAL_S3_ENDPOINT_URL=
+
+# MCP filesystem sandbox (MCPAction): paths <files_root>/<agentId>/<userId>/
+# MCP_FILESYSTEM_SANDBOX_MODE=false
+# MCP_FILESYSTEM_SANDBOX_ROOT=
+# MCP_FILESYSTEM_SANDBOX_USER_SCOPED=false
+# Default user id for tool list + fulfill() when no visitor (default anonymous)
+# MCP_FILESYSTEM_SANDBOX_DEFAULT_USER=anonymous
+
+# ============================================================================
+# API
+# ============================================================================
+# Graph REST API (allowlisted JVSPATIAL_* key; see jvspatial environment-configuration.md)
+# JVSPATIAL_GRAPH_ENDPOINT_ENABLED=true
+
+# ============================================================================
+# INTERACT ENDPOINT
+# ============================================================================
+# JVAGENT_INTERACT_RATE_LIMIT_PER_MINUTE=60
+# JVAGENT_INTERACT_MAX_UTTERANCE_LENGTH=2000  # null or empty = unlimited
+# Max interaction nodes pruned per add_interaction call when over rolling limit (bounded tail latency).
+# JVAGENT_MAX_INTERACTIONS_PRUNED_PER_CALL=100
+# Cross-process serialization for conversation chain updates (recommended in multi-worker prod).
+# JVAGENT_CONVERSATION_LOCK_REDIS_URL=
+# JVAGENT_CONVERSATION_LOCK_DYNAMODB_TABLE=
+
+# ============================================================================
+# DEVELOPMENT & LOGGING
+# ============================================================================
+# JVSPATIAL_LOG_LEVEL=info
+# JVSPATIAL_DEBUG=false
+# JVSPATIAL_ENVIRONMENT=development
+
+# jvspatial serverless override (optional; Lambda/Cloud Run etc. auto-detected).
+# See jvspatial docs: serverless-mode.md
+# SERVERLESS_MODE=true
+
+# ============================================================================
+# WHATSAPP INTEGRATION
+# ============================================================================
+# WHATSAPP_API_URL=http://your-whatsapp-provider:21000
+# WHATSAPP_API_KEY=your-whatsapp-api-key-here
+# WHATSAPP_SESSION=your-session-id-here
+# WHATSAPP_TOKEN=your-token-here
+# WHATSAPP_SESSION_REGISTER_TIMEOUT_SECONDS=120
+# WHATSAPP_SKIP_STARTUP_REGISTRATION=false
+# WHATSAPP_REQUEST_TIMEOUT=15
+# Work-claim lease TTL for persistent batches (seconds); see jvspatial serverless-mode.md
+# JVSPATIAL_WORK_CLAIM_STALE_SECONDS=600
+
+# Serverless / LWA: deferred tasks hit POST {JVSPATIAL_API_PREFIX}/_internal/deferred (default /api/_internal/deferred).
+# Optional: AWS_LWA_INVOKE_MODE=RESPONSE_STREAM and AWS_LWA_PASS_THROUGH_PATH=/api/_internal/deferred (see jvspatial serverless-mode.md).
+
+# EventBridge scheduler: JVSPATIAL_EVENTBRIDGE_SCHEDULER_ENABLED defaults to true on serverless AWS; set false for Lambda invoke only.
+# JVSPATIAL_EVENTBRIDGE_ROLE_ARN=arn:aws:iam::...  # required for schedules to succeed
+# JVSPATIAL_EVENTBRIDGE_LAMBDA_ARN=arn:aws:lambda:...
+# If JVSPATIAL_EVENTBRIDGE_LAMBDA_ARN unset, ARN built from AWS_LAMBDA_FUNCTION_NAME + AWS_REGION + AWS_ACCOUNT_ID:
+# AWS_REGION=us-east-1
+# AWS_ACCOUNT_ID=123456789012
+# JVSPATIAL_EVENTBRIDGE_SCHEDULER_GROUP=default
+
+# ============================================================================
+# EMAIL (EmailAction — package jvagent/email_action: gmail | sendgrid)
+# ============================================================================
+# Gmail (default): add GoogleGmailAction on the same agent; OAuth via:
+# GOOGLE_CLIENT_SECRETS_JSON=   # path or JSON string (same as other Google actions)
+# Optional override From (else Gmail profile emailAddress):
+# EMAIL_DEFAULT_SENDER=
+# EMAIL_DEFAULT_SENDER_NAME=
+# SendGrid: set provider=sendgrid on EmailAction
+# SENDGRID_API_KEY=
+# SENDGRID_API_BASE_URL=https://api.sendgrid.com/v3
+# SENDGRID_FROM_EMAIL=   # optional fallback if EMAIL_DEFAULT_SENDER unset
+# SENDGRID_FROM_NAME=
+
+# ============================================================================
+# TTS / STT
+# ============================================================================
+# TTS_API_KEY=your-tts-api-key-here
+# STT_API_KEY=your-stt-api-key-here
+
+# ============================================================================
+# WEBHOOK (jvspatial)
+# ============================================================================
+# JVSPATIAL_WEBHOOK_HMAC_SECRET=
+# JVSPATIAL_WEBHOOK_HMAC_ALGORITHM=sha256
+# JVSPATIAL_WEBHOOK_MAX_PAYLOAD_SIZE=1048576
+# JVSPATIAL_WEBHOOK_IDEMPOTENCY_TTL=3600
+# JVSPATIAL_WEBHOOK_HTTPS_REQUIRED=true
+
+# ============================================================================
+# PAGEINDEX (document indexing/retrieval)
+# ============================================================================
+# JVAGENT_PAGEINDEX_DB_TYPE=json
+# JVAGENT_PAGEINDEX_DB_PATH=./pageindex_db
+# JVAGENT_PAGEINDEX_DB_NAME=pageindex_db
+# Default when unset: {app_id}_pageindex_db (one db per app, agents share it)
+# JVAGENT_PAGEINDEX_DB_ROOT=.   # Root for path when DB_PATH not set
+# MongoDB/DynamoDB (when DB_TYPE is mongodb/dynamodb):
+# JVAGENT_PAGEINDEX_DB_URI=mongodb://localhost:27017
+# When unset/blank, Pageindex uses JVSPATIAL_MONGODB_URI, then mongodb://localhost:27017
+# JVAGENT_PAGEINDEX_DB_TABLE_NAME=
+# JVAGENT_PAGEINDEX_DB_REGION=us-east-1
+
+# ============================================================================
+# JVSPATIAL CACHE (entity cache)
+# ============================================================================
+# JVSPATIAL_CACHE_BACKEND=memory
+# JVSPATIAL_CACHE_SIZE=1000
+# JVSPATIAL_L1_CACHE_SIZE=500
+# JVSPATIAL_REDIS_URL=redis://localhost:6379
+# JVSPATIAL_REDIS_TTL=3600
+
+# ============================================================================
+# PERFORMANCE (jvagent)
+# ============================================================================
+# JVAGENT_ENABLE_PROFILING=false
+# JVAGENT_ENABLE_AGENT_CACHE=true
+# JVAGENT_AGENT_CACHE_TTL=300
+# JVAGENT_ENABLE_ACTION_CACHE=true
+# JVAGENT_ACTION_CACHE_TTL=60
+# JVAGENT_ENABLE_DSPY_CACHE=false
+# JVAGENT_CACHE_CLEANUP_PROBABILITY=0.1
+# JVAGENT_ENABLE_INTERACT_ROUTER_CACHE=false
+# JVAGENT_INTERACT_ROUTER_CACHE_TTL=45
+
+# ============================================================================
+# JVSPATIAL_* (framework keys used by jvagent)
+# ============================================================================
+# Set only names documented in docs/environment-keys-reference.md and jvspatial
+# docs/md/environment-keys-reference.md. For file storage use JVSPATIAL_FILE_STORAGE_PROVIDER;
+# for public webhook/OAuth URLs use JVAGENT_PUBLIC_BASE_URL.
+
+# ============================================================================
+# JVSPATIAL PERFORMANCE
+# ============================================================================
+# Batch saves (ignored when serverless / SERVERLESS_MODE — see jvspatial deferred_saves_globally_allowed)
+# JVSPATIAL_ENABLE_DEFERRED_SAVES=true
+
+
+# jvforge (PageIndex delegated ingest): base URL of the jvforge service (e.g. http://127.0.0.1:8088)
+# JVAGENT_JVFORGE_BASE_URL=http://127.0.0.1:8088
+# Optional API key only if jvforge has JVFORGE_API_KEY set
+# JVAGENT_JVFORGE_API_KEY=
+# JVFORGE_API_KEY=
+# When true, ingest uses jvforge POST /v1/jobs (async queue) instead of synchronous /v1/process
+# JVAGENT_JVFORGE_ASYNC=false
+# Webhook path: set JVAGENT_PUBLIC_BASE_URL so PageIndex interact webhook URLs are reachable from jvforge.
+# Align JVFORGE_PUBLIC_BASE_URL on the jvforge side with a host jvagent can use to GET artifacts (often same as JVAGENT_JVFORGE_BASE_URL for local dev).

jvagent-0.1.1/AUTHORS

@@ -0,0 +1,15 @@
+jvagent — Authors & Maintainers
+===============================
+
+jvagent is an agent harness built on jvspatial.
+
+Creator & Lead Maintainer
+  Eldon Marks (@eldonm) — https://github.com/eldonm
+
+Contributors
+  This list grows with the project. Contributions are welcome.
+
+---------------------------------------------------------------------
+This file records authorship and ongoing maintenance of the project.
+Authorship and maintenance are distinct from copyright ownership and
+license terms, which are set out in LICENSE.

jvagent-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 TrueSelph Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

jvagent-0.1.1/MANIFEST.in

@@ -0,0 +1,23 @@
+include README.md
+include LICENSE
+include pyproject.toml
+include .env.example
+recursive-include jvagent *.py
+
+# Action + skill data — every action package ships an `info.yaml` (the
+# action loader walks these to discover core actions at runtime), every
+# skill bundle ships a `SKILL.md`, and some packages ship per-package
+# READMEs or pinned `requirements.txt` files. Without these, non-editable
+# wheel installs cannot discover any core action and emit
+# "Action jvagent/<x> not found locally or in core library" warnings.
+recursive-include jvagent *.yaml
+recursive-include jvagent *.yml
+recursive-include jvagent *.md
+recursive-include jvagent *.json
+recursive-include jvagent requirements.txt
+recursive-include jvagent/scaffold/static *.txt
+
+# Bundled jvchat UI (built by scripts/build_jvchat.py; served by `jvagent chat`).
+recursive-include jvagent/webui/dist *
+
+recursive-include docs *.md