openaivec 0.10.0__py3-none-any.whl → 1.0.10__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (45) hide show
  1. openaivec/__init__.py +13 -4
  2. openaivec/_cache/__init__.py +12 -0
  3. openaivec/_cache/optimize.py +109 -0
  4. openaivec/_cache/proxy.py +806 -0
  5. openaivec/_di.py +326 -0
  6. openaivec/_embeddings.py +203 -0
  7. openaivec/{log.py → _log.py} +2 -2
  8. openaivec/_model.py +113 -0
  9. openaivec/{prompt.py → _prompt.py} +95 -28
  10. openaivec/_provider.py +207 -0
  11. openaivec/_responses.py +511 -0
  12. openaivec/_schema/__init__.py +9 -0
  13. openaivec/_schema/infer.py +340 -0
  14. openaivec/_schema/spec.py +350 -0
  15. openaivec/_serialize.py +234 -0
  16. openaivec/{util.py → _util.py} +25 -85
  17. openaivec/pandas_ext.py +1635 -425
  18. openaivec/spark.py +604 -335
  19. openaivec/task/__init__.py +27 -29
  20. openaivec/task/customer_support/__init__.py +9 -15
  21. openaivec/task/customer_support/customer_sentiment.py +51 -41
  22. openaivec/task/customer_support/inquiry_classification.py +86 -61
  23. openaivec/task/customer_support/inquiry_summary.py +44 -45
  24. openaivec/task/customer_support/intent_analysis.py +56 -41
  25. openaivec/task/customer_support/response_suggestion.py +49 -43
  26. openaivec/task/customer_support/urgency_analysis.py +76 -71
  27. openaivec/task/nlp/__init__.py +4 -4
  28. openaivec/task/nlp/dependency_parsing.py +19 -20
  29. openaivec/task/nlp/keyword_extraction.py +22 -24
  30. openaivec/task/nlp/morphological_analysis.py +25 -25
  31. openaivec/task/nlp/named_entity_recognition.py +26 -28
  32. openaivec/task/nlp/sentiment_analysis.py +29 -21
  33. openaivec/task/nlp/translation.py +24 -30
  34. openaivec/task/table/__init__.py +3 -0
  35. openaivec/task/table/fillna.py +183 -0
  36. openaivec-1.0.10.dist-info/METADATA +399 -0
  37. openaivec-1.0.10.dist-info/RECORD +39 -0
  38. {openaivec-0.10.0.dist-info → openaivec-1.0.10.dist-info}/WHEEL +1 -1
  39. openaivec/embeddings.py +0 -172
  40. openaivec/responses.py +0 -392
  41. openaivec/serialize.py +0 -225
  42. openaivec/task/model.py +0 -84
  43. openaivec-0.10.0.dist-info/METADATA +0 -546
  44. openaivec-0.10.0.dist-info/RECORD +0 -29
  45. {openaivec-0.10.0.dist-info → openaivec-1.0.10.dist-info}/licenses/LICENSE +0 -0
@@ -11,20 +11,20 @@ with openaivec's batch processing capabilities.
11
11
  Core NLP tasks for text analysis and processing:
12
12
 
13
13
  - **Translation**: Multi-language translation with 40+ language support
14
- - **Sentiment Analysis**: Emotion detection and sentiment scoring
14
+ - **Sentiment Analysis**: Emotion detection and sentiment scoring
15
15
  - **Named Entity Recognition**: Extract people, organizations, locations
16
16
  - **Morphological Analysis**: Part-of-speech tagging and lemmatization
17
17
  - **Dependency Parsing**: Syntactic structure analysis
18
18
  - **Keyword Extraction**: Important term identification
19
19
 
20
- ### Customer Support (`customer_support`)
20
+ ### Customer Support (`customer_support`)
21
21
  Specialized tasks for customer service operations:
22
22
 
23
23
  - **Intent Analysis**: Understand customer goals and requirements
24
24
  - **Sentiment Analysis**: Customer satisfaction and emotional state
25
25
  - **Urgency Analysis**: Priority assessment and response time recommendations
26
26
  - **Inquiry Classification**: Automatic categorization and routing
27
- - **Inquiry Summary**: Comprehensive issue summarization
27
+ - **Inquiry Summary**: Comprehensive issue summarization
28
28
  - **Response Suggestion**: AI-powered response drafting
29
29
 
30
30
  ## Usage Patterns
@@ -32,7 +32,7 @@ Specialized tasks for customer service operations:
32
32
  ### Quick Start with Default Tasks
33
33
  ```python
34
34
  from openai import OpenAI
35
- from openaivec.responses import BatchResponses
35
+ from openaivec import BatchResponses
36
36
  from openaivec.task import nlp, customer_support
37
37
 
38
38
  client = OpenAI()
@@ -40,13 +40,13 @@ client = OpenAI()
40
40
  # Use pre-configured tasks
41
41
  sentiment_analyzer = BatchResponses.of_task(
42
42
  client=client,
43
- model_name="gpt-4o-mini",
43
+ model_name="gpt-4.1-mini",
44
44
  task=nlp.SENTIMENT_ANALYSIS
45
45
  )
46
46
 
47
47
  intent_analyzer = BatchResponses.of_task(
48
- client=client,
49
- model_name="gpt-4o-mini",
48
+ client=client,
49
+ model_name="gpt-4.1-mini",
50
50
  task=customer_support.INTENT_ANALYSIS
51
51
  )
52
52
  ```
@@ -60,7 +60,7 @@ custom_urgency = urgency_analysis(
60
60
  business_context="SaaS platform support",
61
61
  urgency_levels={
62
62
  "critical": "Service outages, security breaches",
63
- "high": "Login issues, payment failures",
63
+ "high": "Login issues, payment failures",
64
64
  "medium": "Feature bugs, billing questions",
65
65
  "low": "Feature requests, general feedback"
66
66
  }
@@ -68,7 +68,7 @@ custom_urgency = urgency_analysis(
68
68
 
69
69
  analyzer = BatchResponses.of_task(
70
70
  client=client,
71
- model_name="gpt-4o-mini",
71
+ model_name="gpt-4.1-mini",
72
72
  task=custom_urgency
73
73
  )
74
74
  ```
@@ -88,22 +88,24 @@ df["intent"] = df["text"].ai.task(customer_support.INTENT_ANALYSIS)
88
88
  results_df = df.ai.extract("sentiment")
89
89
  ```
90
90
 
91
- ### Spark Integration
91
+ ### Spark Integration
92
92
  ```python
93
- from openaivec.spark import ResponsesUDFBuilder
93
+ from openaivec.spark import task_udf
94
94
 
95
95
  # Register UDF for large-scale processing
96
96
  spark.udf.register(
97
97
  "analyze_sentiment",
98
- ResponsesUDFBuilder.of_openai(
99
- api_key=api_key,
100
- model_name="gpt-4o-mini"
101
- ).build_from_task(task=nlp.SENTIMENT_ANALYSIS)
98
+ task_udf(
99
+ task=nlp.SENTIMENT_ANALYSIS,
100
+ model_name="gpt-4.1-mini",
101
+ batch_size=64,
102
+ max_concurrency=8,
103
+ ),
102
104
  )
103
105
 
104
106
  # Use in Spark SQL
105
107
  df = spark.sql(\"\"\"
106
- SELECT text, analyze_sentiment(text) as sentiment
108
+ SELECT text, analyze_sentiment(text) as sentiment
107
109
  FROM customer_feedback
108
110
  \"\"\")
109
111
  ```
@@ -117,7 +119,7 @@ All tasks are built using the `PreparedTask` dataclass:
117
119
  @dataclass(frozen=True)
118
120
  class PreparedTask:
119
121
  instructions: str # Detailed prompt for the LLM
120
- response_format: Type[T] # Pydantic model for structured output
122
+ response_format: type[ResponseFormat] # Pydantic model or str for structured/plain output
121
123
  temperature: float = 0.0 # Sampling temperature
122
124
  top_p: float = 1.0 # Nucleus sampling parameter
123
125
  ```
@@ -130,7 +132,7 @@ class PreparedTask:
130
132
 
131
133
  ### Design Principles
132
134
  1. **Consistency**: Uniform API across all task domains
133
- 2. **Configurability**: Customizable parameters for different use cases
135
+ 2. **Configurability**: Customizable parameters for different use cases
134
136
  3. **Type Safety**: Strong typing with Pydantic validation
135
137
  4. **Scalability**: Optimized for batch processing and large datasets
136
138
  5. **Extensibility**: Easy to add new domains and tasks
@@ -164,18 +166,18 @@ src/openaivec/task/finance/
164
166
 
165
167
  ## Best Practices
166
168
 
167
- 1. **Choose Appropriate Models**:
168
- - `gpt-4o-mini`: Fast, cost-effective for most tasks
169
+ 1. **Choose Appropriate Models**:
170
+ - `gpt-4.1-mini`: Fast, cost-effective for most tasks
169
171
  - `gpt-4o`: Higher accuracy for complex analysis
170
-
171
- 2. **Customize When Needed**:
172
+
173
+ 2. **Customize When Needed**:
172
174
  - Use default tasks for quick prototyping
173
175
  - Configure custom tasks for production use
174
-
176
+
175
177
  3. **Handle Multilingual Input**:
176
178
  - Tasks automatically detect and respond in input language
177
179
  - Categorical fields remain in English for system compatibility
178
-
180
+
179
181
  4. **Monitor Performance**:
180
182
  - Use batch sizes appropriate for your use case
181
183
  - Monitor token usage for cost optimization
@@ -183,8 +185,4 @@ src/openaivec/task/finance/
183
185
  See individual task modules for detailed documentation and examples.
184
186
  """
185
187
 
186
- from .model import PreparedTask
187
-
188
- __all__ = [
189
- "PreparedTask",
190
- ]
188
+ __all__ = []
@@ -1,32 +1,26 @@
1
1
  # Function imports
2
- from .inquiry_classification import inquiry_classification
3
- from .urgency_analysis import urgency_analysis
4
- from .customer_sentiment import customer_sentiment
5
- from .intent_analysis import intent_analysis
6
- from .inquiry_summary import inquiry_summary
7
- from .response_suggestion import response_suggestion
2
+ from .customer_sentiment import CUSTOMER_SENTIMENT, customer_sentiment
8
3
 
9
4
  # Backward compatibility - constant imports
10
- from .inquiry_classification import INQUIRY_CLASSIFICATION
11
- from .urgency_analysis import URGENCY_ANALYSIS
12
- from .customer_sentiment import CUSTOMER_SENTIMENT
13
- from .intent_analysis import INTENT_ANALYSIS
14
- from .inquiry_summary import INQUIRY_SUMMARY
15
- from .response_suggestion import RESPONSE_SUGGESTION
5
+ from .inquiry_classification import INQUIRY_CLASSIFICATION, inquiry_classification
6
+ from .inquiry_summary import INQUIRY_SUMMARY, inquiry_summary
7
+ from .intent_analysis import INTENT_ANALYSIS, intent_analysis
8
+ from .response_suggestion import RESPONSE_SUGGESTION, response_suggestion
9
+ from .urgency_analysis import URGENCY_ANALYSIS, urgency_analysis
16
10
 
17
11
  __all__ = [
18
12
  # Configurable functions (recommended)
19
13
  "inquiry_classification",
20
- "urgency_analysis",
14
+ "urgency_analysis",
21
15
  "customer_sentiment",
22
16
  "intent_analysis",
23
17
  "inquiry_summary",
24
18
  "response_suggestion",
25
19
  # Backward compatibility constants
26
20
  "INQUIRY_CLASSIFICATION",
27
- "URGENCY_ANALYSIS",
21
+ "URGENCY_ANALYSIS",
28
22
  "CUSTOMER_SENTIMENT",
29
23
  "INTENT_ANALYSIS",
30
24
  "INQUIRY_SUMMARY",
31
25
  "RESPONSE_SUGGESTION",
32
- ]
26
+ ]
@@ -6,26 +6,26 @@ customer experience and support strategy.
6
6
 
7
7
  Example:
8
8
  Basic usage with BatchResponses:
9
-
9
+
10
10
  ```python
11
11
  from openai import OpenAI
12
- from openaivec.responses import BatchResponses
12
+ from openaivec import BatchResponses
13
13
  from openaivec.task import customer_support
14
-
14
+
15
15
  client = OpenAI()
16
16
  analyzer = BatchResponses.of_task(
17
17
  client=client,
18
- model_name="gpt-4o-mini",
18
+ model_name="gpt-4.1-mini",
19
19
  task=customer_support.CUSTOMER_SENTIMENT
20
20
  )
21
-
21
+
22
22
  inquiries = [
23
23
  "I'm really disappointed with your service. This is the third time I've had this issue.",
24
24
  "Thank you so much for your help! You've been incredibly patient.",
25
25
  "I need to cancel my subscription. It's not working for me."
26
26
  ]
27
27
  sentiments = analyzer.parse(inquiries)
28
-
28
+
29
29
  for sentiment in sentiments:
30
30
  print(f"Sentiment: {sentiment.sentiment}")
31
31
  print(f"Satisfaction: {sentiment.satisfaction_level}")
@@ -34,68 +34,79 @@ Example:
34
34
  ```
35
35
 
36
36
  With pandas integration:
37
-
37
+
38
38
  ```python
39
39
  import pandas as pd
40
40
  from openaivec import pandas_ext # Required for .ai accessor
41
41
  from openaivec.task import customer_support
42
-
42
+
43
43
  df = pd.DataFrame({"inquiry": [
44
44
  "I'm really disappointed with your service. This is the third time I've had this issue.",
45
45
  "Thank you so much for your help! You've been incredibly patient.",
46
46
  "I need to cancel my subscription. It's not working for me."
47
47
  ]})
48
48
  df["sentiment"] = df["inquiry"].ai.task(customer_support.CUSTOMER_SENTIMENT)
49
-
49
+
50
50
  # Extract sentiment components
51
51
  extracted_df = df.ai.extract("sentiment")
52
- print(extracted_df[["inquiry", "sentiment_satisfaction_level", "sentiment_churn_risk", "sentiment_emotional_state"]])
52
+ print(extracted_df[[
53
+ "inquiry", "sentiment_satisfaction_level",
54
+ "sentiment_churn_risk", "sentiment_emotional_state"
55
+ ]])
53
56
  ```
54
57
 
55
58
  Attributes:
56
- CUSTOMER_SENTIMENT (PreparedTask): A prepared task instance
57
- configured for customer sentiment analysis with temperature=0.0 and
59
+ CUSTOMER_SENTIMENT (PreparedTask): A prepared task instance
60
+ configured for customer sentiment analysis with temperature=0.0 and
58
61
  top_p=1.0 for deterministic output.
59
62
  """
60
63
 
61
- from typing import List, Literal
64
+ from typing import Literal
65
+
62
66
  from pydantic import BaseModel, Field
63
67
 
64
- from ..model import PreparedTask
68
+ from openaivec._model import PreparedTask
65
69
 
66
70
  __all__ = ["customer_sentiment"]
67
71
 
68
72
 
69
73
  class CustomerSentiment(BaseModel):
70
- sentiment: Literal["positive", "negative", "neutral", "mixed"] = Field(description="Overall sentiment (positive, negative, neutral, mixed)")
71
- satisfaction_level: Literal["very_satisfied", "satisfied", "neutral", "dissatisfied", "very_dissatisfied"] = Field(description="Customer satisfaction (very_satisfied, satisfied, neutral, dissatisfied, very_dissatisfied)")
72
- emotional_state: Literal["happy", "frustrated", "angry", "disappointed", "confused", "grateful", "worried"] = Field(description="Primary emotional state (happy, frustrated, angry, disappointed, confused, grateful, worried)")
74
+ sentiment: Literal["positive", "negative", "neutral", "mixed"] = Field(
75
+ description="Overall sentiment (positive, negative, neutral, mixed)"
76
+ )
77
+ satisfaction_level: Literal["very_satisfied", "satisfied", "neutral", "dissatisfied", "very_dissatisfied"] = Field(
78
+ description="Customer satisfaction (very_satisfied, satisfied, neutral, dissatisfied, very_dissatisfied)"
79
+ )
80
+ emotional_state: Literal["happy", "frustrated", "angry", "disappointed", "confused", "grateful", "worried"] = Field(
81
+ description="Primary emotional state (happy, frustrated, angry, disappointed, confused, grateful, worried)"
82
+ )
73
83
  confidence: float = Field(description="Confidence score for sentiment analysis (0.0-1.0)")
74
- churn_risk: Literal["low", "medium", "high", "critical"] = Field(description="Risk of customer churn (low, medium, high, critical)")
84
+ churn_risk: Literal["low", "medium", "high", "critical"] = Field(
85
+ description="Risk of customer churn (low, medium, high, critical)"
86
+ )
75
87
  sentiment_intensity: float = Field(description="Intensity of sentiment from 0.0 (mild) to 1.0 (extreme)")
76
88
  polarity_score: float = Field(description="Polarity score from -1.0 (very negative) to 1.0 (very positive)")
77
- tone_indicators: List[str] = Field(description="Specific words or phrases indicating tone")
78
- relationship_status: Literal["new", "loyal", "at_risk", "detractor", "advocate"] = Field(description="Customer relationship status (new, loyal, at_risk, detractor, advocate)")
79
- response_approach: Literal["empathetic", "professional", "solution_focused", "escalation_required"] = Field(description="Recommended response approach (empathetic, professional, solution_focused, escalation_required)")
89
+ tone_indicators: list[str] = Field(description="Specific words or phrases indicating tone")
90
+ relationship_status: Literal["new", "loyal", "at_risk", "detractor", "advocate"] = Field(
91
+ description="Customer relationship status (new, loyal, at_risk, detractor, advocate)"
92
+ )
93
+ response_approach: Literal["empathetic", "professional", "solution_focused", "escalation_required"] = Field(
94
+ description="Recommended response approach (empathetic, professional, solution_focused, escalation_required)"
95
+ )
80
96
 
81
97
 
82
- def customer_sentiment(
83
- business_context: str = "general customer support",
84
- temperature: float = 0.0,
85
- top_p: float = 1.0
86
- ) -> PreparedTask:
98
+ def customer_sentiment(business_context: str = "general customer support") -> PreparedTask:
87
99
  """Create a configurable customer sentiment analysis task.
88
-
100
+
89
101
  Args:
90
- business_context: Business context for sentiment analysis.
91
- temperature: Sampling temperature (0.0-1.0).
92
- top_p: Nucleus sampling parameter (0.0-1.0).
93
-
102
+ business_context (str): Business context for sentiment analysis.
103
+
94
104
  Returns:
95
105
  PreparedTask configured for customer sentiment analysis.
96
106
  """
97
-
98
- instructions = f"""Analyze customer sentiment in the context of support interactions, focusing on satisfaction, emotional state, and business implications.
107
+
108
+ instructions = f"""Analyze customer sentiment in the context of support interactions, focusing on
109
+ satisfaction, emotional state, and business implications.
99
110
 
100
111
  Business Context: {business_context}
101
112
 
@@ -146,17 +157,16 @@ Analyze tone indicators like:
146
157
  - Urgency: "urgent", "immediately", "ASAP", "critical"
147
158
  - Threat: "cancel", "switch", "competitor", "lawyer", "report"
148
159
 
149
- IMPORTANT: Provide analysis responses in the same language as the input text, except for the predefined categorical fields (sentiment, satisfaction_level, emotional_state, churn_risk, relationship_status, response_approach) which must use the exact English values specified above. For example, if the input is in Spanish, provide tone_indicators in Spanish, but use English values like "positive" for sentiment.
160
+ IMPORTANT: Provide analysis responses in the same language as the input text, except for the
161
+ predefined categorical fields (sentiment, satisfaction_level, emotional_state, churn_risk,
162
+ relationship_status, response_approach) which must use the exact English values specified above.
163
+ For example, if the input is in Spanish, provide tone_indicators in Spanish, but use English
164
+ values like "positive" for sentiment.
150
165
 
151
166
  Provide comprehensive sentiment analysis with business context and recommended response strategy."""
152
167
 
153
- return PreparedTask(
154
- instructions=instructions,
155
- response_format=CustomerSentiment,
156
- temperature=temperature,
157
- top_p=top_p
158
- )
168
+ return PreparedTask(instructions=instructions, response_format=CustomerSentiment)
159
169
 
160
170
 
161
171
  # Backward compatibility - default configuration
162
- CUSTOMER_SENTIMENT = customer_sentiment()
172
+ CUSTOMER_SENTIMENT = customer_sentiment()
@@ -5,26 +5,26 @@ different categories to help route them to the appropriate support team.
5
5
 
6
6
  Example:
7
7
  Basic usage with default settings:
8
-
8
+
9
9
  ```python
10
10
  from openai import OpenAI
11
- from openaivec.responses import BatchResponses
11
+ from openaivec import BatchResponses
12
12
  from openaivec.task import customer_support
13
-
13
+
14
14
  client = OpenAI()
15
15
  classifier = BatchResponses.of_task(
16
16
  client=client,
17
- model_name="gpt-4o-mini",
17
+ model_name="gpt-4.1-mini",
18
18
  task=customer_support.inquiry_classification()
19
19
  )
20
-
20
+
21
21
  inquiries = [
22
22
  "I can't log into my account",
23
23
  "When will my order arrive?",
24
24
  "I want to cancel my subscription"
25
25
  ]
26
26
  classifications = classifier.parse(inquiries)
27
-
27
+
28
28
  for classification in classifications:
29
29
  print(f"Category: {classification.category}")
30
30
  print(f"Subcategory: {classification.subcategory}")
@@ -33,10 +33,10 @@ Example:
33
33
  ```
34
34
 
35
35
  Customized for e-commerce:
36
-
36
+
37
37
  ```python
38
38
  from openaivec.task import customer_support
39
-
39
+
40
40
  # E-commerce specific categories
41
41
  ecommerce_categories = {
42
42
  "order_management": ["order_status", "order_cancellation", "order_modification", "returns"],
@@ -46,53 +46,57 @@ Example:
46
46
  "account": ["login_issues", "account_settings", "profile_updates", "password_reset"],
47
47
  "general": ["complaints", "compliments", "feedback", "other"]
48
48
  }
49
-
49
+
50
50
  ecommerce_routing = {
51
51
  "order_management": "order_team",
52
- "payment": "billing_team",
52
+ "payment": "billing_team",
53
53
  "product": "product_team",
54
54
  "shipping": "logistics_team",
55
55
  "account": "account_support",
56
56
  "general": "general_support"
57
57
  }
58
-
58
+
59
59
  task = customer_support.inquiry_classification(
60
60
  categories=ecommerce_categories,
61
61
  routing_rules=ecommerce_routing,
62
62
  business_context="e-commerce platform"
63
63
  )
64
-
64
+
65
65
  classifier = BatchResponses.of_task(
66
66
  client=client,
67
- model_name="gpt-4o-mini",
67
+ model_name="gpt-4.1-mini",
68
68
  task=task
69
69
  )
70
70
  ```
71
71
 
72
72
  With pandas integration:
73
-
73
+
74
74
  ```python
75
75
  import pandas as pd
76
76
  from openaivec import pandas_ext # Required for .ai accessor
77
77
  from openaivec.task import customer_support
78
-
78
+
79
79
  df = pd.DataFrame({"inquiry": [
80
80
  "I can't log into my account",
81
81
  "When will my order arrive?",
82
82
  "I want to cancel my subscription"
83
83
  ]})
84
84
  df["classification"] = df["inquiry"].ai.task(customer_support.inquiry_classification())
85
-
85
+
86
86
  # Extract classification components
87
87
  extracted_df = df.ai.extract("classification")
88
- print(extracted_df[["inquiry", "classification_category", "classification_subcategory", "classification_confidence"]])
88
+ print(extracted_df[[
89
+ "inquiry", "classification_category",
90
+ "classification_subcategory", "classification_confidence"
91
+ ]])
89
92
  ```
90
93
  """
91
94
 
92
- from typing import List, Dict, Optional, Literal
95
+ from typing import Dict, Literal
96
+
93
97
  from pydantic import BaseModel, Field
94
98
 
95
- from ..model import PreparedTask
99
+ from openaivec._model import PreparedTask
96
100
 
97
101
  __all__ = ["inquiry_classification"]
98
102
 
@@ -102,92 +106,115 @@ class InquiryClassification(BaseModel):
102
106
  subcategory: str = Field(description="Specific subcategory within the primary category")
103
107
  confidence: float = Field(description="Confidence score for classification (0.0-1.0)")
104
108
  routing: str = Field(description="Recommended routing destination")
105
- keywords: List[str] = Field(description="Key terms that influenced the classification")
106
- priority: Literal["low", "medium", "high", "urgent"] = Field(description="Suggested priority level (low, medium, high, urgent)")
109
+ keywords: list[str] = Field(description="Key terms that influenced the classification")
110
+ priority: Literal["low", "medium", "high", "urgent"] = Field(
111
+ description="Suggested priority level (low, medium, high, urgent)"
112
+ )
107
113
  business_context_match: bool = Field(description="Whether the inquiry matches the business context")
108
114
 
109
115
 
110
116
  def inquiry_classification(
111
- categories: Optional[Dict[str, List[str]]] = None,
112
- routing_rules: Optional[Dict[str, str]] = None,
113
- priority_rules: Optional[Dict[str, str]] = None,
117
+ categories: Dict[str, list[str]] | None = None,
118
+ routing_rules: Dict[str, str] | None = None,
119
+ priority_rules: Dict[str, str] | None = None,
114
120
  business_context: str = "general customer support",
115
- custom_keywords: Optional[Dict[str, List[str]]] = None,
116
- temperature: float = 0.0,
117
- top_p: float = 1.0
121
+ custom_keywords: Dict[str, list[str]] | None = None,
118
122
  ) -> PreparedTask:
119
123
  """Create a configurable inquiry classification task.
120
-
124
+
121
125
  Args:
122
- categories: Dictionary mapping category names to lists of subcategories.
126
+ categories (dict[str, list[str]] | None): Dictionary mapping category names to lists of subcategories.
123
127
  Default provides standard support categories.
124
- routing_rules: Dictionary mapping categories to routing destinations.
128
+ routing_rules (dict[str, str] | None): Dictionary mapping categories to routing destinations.
125
129
  Default provides standard routing options.
126
- priority_rules: Dictionary mapping keywords/patterns to priority levels.
130
+ priority_rules (dict[str, str] | None): Dictionary mapping keywords/patterns to priority levels.
127
131
  Default uses standard priority indicators.
128
- business_context: Description of the business context to help with classification.
129
- custom_keywords: Dictionary mapping categories to relevant keywords.
130
- temperature: Sampling temperature (0.0-1.0).
131
- top_p: Nucleus sampling parameter (0.0-1.0).
132
-
132
+ business_context (str): Description of the business context to help with classification.
133
+ custom_keywords (dict[str, list[str]] | None): Dictionary mapping categories to relevant keywords.
134
+
133
135
  Returns:
134
136
  PreparedTask configured for inquiry classification.
135
137
  """
136
-
138
+
137
139
  # Default categories
138
140
  if categories is None:
139
141
  categories = {
140
- "technical": ["login_issues", "password_reset", "app_crashes", "connectivity_problems", "feature_not_working"],
141
- "billing": ["payment_failed", "invoice_questions", "refund_request", "pricing_inquiry", "subscription_changes"],
142
- "product": ["feature_request", "product_information", "compatibility_questions", "how_to_use", "bug_reports"],
143
- "shipping": ["delivery_status", "shipping_address", "delivery_issues", "tracking_number", "expedited_shipping"],
142
+ "technical": [
143
+ "login_issues",
144
+ "password_reset",
145
+ "app_crashes",
146
+ "connectivity_problems",
147
+ "feature_not_working",
148
+ ],
149
+ "billing": [
150
+ "payment_failed",
151
+ "invoice_questions",
152
+ "refund_request",
153
+ "pricing_inquiry",
154
+ "subscription_changes",
155
+ ],
156
+ "product": [
157
+ "feature_request",
158
+ "product_information",
159
+ "compatibility_questions",
160
+ "how_to_use",
161
+ "bug_reports",
162
+ ],
163
+ "shipping": [
164
+ "delivery_status",
165
+ "shipping_address",
166
+ "delivery_issues",
167
+ "tracking_number",
168
+ "expedited_shipping",
169
+ ],
144
170
  "account": ["account_creation", "profile_updates", "account_deletion", "data_export", "privacy_settings"],
145
- "general": ["compliments", "complaints", "feedback", "partnership_inquiry", "other"]
171
+ "general": ["compliments", "complaints", "feedback", "partnership_inquiry", "other"],
146
172
  }
147
-
173
+
148
174
  # Default routing rules
149
175
  if routing_rules is None:
150
176
  routing_rules = {
151
177
  "technical": "tech_support",
152
- "billing": "billing_team",
178
+ "billing": "billing_team",
153
179
  "product": "product_team",
154
180
  "shipping": "shipping_team",
155
181
  "account": "account_management",
156
- "general": "general_support"
182
+ "general": "general_support",
157
183
  }
158
-
184
+
159
185
  # Default priority rules
160
186
  if priority_rules is None:
161
187
  priority_rules = {
162
188
  "urgent": "urgent, emergency, critical, down, outage, security, breach, immediate",
163
189
  "high": "login, password, payment, billing, delivery, problem, issue, error, bug",
164
190
  "medium": "feature, request, question, how, help, support, feedback",
165
- "low": "information, compliment, thank, suggestion, general, other"
191
+ "low": "information, compliment, thank, suggestion, general, other",
166
192
  }
167
-
193
+
168
194
  # Build categories section
169
195
  categories_text = "Categories and subcategories:\n"
170
196
  for category, subcategories in categories.items():
171
197
  categories_text += f"- {category}: {', '.join(subcategories)}\n"
172
-
198
+
173
199
  # Build routing section
174
200
  routing_text = "Routing options:\n"
175
201
  for category, routing in routing_rules.items():
176
202
  routing_text += f"- {routing}: {category.replace('_', ' ').title()} issues\n"
177
-
203
+
178
204
  # Build priority section
179
205
  priority_text = "Priority levels:\n"
180
206
  for priority, keywords in priority_rules.items():
181
207
  priority_text += f"- {priority}: {keywords}\n"
182
-
208
+
183
209
  # Build custom keywords section
184
210
  keywords_text = ""
185
211
  if custom_keywords:
186
212
  keywords_text = "\nCustom keywords for classification:\n"
187
213
  for category, keywords in custom_keywords.items():
188
214
  keywords_text += f"- {category}: {', '.join(keywords)}\n"
189
-
190
- instructions = f"""Classify the customer inquiry into the appropriate category and subcategory based on the configured categories and business context.
215
+
216
+ instructions = f"""Classify the customer inquiry into the appropriate category and subcategory
217
+ based on the configured categories and business context.
191
218
 
192
219
  Business Context: {business_context}
193
220
 
@@ -216,17 +243,15 @@ Consider:
216
243
  - Business impact
217
244
  - Customer type indicators
218
245
 
219
- IMPORTANT: Provide analysis responses in the same language as the input text, except for the predefined categorical fields (priority) which must use the exact English values specified above. Category, subcategory, routing, and keywords should reflect the content and can be in the input language where appropriate, but priority must use English values like "high".
246
+ IMPORTANT: Provide analysis responses in the same language as the input text, except for the
247
+ predefined categorical fields (priority) which must use the exact English values specified above.
248
+ Category, subcategory, routing, and keywords should reflect the content and can be in the input
249
+ language where appropriate, but priority must use English values like "high".
220
250
 
221
251
  Provide accurate classification with detailed reasoning."""
222
252
 
223
- return PreparedTask(
224
- instructions=instructions,
225
- response_format=InquiryClassification,
226
- temperature=temperature,
227
- top_p=top_p
228
- )
253
+ return PreparedTask(instructions=instructions, response_format=InquiryClassification)
229
254
 
230
255
 
231
256
  # Backward compatibility - default configuration
232
- INQUIRY_CLASSIFICATION = inquiry_classification()
257
+ INQUIRY_CLASSIFICATION = inquiry_classification()