ejentum 0.1.0__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.
ejentum/__init__.py ADDED
@@ -0,0 +1,18 @@
1
+ """
2
+ Ejentum Python SDK — Deterministic Reasoning-Augmented Retrieval (RAR)
3
+ """
4
+
5
+ from .client import Ejentum
6
+ from .exceptions import APIError, AuthenticationError, EjentumError, ScaffoldNotFoundError
7
+ from .wrappers import wrap_anthropic, wrap_openai
8
+
9
+ __version__ = "0.1.0"
10
+ __all__ = [
11
+ "Ejentum",
12
+ "wrap_openai",
13
+ "wrap_anthropic",
14
+ "EjentumError",
15
+ "AuthenticationError",
16
+ "APIError",
17
+ "ScaffoldNotFoundError",
18
+ ]
ejentum/client.py ADDED
@@ -0,0 +1,153 @@
1
+ """
2
+ Official Python client for the Ejentum Deterministic Reasoning-Augmented Retrieval (RAR) API.
3
+ """
4
+
5
+ from __future__ import annotations
6
+
7
+ import json
8
+ import os
9
+ import urllib.error
10
+ import urllib.request
11
+ from typing import Any, Dict, List, Optional
12
+
13
+ from .exceptions import APIError, AuthenticationError, ScaffoldNotFoundError
14
+
15
+ DEFAULT_BASE_URL = "https://api.ejentum.com/logicv1/"
16
+
17
+
18
+ class Ejentum:
19
+ """Ejentum Client for deterministic cognitive scaffold retrieval and prompt augmentation.
20
+
21
+ Example:
22
+ >>> from ejentum import Ejentum
23
+ >>> client = Ejentum() # Reads EJENTUM_API_KEY from environment
24
+ >>> scaffold = client.scaffold("diagnose database connection pool exhaustion")
25
+ >>> augmented_prompt = client.augment("Why is checkout failing?")
26
+ """
27
+
28
+ def __init__(
29
+ self,
30
+ api_key: Optional[str] = None,
31
+ base_url: str = DEFAULT_BASE_URL,
32
+ timeout: float = 10.0,
33
+ ) -> None:
34
+ self.api_key = api_key or os.getenv("EJENTUM_API_KEY")
35
+ if not self.api_key:
36
+ raise AuthenticationError(
37
+ "Ejentum API key is missing. Pass `api_key='...'` or set the "
38
+ "`EJENTUM_API_KEY` environment variable. Get a key at https://ejentum.com/pricing"
39
+ )
40
+ self.base_url = base_url.rstrip("/") + "/"
41
+ self.timeout = timeout
42
+
43
+ def get_ability(self, query: str, mode: str = "reasoning") -> Dict[str, Any]:
44
+ """Fetch the full raw cognitive ability payload from the Ejentum engine."""
45
+ payload = json.dumps({"query": query, "mode": mode}).encode("utf-8")
46
+ headers = {
47
+ "Authorization": f"Bearer {self.api_key}",
48
+ "Content-Type": "application/json",
49
+ "User-Agent": "Ejentum-Python-SDK/0.1.0",
50
+ }
51
+
52
+ req = urllib.request.Request(self.base_url, data=payload, headers=headers, method="POST")
53
+
54
+ try:
55
+ with urllib.request.urlopen(req, timeout=self.timeout) as resp:
56
+ data = json.loads(resp.read().decode("utf-8"))
57
+ return data
58
+ except urllib.error.HTTPError as e:
59
+ raw_body = e.read().decode("utf-8", errors="replace")
60
+ if e.code == 401:
61
+ raise AuthenticationError(
62
+ f"Ejentum authentication failed (401 Unauthorized): {raw_body}"
63
+ ) from e
64
+ raise APIError(
65
+ f"Ejentum API request failed with status {e.code}: {raw_body}",
66
+ status_code=e.code,
67
+ response_body=raw_body,
68
+ ) from e
69
+ except urllib.error.URLError as e:
70
+ raise APIError(f"Network error connecting to Ejentum API: {e.reason}") from e
71
+ except Exception as e:
72
+ raise APIError(f"Unexpected error communicating with Ejentum: {str(e)}") from e
73
+
74
+ def scaffold(self, query: str, mode: str = "reasoning") -> str:
75
+ """Fetch the extracted cognitive scaffold string for a given task query.
76
+
77
+ Args:
78
+ query: The user task, error message, or diagnostic query.
79
+ mode: Reasoning mode (e.g., 'reasoning', 'causal', 'diagnostic').
80
+
81
+ Returns:
82
+ The raw cognitive scaffold text ready for system prompt injection.
83
+ """
84
+ data = self.get_ability(query=query, mode=mode)
85
+
86
+ if isinstance(data, dict):
87
+ if "single_ability" in data and isinstance(data["single_ability"], str):
88
+ return data["single_ability"].strip()
89
+ if "scaffold" in data and isinstance(data["scaffold"], str):
90
+ return data["scaffold"].strip()
91
+
92
+ if isinstance(data, list) and len(data) > 0 and isinstance(data[0], dict):
93
+ val = data[0].get(mode) or data[0].get("reasoning") or data[0].get("single_ability")
94
+ if isinstance(val, str) and val.strip():
95
+ return val.strip()
96
+
97
+ raise ScaffoldNotFoundError(
98
+ f"Ejentum API did not return a valid '{mode}' scaffold for query: {query!r}"
99
+ )
100
+
101
+ def augment(self, prompt: str, mode: str = "reasoning") -> str:
102
+ """Prepend a cognitive scaffold block to a raw prompt string."""
103
+ scaffold_text = self.scaffold(query=prompt, mode=mode)
104
+ instruction = (
105
+ "Apply the cognitive scaffold below, then answer the user's task.\n\n"
106
+ f"[COGNITIVE SCAFFOLD]\n{scaffold_text}\n[END SCAFFOLD]\n\n"
107
+ )
108
+ return f"{instruction}{prompt}"
109
+
110
+ def augment_messages(
111
+ self, messages: List[Dict[str, Any]], mode: str = "reasoning"
112
+ ) -> List[Dict[str, Any]]:
113
+ """Inject a cognitive scaffold into an OpenAI/Anthropic messages array.
114
+
115
+ Finds the last user message to use as the query, then prepends the scaffold
116
+ instruction to the system message (or creates one at index 0).
117
+ """
118
+ if not messages:
119
+ return messages
120
+
121
+ # Find last user prompt as query
122
+ user_query = ""
123
+ for msg in reversed(messages):
124
+ if msg.get("role") == "user":
125
+ content = msg.get("content", "")
126
+ if isinstance(content, str):
127
+ user_query = content
128
+ elif isinstance(content, list):
129
+ # Multi-modal / block format
130
+ for part in content:
131
+ if isinstance(part, dict) and part.get("type") == "text":
132
+ user_query = part.get("text", "")
133
+ break
134
+ break
135
+
136
+ if not user_query:
137
+ user_query = "analyze and execute instructions"
138
+
139
+ scaffold_text = self.scaffold(query=user_query, mode=mode)
140
+ instruction = (
141
+ "Apply the cognitive scaffold below, then execute the user's task.\n\n"
142
+ f"[COGNITIVE SCAFFOLD]\n{scaffold_text}\n[END SCAFFOLD]"
143
+ )
144
+
145
+ new_messages = [dict(m) for m in messages]
146
+
147
+ if new_messages[0].get("role") == "system":
148
+ existing_sys = new_messages[0].get("content", "")
149
+ new_messages[0]["content"] = f"{instruction}\n\n{existing_sys}"
150
+ else:
151
+ new_messages.insert(0, {"role": "system", "content": instruction})
152
+
153
+ return new_messages
ejentum/exceptions.py ADDED
@@ -0,0 +1,21 @@
1
+ class EjentumError(Exception):
2
+ """Base exception for all Ejentum SDK errors."""
3
+ pass
4
+
5
+
6
+ class AuthenticationError(EjentumError):
7
+ """Raised when an API key is missing or rejected (HTTP 401)."""
8
+ pass
9
+
10
+
11
+ class APIError(EjentumError):
12
+ """Raised when the Ejentum API returns an unexpected error."""
13
+ def __init__(self, message: str, status_code: int = 500, response_body: str = ""):
14
+ super().__init__(message)
15
+ self.status_code = status_code
16
+ self.response_body = response_body
17
+
18
+
19
+ class ScaffoldNotFoundError(EjentumError):
20
+ """Raised when the Ejentum engine cannot produce a valid scaffold."""
21
+ pass
ejentum/wrappers.py ADDED
@@ -0,0 +1,101 @@
1
+ """
2
+ Drop-in wrappers for popular LLM provider clients (OpenAI, Anthropic).
3
+ Automatically intercepts chat completion calls to inject Ejentum cognitive scaffolds in <80ms.
4
+ """
5
+
6
+ from __future__ import annotations
7
+
8
+ import functools
9
+ from typing import Any, Optional
10
+
11
+ from .client import Ejentum
12
+
13
+
14
+ def wrap_openai(client: Any, ejentum_client: Optional[Ejentum] = None) -> Any:
15
+ """Wrap an official OpenAI client to automatically scaffold chat completions.
16
+
17
+ Example:
18
+ >>> from openai import OpenAI
19
+ >>> from ejentum import wrap_openai
20
+ >>> client = wrap_openai(OpenAI())
21
+ >>> response = client.chat.completions.create(
22
+ ... model="gpt-4o",
23
+ ... messages=[{"role": "user", "content": "Diagnose latency spike"}],
24
+ ... ejentum_mode="reasoning",
25
+ ... )
26
+ """
27
+ if ejentum_client is None:
28
+ ejentum_client = Ejentum()
29
+
30
+ orig_create = client.chat.completions.create
31
+
32
+ @functools.wraps(orig_create)
33
+ def wrapped_create(*args: Any, **kwargs: Any) -> Any:
34
+ mode = kwargs.pop("ejentum_mode", "reasoning")
35
+ enabled = kwargs.pop("ejentum_enabled", True)
36
+
37
+ if enabled and "messages" in kwargs:
38
+ kwargs["messages"] = ejentum_client.augment_messages(
39
+ messages=kwargs["messages"], mode=mode
40
+ )
41
+
42
+ return orig_create(*args, **kwargs)
43
+
44
+ client.chat.completions.create = wrapped_create
45
+ return client
46
+
47
+
48
+ def wrap_anthropic(client: Any, ejentum_client: Optional[Ejentum] = None) -> Any:
49
+ """Wrap an official Anthropic client to automatically scaffold message creations.
50
+
51
+ Example:
52
+ >>> from anthropic import Anthropic
53
+ >>> from ejentum import wrap_anthropic
54
+ >>> client = wrap_anthropic(Anthropic())
55
+ >>> response = client.messages.create(
56
+ ... model="claude-3-7-sonnet-20250219",
57
+ ... max_tokens=1024,
58
+ ... messages=[{"role": "user", "content": "Diagnose latency spike"}],
59
+ ... ejentum_mode="reasoning",
60
+ ... )
61
+ """
62
+ if ejentum_client is None:
63
+ ejentum_client = Ejentum()
64
+
65
+ orig_create = client.messages.create
66
+
67
+ @functools.wraps(orig_create)
68
+ def wrapped_create(*args: Any, **kwargs: Any) -> Any:
69
+ mode = kwargs.pop("ejentum_mode", "reasoning")
70
+ enabled = kwargs.pop("ejentum_enabled", True)
71
+
72
+ if enabled and "messages" in kwargs:
73
+ # Get last user prompt for scaffold query
74
+ user_query = ""
75
+ for msg in reversed(kwargs["messages"]):
76
+ if msg.get("role") == "user":
77
+ content = msg.get("content", "")
78
+ if isinstance(content, str):
79
+ user_query = content
80
+ break
81
+
82
+ if not user_query:
83
+ user_query = "execute instructions"
84
+
85
+ scaffold_text = ejentum_client.scaffold(query=user_query, mode=mode)
86
+ instruction = (
87
+ "Apply the cognitive scaffold below, then execute the user's task.\n\n"
88
+ f"[COGNITIVE SCAFFOLD]\n{scaffold_text}\n[END SCAFFOLD]"
89
+ )
90
+
91
+ # Anthropic takes system as a top-level parameter
92
+ existing_system = kwargs.get("system", "")
93
+ if existing_system:
94
+ kwargs["system"] = f"{instruction}\n\n{existing_system}"
95
+ else:
96
+ kwargs["system"] = instruction
97
+
98
+ return orig_create(*args, **kwargs)
99
+
100
+ client.messages.create = wrapped_create
101
+ return client
@@ -0,0 +1,176 @@
1
+ Metadata-Version: 2.4
2
+ Name: ejentum
3
+ Version: 0.1.0
4
+ Summary: Deterministic Reasoning-Augmented Retrieval (RAR) Cognitive Infrastructure SDK
5
+ Author-email: Bob Franks <contact@ejentum.com>, Ejentum Team <contact@ejentum.com>
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://ejentum.com
8
+ Project-URL: Documentation, https://ejentum.com/docs
9
+ Project-URL: Repository, https://github.com/DrFauchi/ejentum-core
10
+ Keywords: reasoning,prompt-engineering,llm,cognitive-scaffolding,openai,anthropic,langchain,ai-agents
11
+ Classifier: Development Status :: 4 - Beta
12
+ Classifier: Intended Audience :: Developers
13
+ Classifier: Programming Language :: Python :: 3
14
+ Classifier: Programming Language :: Python :: 3.8
15
+ Classifier: Programming Language :: Python :: 3.9
16
+ Classifier: Programming Language :: Python :: 3.10
17
+ Classifier: Programming Language :: Python :: 3.11
18
+ Classifier: Programming Language :: Python :: 3.12
19
+ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
20
+ Requires-Python: >=3.8
21
+ Description-Content-Type: text/markdown
22
+ Provides-Extra: all
23
+ Requires-Dist: openai; extra == "all"
24
+ Requires-Dist: anthropic; extra == "all"
25
+ Provides-Extra: dev
26
+ Requires-Dist: pytest; extra == "dev"
27
+ Requires-Dist: pytest-mock; extra == "dev"
28
+
29
+ # Ejentum Python SDK
30
+
31
+ [![PyPI Version](https://img.shields.io/badge/pypi-0.1.0-blue.svg)](https://pypi.org/project/ejentum/)
32
+ [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
33
+ [![Latency](https://img.shields.io/badge/API%20Latency-%3C80ms-neon)](https://api.ejentum.com)
34
+
35
+ The official Python SDK for **Ejentum** — Deterministic Reasoning-Augmented Retrieval (RAR) Cognitive Infrastructure.
36
+
37
+ Ejentum indexes 300+ deterministic mental models and cognitive scaffolds. In `<80ms`, it retrieves and injects the optimal reasoning scaffold into your LLM prompt, eliminating hallucinated leaps, sycophantic shortcuts, and premature convergence in production AI agents.
38
+
39
+ ---
40
+
41
+ ## ⚡ Installation
42
+
43
+ ```bash
44
+ pip install ejentum
45
+ ```
46
+
47
+ *Zero dependencies required. Uses Python standard library only.*
48
+
49
+ ---
50
+
51
+ ## 🔑 Authentication
52
+
53
+ Export your API key in your environment (or pass `api_key="..."` directly to the client):
54
+
55
+ ```bash
56
+ export EJENTUM_API_KEY="ej_live_your_key_here"
57
+ ```
58
+
59
+ *Need an API key? Get instant access at [ejentum.com/pricing](https://ejentum.com/pricing).*
60
+
61
+ ---
62
+
63
+ ## 🚀 Quickstart
64
+
65
+ ### 1. Basic Scaffold Retrieval
66
+
67
+ ```python
68
+ from ejentum import Ejentum
69
+
70
+ client = Ejentum()
71
+
72
+ # Retrieve the deterministic cognitive scaffold for any query (<80ms)
73
+ scaffold = client.scaffold("diagnose PostgreSQL high CPU and lock contention")
74
+ print(scaffold)
75
+ ```
76
+
77
+ ### 2. Auto-Augment a Prompt
78
+
79
+ ```python
80
+ # Automatically prepends the scaffold instruction block to your task prompt
81
+ prompt = "Design a failover strategy for our payment processing service."
82
+ augmented_prompt = client.augment(prompt, mode="reasoning")
83
+
84
+ print(augmented_prompt)
85
+ # Output:
86
+ # Apply the cognitive scaffold below, then answer the user's task.
87
+ # [COGNITIVE SCAFFOLD]
88
+ # ... [Deterministic Causal / Resiliency Scaffold] ...
89
+ # [END SCAFFOLD]
90
+ # Design a failover strategy for our payment processing service.
91
+ ```
92
+
93
+ ---
94
+
95
+ ## 🔌 1-Line Drop-in Wrappers
96
+
97
+ ### OpenAI Drop-in
98
+
99
+ Wrap your existing `OpenAI()` client. All `chat.completions.create` calls will automatically fetch and inject the optimal Ejentum scaffold before invoking OpenAI:
100
+
101
+ ```python
102
+ from openai import OpenAI
103
+ from ejentum import wrap_openai
104
+
105
+ # Wrap your existing client in 1 line:
106
+ client = wrap_openai(OpenAI())
107
+
108
+ response = client.chat.completions.create(
109
+ model="gpt-4o",
110
+ messages=[
111
+ {"role": "user", "content": "Diagnose silent failure in checkout webhooks"}
112
+ ],
113
+ ejentum_mode="reasoning" # Optional: defaults to "reasoning"
114
+ )
115
+
116
+ print(response.choices[0].message.content)
117
+ ```
118
+
119
+ ### Anthropic Drop-in
120
+
121
+ ```python
122
+ from anthropic import Anthropic
123
+ from ejentum import wrap_anthropic
124
+
125
+ client = wrap_anthropic(Anthropic())
126
+
127
+ response = client.messages.create(
128
+ model="claude-3-7-sonnet-20250219",
129
+ max_tokens=1024,
130
+ messages=[
131
+ {"role": "user", "content": "Refactor auth token refresh to prevent race condition"}
132
+ ]
133
+ )
134
+
135
+ print(response.content[0].text)
136
+ ```
137
+
138
+ ### LangChain / Agent Loop Integration
139
+
140
+ ```python
141
+ from ejentum import Ejentum
142
+ from langchain_core.prompts import ChatPromptTemplate
143
+ from langchain_openai import ChatOpenAI
144
+
145
+ ejentum = Ejentum()
146
+
147
+ def scaffold_runnable(inputs):
148
+ scaffold = ejentum.scaffold(inputs["task"])
149
+ return {
150
+ "system_scaffold": f"Apply this scaffold:\n{scaffold}",
151
+ "task": inputs["task"]
152
+ }
153
+
154
+ prompt = ChatPromptTemplate.from_messages([
155
+ ("system", "{system_scaffold}"),
156
+ ("user", "{task}")
157
+ ])
158
+
159
+ chain = scaffold_runnable | prompt | ChatOpenAI(model="gpt-4o")
160
+ result = chain.invoke({"task": "Plan a zero-downtime database migration for 50M rows."})
161
+ ```
162
+
163
+ ---
164
+
165
+ ## 🛠️ API Reference
166
+
167
+ ### `Ejentum(api_key=None, base_url="https://api.ejentum.com/logicv1/", timeout=10.0)`
168
+ * `scaffold(query: str, mode="reasoning") -> str`: Returns the raw cognitive scaffold string.
169
+ * `augment(prompt: str, mode="reasoning") -> str`: Returns the prompt augmented with cognitive scaffolding.
170
+ * `augment_messages(messages: list[dict], mode="reasoning") -> list[dict]`: Augments an OpenAI/Anthropic messages list in-place or prepends to the system message.
171
+ * `get_ability(query: str, mode="reasoning") -> dict`: Returns the full metadata payload including `ability_id` and matched `domain`.
172
+
173
+ ---
174
+
175
+ ## 📄 License
176
+ MIT © [Ejentum.com](https://ejentum.com)
@@ -0,0 +1,8 @@
1
+ ejentum/__init__.py,sha256=G-1j1LbUEOosnm6eDYh8zseHBg9pQ6Heg4LRTDcv56o,436
2
+ ejentum/client.py,sha256=bMIrCeKvnwCtgnRGoTAbKBBQxPoei9LRqEzMopLNU7M,6189
3
+ ejentum/exceptions.py,sha256=CiNpOEe4sKCMDSzgjON5JoQoZJyb6tad9zOluvcudGQ,643
4
+ ejentum/wrappers.py,sha256=lCK84ErYyvy-tXySqyOS0LA3Fnr0v2FouM2z8sYthOg,3517
5
+ ejentum-0.1.0.dist-info/METADATA,sha256=-QL0E1L_EYulqFlLjqpngdf5h82kxtoRGpoN1NFzDDc,5704
6
+ ejentum-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
7
+ ejentum-0.1.0.dist-info/top_level.txt,sha256=bYW5mCnQK73WWQlPME617ssTu3peixpFOhFPAYbVHCs,8
8
+ ejentum-0.1.0.dist-info/RECORD,,
@@ -0,0 +1,5 @@
1
+ Wheel-Version: 1.0
2
+ Generator: setuptools (84.0.0)
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
5
+
@@ -0,0 +1 @@
1
+ ejentum