shiftaiagenticinfra-sdk-python 0.0.12

Shiftai Agentic Infra Python SDK

Shiftai Agentic Infra Python SDK

This SDK is the official gateway to the Shift AI Agentic Infra services, enabling developers to directly integrate and use agentic capabilities in their applications.

About ShiftAI

ShiftAI is an AI infrastructure and consulting company focused on building production-ready AI systems that help organizations transform business operations using AI.

ShiftAI works with enterprises and product teams to design, integrate, and deploy AI-driven systems that move beyond experimentation into real-world production.

---

Official ShiftAI Links

• 🌐 Website: https://theshiftai.in
• 🐙 GitHub Organization: https://github.com/shiftaitop
• 💼 LinkedIn (Company): https://www.linkedin.com/company/theshiftai-in/
• 🐦 Twitter (X): https://x.com/shift_ai_first
• 🔗 Reddit: https://www.reddit.com/user/TheShiftAI/
• ✍️ Substack: https://substack.com/@shiftaifirst

Founder

• Suresh Gokarakonda
• LinkedIn: https://www.linkedin.com/in/gokarakonda/

---

About ShiftAI Agentic Infrastructure

ShiftAI Agentic Infrastructure is a multi-tenant platform for managing AI-powered conversations, agents, and workflows.

Organizations register as isolated tenants and receive secure API keys for access. The platform automatically manages conversation sessions, threads messages between humans and agents, and maintains complete conversation history.

It supports multiple LLM providers through a pluggable architecture, enabling provider switching without application-level changes.

On every interaction, the platform generates AI-enhanced contextual prompts derived from conversation history, summarizing conversation flow, key facts, and resolved ambiguities. This context is returned to clients and stored for future interactions.

The platform also includes built-in evaluation and analytics capabilities that assess response quality, relevance, and reasoning across user–agent interactions, providing visibility into conversation performance over time.

---

Platform Usage Overview

Using ShiftAI Agentic Infrastructure through this SDK, applications typically:

1. Initialize the SDK client using project credentials
2. Submit human messages to start or continue conversations
3. Receive contextual intelligence generated from conversation history
4. Generate agent responses using the provided context
5. Submit agent responses linked to prior human messages
6. Monitor conversations and performance using built-in analytics

All operations are automatically scoped to the authenticated project, ensuring secure isolation between organizations using the platform.

---

Dependencies

Allowed Dependencies (Only These)

• ✅ httpx - Async HTTP client (required for API calls)
• ✅ dataclasses - Standard library (for data models)
• ✅ typing - Standard library (for type hints)
• ✅ Standard library only: json, datetime, uuid, asyncio
• ✅ SDK internal modules - All models and utilities owned by SDK

Installation & Usage Modes

Package Usage

pip install shiftaiagenticinfra-sdk-python

Quick Start

import asyncio
from shiftai import ShiftaiagenticinfraClient

async def main():
    # 1. Initialize client
    client = ShiftaiagenticinfraClient(
        base_url="api.theshiftai.in",
        api_key="pk_your_api_key"
    )

    # 2. Send a human message
    human_response = await client.messages.send_human_message(
        username="john_doe",
        message="Hello, how can I help you?",
        agent_name="SupportBot",
        user_email="[e-mail]",  # Required for message submission
        agent_platform="OpenAI",        # Optional; when omitted, lookup uses name and project only
        agent_version="1.0.0"           # Optional; backend defaults to "1.0.0" when omitted
    )

    print(f"Message sent! ID: {human_response.messageId}")
    print(f"Org context: {human_response.orgContext}")  # Optional; may be null if org knowledge is unavailable/not configured

    # 3. Send a bot response
    bot_response = await client.messages.send_bot_message(
        username="john_doe",
        message="I can help you with your questions!",
        agent_name="SupportBot",
        reply_message_id=human_response.messageId,
        rag_context="Retrieved context from knowledge base...",
        user_email="[e-mail]",  # Required for message submission
        agent_platform="OpenAI",         # Optional
        agent_version="1.0.0"           # Optional; backend defaults to "1.0.0" when omitted
    )

    # 4. Get analytics
    dashboard = await client.analytics.get_dashboard()
    print(f"Total users: {dashboard.totalUsers}")

    # 5. Close client
    await client.close()

asyncio.run(main())

This example imports and runs immediately when the SDK source is copied into any Python project with httpx installed.

API Reference

Platform API

await platform.register(project_name, metadata=None)

Register a new project and get API key.

Parameters:

• project_name (str, required): Unique name for the project/platform (e.g., "my-chatbot", "customer-support-app")
• metadata (dict, optional): Additional project metadata (e.g., {"environment": "production", "version": "1.0"})

Return Type: PlatformRegistrationResponse

Example:

response = await client.platform.register(
    project_name="MyProject",
    metadata={"environment": "production"}
)
print(f"API Key: {response.apiKey}")

Messages API

await messages.send_human_message(...)

Send a human message with automatic user/agent creation.

Parameters:

• username (str, required): User identifier (e.g., "john_doe", "user123")
• message (str, required): The actual message content (e.g., "Hello, how can I help you?")
• agent_name (str, required): Target agent name (e.g., "SupportBot", "GPT-4")
• user_email (str, required): User's email address (required for message submission; e.g., "[e-mail]")
• agent_platform (str, optional): Agent platform/provider (e.g., "OpenAI", "Azure"). When omitted, lookup/creation use name and project only.
• user_metadata (dict, optional): Custom user attributes (e.g., {"role": "premium", "subscription": "gold"})
• intent (str, optional): Message intent classification (e.g., "question", "complaint", "request")
• entities (dict, optional): Extracted named entities (e.g., {"person": "John", "location": "New York"})
• annotations (dict, optional): Additional message annotations (e.g., {"priority": "high", "tags": ["urgent"]})
• source_event (dict, optional): Original event data from source system
• agent_version (str, optional): Agent version/model (e.g., "gpt-4", "claude-2"). Backend defaults to "1.0.0" when omitted.
• agent_metadata (dict, optional): Agent configuration data (e.g., {"temperature": 0.7, "max_tokens": 1000})
• mode (str, optional): Mode identifier for the message. Allowed values: "SIMPLE" or "EXPAND"
• conversation_id (UUID, optional): Conversation ID to store the HUMAN message in. If omitted, backend creates a new conversation automatically.

Return Type: PlatformMessageSubmissionResponse

await messages.send_bot_message(...)

Send a bot response to a human message.

Parameters:

• username (str, required): User identifier (must match the human message sender)
• message (str, required): Bot response content (e.g., "I can help you with that!")
• agent_name (str, required): Agent name (must match the human message agent)
• reply_message_id (UUID, required): ID of the human message being replied to
• rag_context (str, required): RAG context used for generating the response
• user_email (str, required): User's email address (required for message submission)
• agent_platform (str, optional): Agent platform (must match the human message when provided). When omitted, lookup uses name and project only.
• user_metadata (dict, optional): User metadata
• intent (str, optional): Response intent
• entities (dict, optional): Extracted entities from response
• annotations (dict, optional): Response annotations
• source_event (dict, optional): Source event data
• agent_version (str, optional): Agent version/model. Backend defaults to "1.0.0" when omitted.
• agent_metadata (dict, optional): Agent configuration
• mode (str, optional): Mode identifier for the message. Allowed values: "SIMPLE" or "EXPAND"

Return Type: PlatformMessageSubmissionResponse

Response Notes (Cache):

• cacheHit / cacheResponse may be present when the backend cache API was checked (typically for HUMAN messages).
• orgContext may be present in submission response (typically HUMAN flow). May be null if org knowledge is unavailable, or not configured.

Platform Session API

await platform_session.initiate_session(request=None)

Initiate a new conversation session.

POST /api/platformsession/initiate

Return Type: Dict[str, Any] (raw response body as returned by the server)

await platform_session.end_conversation(conversation_id)

End an active conversation session explicitly.

POST /api/platformsession/endconversation

Parameters:

• conversation_id (UUID, required): Conversation identifier to end

Return Type: EndConversationResponse

await messages.submit(request)

Low-level message submission with full control.

Parameters:

• request (PlatformMessageSubmissionRequest, required): Complete message request object. email is required for message submission; the SDK raises ValueError if it is missing or blank.

Return Type: PlatformMessageSubmissionResponse

Response fields to expect in PlatformMessageSubmissionResponse:

• success, messageId, conversationId, message
• contextualPrompt, humanQuery, previousKConversations, similarConversations
• operationStatus, conversationTitle
• cacheResponse, cacheHit
• orgContext (optional; typically HUMAN flow. May be null if org knowledge is unavailable, or not configured.)

await messages.get_all()

Get all messages for the authenticated project.

Return Type: List[PlatformMessage]

await messages.get_by_id(message_id)

Get a specific message by ID.

Parameters:

• message_id (UUID, required): Message identifier

Return Type: PlatformMessage

await messages.get_by_agent(agent_id)

Get all messages sent by a specific agent.

Parameters:

• agent_id (UUID, required): Agent identifier

Return Type: List[PlatformMessage]

await messages.delete_message(message_id)

delete a message turn (bot message and its paired human message). Idempotent if already deleted.

Parameters:

• message_id (UUID, required): UUID of the BOT message to soft-delete

Return Type: Dict[str, Any] (success: success, message, timestamp; errors: error, message, status, timestamp)

Users API

await users.create(username, email, metadata=None)

Create a new user.

Parameters:

• username (str, required): Unique username (e.g., "john_doe", "user123")
• email (str, required): User's email address (e.g., "[e-mail]")
• metadata (dict, optional): Custom user attributes (e.g., {"role": "premium", "subscription": "gold", "preferences": {"theme": "dark"}})

Return Type: User

Example:

user = await client.users.create_user(
    username="john_doe",
    email="[e-mail]",
    metadata={"role": "premium"}
)
print(f"Created user: {user.username}")

Agents API

await agents.create(name, platform, version=None, metadata=None)

Create a new AI agent.

Parameters:

• name (str, required): Display name for the agent (e.g., "CustomerSupportBot", "CodeAssistant")
• platform (str, required): Platform/provider (e.g., "OpenAI", "Azure", "Anthropic")
• version (str, optional): Model version (e.g., "gpt-4", "claude-2", "gpt-3.5-turbo")
• metadata (dict, optional): Agent configuration (e.g., {"temperature": 0.7, "max_tokens": 2000, "system_prompt": "You are a helpful assistant"})

Return Type: Agent

Example:

agent = await client.agents.create_agent(
    name="ChatGPT-4",
    platform="OpenAI",
    version="4.0",
    metadata={"model": "gpt-4", "temperature": 0.7}
)
print(f"Created agent: {agent.name}")

Analytics API

await analytics.submit_feedback(message_id, feedback_title, feedback, liked=None, disliked=None, regeneration=None)

Submit user feedback on a BOT message (multiple feedback per message allowed).

Parameters:

• message_id (UUID, required): ID of the BOT message receiving feedback
• feedback_title (str, required): Title for the feedback (e.g., "Response Quality Feedback")
• feedback (str, required): Feedback content (e.g., "The response was very helpful")
• liked (bool, optional): User liked the response (true/false)
• disliked (bool, optional): User disliked the response (true/false)
• regeneration (bool, optional): User requested regeneration (true/false)

Return Type: FeedbackSubmissionResponse (includes feedbackId, submittedAt)

await analytics.get_message_feedback(message_id)

Get all feedback submissions for a specific BOT message (most recent first).

Parameters:

• message_id (UUID, required): UUID of the BOT message

Return Type: List[FeedbackDTO]

await analytics.get_latest_feedbacks(timeperiod=None)

Get latest feedback submissions for the project, most recent first.

Parameters:

• timeperiod (int, optional): None or omitted = all feedbacks; N (e.g. 24) = only feedbacks from the last N hours

Return Type: LatestFeedbacksResponse (.feedbacks list of LatestFeedbackItemResponse; optional .message when time window is used and there are no feedbacks)

User preferences (tenant-isolated; require Api-Key)

Categories: USER_PERSONAL (tone, style, formatting), METRICS (structure, visualization), CALCULATION (formulas, methods). Use value "DELETE" (case-insensitive) to remove the item at the given index.

await analytics.update_user_preference(request)

Update one user preference item (or remove with value "DELETE").

Endpoint: POST /api/analytics/user-preferences/update

Parameters:

• request (UserPreferenceUpdateRequest, required): profileId (UUID), category (USER_PERSONAL | METRICS | CALCULATION), index (0-based, non-negative), value (new text or "DELETE" to remove item at index)

Return Type: UserPreferenceItemResponse (includes updatedAt on success)

await analytics.list_user_preferences_by_email(email)

List preferences for one user by email.

Endpoint: POST /api/analytics/user-preferences/list

Parameters:

• email (str, required): User email in the tenant (e.g. "[e-mail]")

Return Type: UserPreferenceListResponse (.userpreferences list of UserPreferenceItemResponse)

await analytics.list_all_user_preferences(limit=None)

List all user preferences in the tenant with optional limit.

Endpoint: POST /api/analytics/user-preferences/list/all

Parameters:

• limit (int, optional): Max profiles to return (default 50, max 500). Omit or None for default.

Return Type: UserPreferenceListResponse (.userpreferences list of UserPreferenceItemResponse)

Response shape (single profile): UserPreferenceItemResponse has profileId, username, userEmail, botName, userPreferences (object with userPersonalFeedbacks, metricsFeedbacks, calculationFeedbacks arrays of strings), createdAt, updatedAt (ISO-8601).

await analytics.get_dashboard()

Get project dashboard metrics (includes cache analytics: cacheServed, estimatedTokensSaved, estimatedCostSaved when available).

Return Type: DashboardMetricsDTO

await analytics.get_top_agents(limit=5)

Get top-performing agents by usage.

Parameters:

• limit (int, optional): Maximum number of results (default: 5, max: 100)

Return Type: List[TopAgentDTO]

await analytics.get_top_users(limit=5)

Get most active users.

Parameters:

• limit (int, optional): Maximum number of results (default: 5, max: 100)

Return Type: List[TopUserDTO]

await analytics.get_user_analytics()

Get analytics for all users (per-user cache metrics: cacheServed, estimatedTokensSaved, estimatedCostSaved when available).

Return Type: List[UserAnalyticsDTO]

await analytics.get_project_data(top_limit=10)

Get project-level analytics data (includes cacheServed, estimatedTokensSaved, estimatedCostSaved when available).

Parameters:

• top_limit (int, optional): Limit for top results (default: 10, max: 100)

Return Type: ProjectAnalyticsResponseDTO

await analytics.get_all(top_limit=5)

Get comprehensive analytics data.

Parameters:

• top_limit (int, optional): Limit for top results (default: 5, max: 100)

Return Type: Dict[str, Any]

await analytics.initialize()

Initialize analytics for the project.

Return Type: Dict[str, Any]

Conversations API

await conversations.get_messages_by_conversation_id(conversation_id)

Get all messages in a conversation.

Parameters:

• conversation_id (UUID, required): Conversation identifier

Return Type: List[ConversationMessageResponse]

await conversations.get_all_conversations()

Get all conversations for the project.

Return Type: List[ConversationSummaryResponse]

await conversations.get_user_conversations(username)

Get all conversations for a specific user.

Parameters:

• username (str, required): Username

Return Type: List[ConversationSummaryResponse]

await conversations.get_conversations_by_email(email)

Get all conversations for a specific user by email.

Parameters:

• email (str, required): User's email address

Return Type: List[ConversationSummaryResponse]

await conversations.delete_conversation(conversation_id)

Delete a conversation.

Parameters:

• conversation_id (UUID, required): Conversation identifier

Return Type: Dict[str, Any]

Error Handling

The SDK surfaces HTTP errors as typed exceptions:

from shiftai.http import (
    ApiException,
    UnauthorizedException,
    BadRequestException,
    NotFoundException,
    ServerException
)

try:
    response = await client.messages.send_human_message(
        username="user",
        message="Hello",
        agent_name="Bot",
        user_email="[e-mail]",  # Required for message submission
        agent_platform="OpenAI"         # Optional
    )
except BadRequestException as e:
    print(f"Invalid request: {e}")
except UnauthorizedException as e:
    print("Invalid API key")
except ApiException as e:
    print(f"API error {e.status_code}: {e}")

Why This SDK Is Safe to Use

No Hidden Dependencies

• Explicit dependency list: Only 1 external library needed
• No transitive dependencies: No "dependency hell"
• Standard async library: httpx is the de facto async HTTP library for Python

Proven Portability

• Minimal setup: Just add httpx to requirements.txt
• No configuration: No complex setup or initialization

This SDK is built to enable developers to easily integrate and use the Shift AI Agentic Infra in their own applications