agenticstar-platform 0.5.19

AGENTICSTAR Platform SDK - Enterprise AI Agent Infrastructure

AGENTICSTAR Platform SDK

Enterprise AI Agent Infrastructure SDK for building autonomous agent systems.

Installation

# Core (minimal)
pip install agenticstar-platform

# With specific modules
pip install agenticstar-platform[db]           # PostgreSQL
pip install agenticstar-platform[rag]          # Qdrant + Embedding
pip install agenticstar-platform[storage]      # Azure Blob, S3, GCS
pip install agenticstar-platform[storage-azure] # Azure Blob only
pip install agenticstar-platform[memory]       # Semantic memory (Mem0)
pip install agenticstar-platform[security]     # PII detection
pip install agenticstar-platform[webhook]      # aiohttp (WebhookEventHandler)
pip install agenticstar-platform[all]          # All modules

Quick Start

from agenticstar_platform import (
    # Database
    PostgreSQLManager, ApiPostgreSQLManager, PostgreSQLConfig, DataAccess,
    # RAG (Vector DB + Embedding)
    QdrantManager, QdrantConfig, EmbeddingGenerator, EmbeddingConfig,
    # Storage
    AzureBlobStorageClient, AzureBlobConfig,
    # Events
    EventEmitter, EventType,
    # Auth
    AgenticStarAuthClient, AgenticStarAuthConfig,
    # Memory
    SemanticMemoryClient, SemanticMemoryConfig,
)

# Example: Initialize SDK components
async def main():
    # Database (direct connection)
    db_config = PostgreSQLConfig.from_toml("config.toml", section="database")
    manager = PostgreSQLManager(db_config)
    da = DataAccess(manager)
    await da.initialize()
    users = await da.fetch_all("SELECT * FROM users WHERE active = $1", (True,))

    # Database (HTTP API)
    db_config = PostgreSQLConfig(api_url="https://your-api.example.com/db")
    manager = ApiPostgreSQLManager(db_config, token_provider=lambda: "your-token")
    da = DataAccess(manager)
    users = await da.fetch_all("SELECT * FROM users WHERE active = $1", (True,))

    # RAG System
    embedding_config = EmbeddingConfig.from_toml("config.toml", section="rag.embedding")
    embedding_gen = EmbeddingGenerator(embedding_config)

    qdrant_config = QdrantConfig.from_toml("config.toml", section="rag.qdrant")
    async with QdrantManager(qdrant_config, embedding_gen) as qdrant:
        results = await qdrant.search("How to use the SDK?", limit=5)

    # Storage (uses from_dict, not from_toml)
    storage_config = AzureBlobConfig.from_dict({
        "bucket_name": "your-container",
        "connection_string": "your-connection-string",
    })
    storage = AzureBlobStorageClient(storage_config)

Modules

Module	Extra	Description
db	[db]	PostgreSQL data access layer with Azure AD support
rag	[rag]	Qdrant vector database and Azure OpenAI embedding integration
storage	[storage] / [storage-azure] / [storage-aws] / [storage-gcp]	Multi-cloud storage (Azure Blob, S3, GCS)
auth	(core)	AgenticStar Auth API client (authentication, user management, MCP tokens)
memory	[memory]	Semantic memory (Mem0 + Qdrant)
security	[security]	PII detection (Azure Presidio, AWS Bedrock Guardrails / Comprehend, GCP DLP)
events	(core)	Event type definitions for streaming
common	(core)	Shared utilities (secret masking, validation)

Auth Module

from agenticstar_platform.auth import AgenticStarAuthClient, AgenticStarAuthConfig

# From config.toml [auth.agenticstar] section
config = AgenticStarAuthConfig.from_config("config.toml")
client = AgenticStarAuthClient(config)

# Get user info
user = await client.get_user(user_id="user-001")

# Get MCP tokens
tokens = await client.get_mcp_tokens(user_id="user-001")

Memory Module

Semantic memory powered by Mem0 + Qdrant (requires pip install agenticstar-platform[memory]):

from agenticstar_platform.memory import SemanticMemoryClient, SemanticMemoryConfig

config = SemanticMemoryConfig.from_toml("config.toml")
memory = SemanticMemoryClient(config)

# Add memory (methods are synchronous; only cleanup() is async)
memory.add(
    [{"role": "user", "content": "User prefers dark mode"}],
    user_id="user-001",
)

# Search memory
results = memory.search("user preferences", user_id="user-001")

Storage Module

Note: AzureBlobConfig uses from_dict() (not from_toml()):

from agenticstar_platform.storage import AzureBlobStorageClient, AzureBlobConfig

config = AzureBlobConfig.from_dict({
    "bucket_name": "your-container",
    "connection_string": "DefaultEndpointsProtocol=https;...",
    "prefix": "uploads/",
})
client = AzureBlobStorageClient(config)
result = await client.upload_file("local/file.pdf", prefix="docs/")

Telemetry / LLM Usage Tracking (Marketplace)

TelemetryAccess (under db module) writes records to the ai_telemetry table. Unknown fields are stored in the metadata jsonb column automatically — no schema migration is required to add new tracking dimensions.

For Marketplace agents that wrap LLM calls, the SDK defines recommended field names for token and model usage. Following this convention enables cross-agent cost / utilization analytics in shared dashboards.

from agenticstar_platform.db import TelemetryAccess

telemetry = TelemetryAccess(data_access)

# After an LLM call from your custom agent:
response = await openai_client.chat.completions.create(...)

await telemetry.save_telemetry({
    "conversation_id": conversation_id,
    "agent_type": "my_marketplace_agent",
    "service": "my-agent-service",
    "operation": "generate_response",
    "duration_ms": elapsed_ms,
    "success": True,

    # Recommended convention fields (stored automatically in metadata jsonb)
    "prompt_tokens": response.usage.prompt_tokens,
    "completion_tokens": response.usage.completion_tokens,
    "total_tokens": response.usage.total_tokens,
    "model": "azure/gpt-4.1",  # LiteLLM-style identifier
})

Recommended convention fields

Field	Type	Source	Notes
prompt_tokens	int	usage.prompt_tokens (OpenAI / LiteLLM compatible)	Input tokens
completion_tokens	int	usage.completion_tokens	Output tokens
total_tokens	int	usage.total_tokens	Sum
model	str	LiteLLM-style: azure/gpt-4.1, bedrock/anthropic.claude-3-5-sonnet, openai/gpt-4o, etc.	Provider/model identifier

These fields are not known columns — they land in metadata jsonb automatically. No SDK code change, no DB schema migration. Use the recommended names so that your data joins with platform-level analytics.

Cross-agent analytics example

-- Per-model token usage in the last 30 days
SELECT
  metadata->>'model' AS model,
  agent_type,
  SUM((metadata->>'prompt_tokens')::int)     AS total_prompt_tokens,
  SUM((metadata->>'completion_tokens')::int) AS total_completion_tokens,
  COUNT(*)                                    AS invocations,
  AVG(duration_ms)::int                       AS avg_duration_ms
FROM ai_telemetry
WHERE timestamp > NOW() - INTERVAL '30 days'
  AND metadata ? 'prompt_tokens'
GROUP BY model, agent_type
ORDER BY total_prompt_tokens DESC;

Updated in SDK ≥ 0.5.15: Cost conversion is no longer out of scope. The new Metering module (UsageMeter) below computes cost via a pluggable engine (litellm by default — its community-maintained price map solves the "changes too frequently" problem; graceful NULL when litellm is absent). TelemetryAccess remains the place for agent operational telemetry (intent / tools / duration → ai_telemetry); UsageMeter is the dedicated per-LLM-call cost ledger. Use whichever fits; they are complementary.

Metering Module — UsageMeter (SDK ≥ 0.5.15)

Dedicated LLM usage & cost infrastructure: computes cost from an LLM response/usage and records one row per call to llm_usage_ledger, with a daily rollup (llm_usage_daily) and cost-visualization queries. Pure infra — agent-logic agnostic, identical for self-hosted and Marketplace BYO (in-process; no proxy/header coupling).

• Pluggable cost: default uses litellm (completion_cost / cost_per_token) — reflects long-context, prompt-cache and tier pricing. If litellm is absent, tokens are still recorded (cost_usd = NULL). Pass cost_fn=... to override.
• DB: any handle exposing execute_query(query, params) -> {success, data, error} (the SDK's DataAccess / PostgreSQLManager).

from agenticstar_platform.metering import UsageMeter

meter = UsageMeter(db=data_access)
await meter.ensure_schema()                        # create ledger/daily/rollup if absent (idempotent)

# Record one LLM call (cost computed automatically; fire-and-forget safe)
await meter.record(
    model="gpt-5.5", response=resp, endpoint="chat/completions",
    labels={"execution_id": eid, "message_id": mid, "conversation_id": cid, "user_id": uid},
)

# ...or wrap the call so it records on completion
resp = await meter.track(model="gpt-5.5", labels=ids)(litellm.acompletion)(**params)

# Cost only (no record)
usd = UsageMeter.cost_usd("gpt-5.5", response=resp)

# Daily rollup + cost visualization (for dashboards / billing)
await meter.rollup_recent()
rows = await meter.daily_cost(by="model", since_days=30)   # by = "model" | "user" | "agent" | "day"

Schema (ensure_schema): llm_usage_ledger — one row per call (execution / message / conversation / user, model, in/out/total/cached tokens, cost_usd, currency) — plus llm_usage_daily (rollup) and rollup_llm_usage_daily(day). The default DDL is portable (any PostgreSQL); at scale, partition llm_usage_ledger monthly (e.g. pg_partman).

Platform Class Example

Below is an example of a Platform class that wraps SDK components for your agent system:

"""
Platform class example - Using AGENTICSTAR Platform SDK
"""
import asyncio
from dataclasses import dataclass
from typing import Optional

from agenticstar_platform import (
    PostgreSQLManager, PostgreSQLConfig, DataAccess,
    QdrantManager, QdrantConfig,
    EmbeddingGenerator, EmbeddingConfig,
    EventEmitter, EventType,
    SemanticMemoryClient, SemanticMemoryConfig,
    AzureBlobStorageClient, AzureBlobConfig,
    AgenticStarAuthClient, AgenticStarAuthConfig,
)


@dataclass
class PlatformConfig:
    """Platform configuration"""
    db_config: PostgreSQLConfig
    qdrant_config: QdrantConfig
    embedding_config: EmbeddingConfig
    storage_config: Optional[AzureBlobConfig] = None
    memory_config: Optional[SemanticMemoryConfig] = None
    auth_config: Optional[AgenticStarAuthConfig] = None

    @classmethod
    def from_toml(cls, path: str) -> "PlatformConfig":
        """Load all configurations from TOML file"""
        return cls(
            db_config=PostgreSQLConfig.from_toml(path, section="database"),
            qdrant_config=QdrantConfig.from_toml(path, section="rag.qdrant"),
            embedding_config=EmbeddingConfig.from_toml(path, section="rag.embedding"),
            storage_config=AzureBlobConfig.from_dict({
                # Load from environment or config
                "bucket_name": "your-container",
                "connection_string": "your-connection-string",
            }),
            auth_config=AgenticStarAuthConfig.from_config(path),
        )


class AgentPlatform:
    """
    Platform class wrapping SDK components.

    Example:
        >>> config = PlatformConfig.from_toml("config.toml")
        >>> platform = AgentPlatform(config)
        >>> await platform.initialize()
        >>>
        >>> # Use database
        >>> users = await platform.db.fetch_all("SELECT * FROM users")
        >>>
        >>> # Use RAG
        >>> results = await platform.search_knowledge("How to deploy?")
        >>>
        >>> # Clean up
        >>> await platform.cleanup()
    """

    def __init__(self, config: PlatformConfig):
        self.config = config
        self._db: Optional[DataAccess] = None
        self._qdrant: Optional[QdrantManager] = None
        self._embedding: Optional[EmbeddingGenerator] = None
        self._storage: Optional[AzureBlobStorageClient] = None
        self._memory: Optional[SemanticMemoryClient] = None
        self._auth: Optional[AgenticStarAuthClient] = None

    async def initialize(self) -> None:
        """Initialize all SDK components"""
        # Database
        db_manager = PostgreSQLManager(self.config.db_config)
        self._db = DataAccess(db_manager)
        await self._db.initialize()

        # Embedding generator
        self._embedding = EmbeddingGenerator(self.config.embedding_config)

        # Vector DB (RAG)
        self._qdrant = QdrantManager(self.config.qdrant_config, self._embedding)
        await self._qdrant.initialize()

        # Storage (optional)
        if self.config.storage_config:
            self._storage = AzureBlobStorageClient(self.config.storage_config)

        # Memory (optional)
        if self.config.memory_config:
            self._memory = SemanticMemoryClient(self.config.memory_config)

        # Auth (optional)
        if self.config.auth_config:
            self._auth = AgenticStarAuthClient(self.config.auth_config)

    @property
    def db(self) -> DataAccess:
        if not self._db:
            raise RuntimeError("Platform not initialized. Call initialize() first.")
        return self._db

    @property
    def qdrant(self) -> QdrantManager:
        if not self._qdrant:
            raise RuntimeError("Platform not initialized. Call initialize() first.")
        return self._qdrant

    @property
    def storage(self) -> Optional[AzureBlobStorageClient]:
        return self._storage

    @property
    def memory(self) -> Optional[SemanticMemoryClient]:
        return self._memory

    @property
    def auth(self) -> Optional[AgenticStarAuthClient]:
        return self._auth

    async def search_knowledge(self, query: str, limit: int = 10):
        return await self.qdrant.search(query, limit=limit)

    async def cleanup(self) -> None:
        """Clean up all resources"""
        if self._qdrant:
            await self._qdrant.close()
        if self._db:
            await self._db.close()
        if self._storage:
            await self._storage.close()
        if self._memory:
            await self._memory.cleanup()

Configuration (config.toml example)

[database]
host = "your-postgresql.postgres.database.azure.com"
port = 5432
database = "agenticai"
username = "admin"
password = "your-password"
use_azure_ad = false
pool_min_size = 2
pool_max_size = 10
# api_url = "https://your-api.example.com/db"  # Set for HTTP API mode

[database.azure_ad]
tenant_id = "your-tenant-id"
client_id = "your-client-id"
client_secret = "your-client-secret"

[auth.agenticstar]
base_url = "https://auth.agenticstar.tm.softbank.jp"
api_key = ""
timeout = 30.0
max_retries = 3

[rag.embedding]
api_base = "https://your-openai.openai.azure.com/"
api_key = "your-api-key"
deployment_name = "text-embedding-ada-002"

[rag.qdrant]
url = "http://localhost:6333"
collection_name = "knowledge_base"
vector_size = 1536

[storage.azure]
bucket_name = "your-container"
connection_string = "DefaultEndpointsProtocol=https;..."
prefix = "uploads/"

[memory.llm]
model = "azure/gpt-4"
api_key = "your-api-key"
base_url = "https://your-openai.openai.azure.com/"
api_version = "2024-02-15-preview"

[memory.embedder]
model = "azure/text-embedding-ada-002"
api_key = "your-api-key"
base_url = "https://your-openai.openai.azure.com/"
api_version = "2024-02-15-preview"

API Reference

See API_REFERENCE.md for detailed API documentation.

Changelog

0.5.19 (2026-06-20)

Metering cost-accuracy fixes (cache-aware). Supersedes 0.5.18.

• default_cost_fn fallback applies prompt-cache pricing — passes cache_read_input_tokens / cache_creation_input_tokens to litellm.cost_per_token when completion_cost(response) is unavailable, so cache-heavy calls are no longer priced at the full input rate.
• extract_usage covers Responses API + cache-creation — reads cached_tokens from input_tokens_details (Responses) as well as prompt_tokens_details (Chat), and propagates cache_creation_input_tokens (Anthropic). Previously cached tokens on Responses calls were missed on the token-only/fallback path. No public API change.

0.5.17 (2026-06-19)

• Security: AWS PII detection now defaults to Bedrock Guardrails (multilingual) — AWSSecurityConfig gains a pii_service field ("bedrock_guardrails" default / "comprehend" legacy). AWS detect_pii() routes through Bedrock Guardrails sensitiveInformationPolicy by default, fixing multilingual (including Japanese) PII masking — Amazon Comprehend DetectPiiEntities only supports en / es (previously ja etc. slipped through and raised a ValidationException). ⚠️ Behavior change: with the new default, AWS PII requires guardrail_id to be set (otherwise it returns NOT_CONFIGURED); set pii_service="comprehend" to keep the legacy en/es path. Configs that already set pii_service explicitly are unaffected.

0.5.16 (2026-06-14)

Marketplace SDK reliability fixes (surfaced while building agents from the guides alone):

• Config: from_toml() resolves ${ENV} placeholders and uses the stdlib tomllib (no external toml dependency). host = "${POSTGRESQL_HOST}"-style values in config.toml are expanded from the environment; unresolved placeholders are left intact. Supports ${VAR} and ${VAR:-default}.
• Memory: mem0 2.x compatibility — SemanticMemoryClient.search() / get_all() now use mem0 2.x filters / top_k internally (the public user_id / limit arguments are unchanged). Azure gpt-5.x / o-series memory models no longer fail with max_tokens is not supported (the unsupported parameter is suppressed; the real Azure deployment is still targeted). mem0ai is pinned to >=2.0.0,<3.0.0.
• Events: EventEmitter.drain() — drives registered handlers (e.g. the marketplace webhook handler) for non-SSE flows. emit_event(...) only enqueues; without an SSE consume_events() loop, call drain() so handlers actually fire (previously emit + cleanup silently dropped events). The [webhook] extra now includes aiohttp (required by WebhookEventHandler); [all] includes it too.
• Storage: StoragePaths.input_uploads_prefix(user_id, conversation_id, message_id) — builds the owner-scoped prefix (users/{user_id}/uploads/{conv}/{msg}) for input attachments uploaded from the chat UI. Use with download_objects_by_prefix.
• Runtime: wait_for_egress() — waits for the egress sidecar to accept connections before the first outbound call, avoiding a startup race that could skip first-turn input moderation / PII.
• PodRuntime: injectable self scale-down — PodRuntime(..., scale_down_callback=...); when omitted and no bundled scaler is present, scale-down is skipped cleanly instead of raising No module named 'src'.

0.5.15 (2026-06-13)

• New: Metering module (UsageMeter) — dedicated LLM usage & cost ledger. meter.record(...) computes cost from a response/usage and writes one row per call to llm_usage_ledger; rollup_recent() / daily_cost(...) provide daily aggregation and cost-visualization queries; ensure_schema() creates the (portable) tables/rollup function idempotently. Cost is pluggable — default default_cost_fn uses litellm if installed (long-context / cache / tier aware), gracefully records tokens-only (cost_usd = NULL) when litellm is absent, and cost_fn= overrides. Agent-logic agnostic; identical for self-hosted and Marketplace BYO. Exports: UsageMeter, default_cost_fn, extract_usage.

0.5.7 (2026-05-10)

• Security: PII confidence threshold per-call — detect_pii() now accepts an optional confidence_threshold parameter on Azure / AWS / GCP clients (and the SecurityClientProtocol / SecurityClientBase). Passing None falls back to the value in *SecurityConfig.pii_confidence_threshold. This lets a single long-lived SecurityClient instance serve callers that need different thresholds, instead of constructing a new client per request. Backward compatible — existing callers that omit the new argument get the previous behavior.
• Security: GCP threshold now respects config — GCPSecurityClient.detect_pii() previously hardcoded a LIKELY (likelihood ≥ 4) cutoff and ignored GCPSecurityConfig.pii_confidence_threshold. It now compares likelihood / 5.0 against the configured threshold, matching Azure / AWS behavior. With the default pii_confidence_threshold = 0.7 the effective cutoff stays at likelihood ≥ 4, so most callers see no change. Callers that had set pii_confidence_threshold below 0.7 will start seeing additional POSSIBLE (likelihood 3) findings.
• Reuse the client to avoid leaks — AzureSecurityClient (and AWS/GCP equivalents) hold an httpx.AsyncClient (TLS context + connection pool) internally. Construct one client per process and call await client.close() on shutdown (or use async with); creating a new client per request without closing leaks resources.

0.5.2 (2026-03-28)

• Memory: Removed episodic memory (Graphiti/FalkorDB) — episodic.py was unused dead code. SDK now provides semantic memory (Mem0) only.
• Extras: [semantic] / [episodic] replaced with [memory] — unified extra for Mem0-based semantic memory.
• Extras: [all] no longer includes graphiti-core[falkordb].
• README updated to reflect episodic memory removal.

0.5.0 (2026-03-25)

Breaking Changes:

• DB: DataAccess now takes a manager instance instead of (config, use_proxy, token_provider). Callers create PostgreSQLManager or ApiPostgreSQLManager and pass it directly.
• DB: use_proxy parameter removed from DataAccess, create_postgresql_manager().
• DB: api_proxy_url renamed to api_url in PostgreSQLConfig.
• DB: ApiPostgreSQLManager exported as public API for HTTP API access.

Improvements:

• DB: is_initialized() method added to both PostgreSQLManager and ApiPostgreSQLManager.
• Qdrant: prefer_grpc / check_compatibility are now explicit QdrantConfig fields (no longer hardcoded based on auth_token_provider).
• Error messages no longer reference use-case specific terms (CLI/Desktop mode).

0.4.0 (2026-03-21)

• Security: Prompt Shield documents trimming - check_prompt_shield() now trims each document to 10,000 characters to comply with Azure API limits. Previously, WebFetch results exceeding 10,000 characters were blocked even without violations.
• Security: PII detection language support - detect_pii() now accepts a language parameter (default: "ja") for accurate multi-language PII detection. Previously hardcoded to Japanese.
• Security: Protocol/ABC updated - SecurityClientProtocol and SecurityClientBase updated with language parameter in detect_pii().

0.3.2

• Storage module: Multi-cloud support (Azure Blob, S3, GCS)
• Auth module: AgenticStar Auth API client
• Memory module: Semantic memory (Mem0)

Version

0.5.16