noetix 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.
noetix/__init__.py ADDED
@@ -0,0 +1,129 @@
1
+ """The Noetix SDK for Python: your company brain, from code.
2
+
3
+ from noetix import Noetix
4
+
5
+ noetix = Noetix() # reads NOETIX_API_KEY
6
+ evidence = noetix.brain.recall("What did we decide about pricing?")
7
+ for source in evidence.sources:
8
+ print(source.title, source.url)
9
+
10
+ The company brain (``brain``, ``pages``, ``skills``, ``gaps``, ``blockers``) is shared by the
11
+ whole workspace. ``memory`` and ``profile`` are the key owner's own and private: never the
12
+ brain. ``AsyncNoetix`` has the same methods as coroutines.
13
+ """
14
+
15
+ from ._client import (
16
+ DEFAULT_BASE_URL,
17
+ DEFAULT_MAX_RETRIES,
18
+ DEFAULT_TIMEOUT,
19
+ AsyncNoetix,
20
+ Noetix,
21
+ UsageWarning,
22
+ )
23
+ from ._errors import (
24
+ AIKeyError,
25
+ AllowanceUsedUpError,
26
+ AmbiguousError,
27
+ APIConnectionError,
28
+ APITimeoutError,
29
+ AuthenticationError,
30
+ BadRequestError,
31
+ BudgetExceededError,
32
+ ConflictError,
33
+ InternalServerError,
34
+ NoetixError,
35
+ NotFoundError,
36
+ PermissionDeniedError,
37
+ PlanFeatureError,
38
+ PlanLimitError,
39
+ RateLimitError,
40
+ StaleVersionError,
41
+ UnprocessableError,
42
+ WorkspaceClosedError,
43
+ )
44
+ from ._types import (
45
+ AddResult,
46
+ Answer,
47
+ ApiKey,
48
+ Author,
49
+ Authors,
50
+ Blockers,
51
+ BrainMap,
52
+ BrainStatus,
53
+ Changes,
54
+ Entity,
55
+ EntityPath,
56
+ Evidence,
57
+ Gap,
58
+ Memory,
59
+ NoteResult,
60
+ Page,
61
+ PageDiff,
62
+ PageEdit,
63
+ PageVersion,
64
+ Passage,
65
+ Profile,
66
+ ReplacedBy,
67
+ Skill,
68
+ Source,
69
+ Topic,
70
+ Usage,
71
+ Workspace,
72
+ )
73
+ from ._version import __version__
74
+
75
+ __all__ = [
76
+ "DEFAULT_BASE_URL",
77
+ "DEFAULT_MAX_RETRIES",
78
+ "DEFAULT_TIMEOUT",
79
+ "AIKeyError",
80
+ "APIConnectionError",
81
+ "APITimeoutError",
82
+ "AddResult",
83
+ "AllowanceUsedUpError",
84
+ "AmbiguousError",
85
+ "Answer",
86
+ "ApiKey",
87
+ "AsyncNoetix",
88
+ "AuthenticationError",
89
+ "Author",
90
+ "Authors",
91
+ "BadRequestError",
92
+ "Blockers",
93
+ "BrainMap",
94
+ "BrainStatus",
95
+ "BudgetExceededError",
96
+ "Changes",
97
+ "ConflictError",
98
+ "Entity",
99
+ "EntityPath",
100
+ "Evidence",
101
+ "Gap",
102
+ "InternalServerError",
103
+ "Memory",
104
+ "Noetix",
105
+ "NoetixError",
106
+ "NotFoundError",
107
+ "NoteResult",
108
+ "Page",
109
+ "PageDiff",
110
+ "PageEdit",
111
+ "PageVersion",
112
+ "Passage",
113
+ "PermissionDeniedError",
114
+ "PlanFeatureError",
115
+ "PlanLimitError",
116
+ "Profile",
117
+ "RateLimitError",
118
+ "ReplacedBy",
119
+ "Skill",
120
+ "Source",
121
+ "StaleVersionError",
122
+ "Topic",
123
+ "UnprocessableError",
124
+ "Usage",
125
+ "UsageWarning",
126
+ "Workspace",
127
+ "WorkspaceClosedError",
128
+ "__version__",
129
+ ]
@@ -0,0 +1,414 @@
1
+ """GENERATED by scripts/generate_async.py from _resources.py: do not edit.
2
+
3
+ The resources of :class:`noetix.AsyncNoetix`: ``brain``, ``pages``, ``skills``, ``gaps``,
4
+ ``blockers``, ``memory``, ``profile``, ``workspace``, ``usage`` and ``api_keys``.
5
+ """
6
+
7
+ # fmt: off
8
+ from __future__ import annotations
9
+
10
+ from typing import TYPE_CHECKING, Dict, List, Optional, Sequence
11
+
12
+ from . import _flows as flows
13
+ from ._flows import EditPair, FileInput
14
+ from ._types import (
15
+ AddResult,
16
+ Answer,
17
+ ApiKey,
18
+ Authors,
19
+ Blockers,
20
+ BrainMap,
21
+ BrainStatus,
22
+ Changes,
23
+ Entity,
24
+ EntityPath,
25
+ Evidence,
26
+ Gap,
27
+ Memory,
28
+ NoteResult,
29
+ Page,
30
+ PageDiff,
31
+ PageEdit,
32
+ PageVersion,
33
+ Profile,
34
+ Skill,
35
+ Topic,
36
+ Usage,
37
+ Workspace,
38
+ )
39
+
40
+ if TYPE_CHECKING:
41
+ from ._client import AsyncNoetix
42
+
43
+
44
+ class _Resource:
45
+ def __init__(self, client: "AsyncNoetix"):
46
+ self._run = client._run
47
+
48
+
49
+ class Brain(_Resource):
50
+ """The company brain: what the business knows, from its pages, files and connected tools."""
51
+
52
+ async def recall(
53
+ self,
54
+ query: str,
55
+ *,
56
+ scope: str = "focused",
57
+ max_chars: Optional[int] = None,
58
+ per_source: Optional[int] = None,
59
+ ) -> Evidence:
60
+ """The evidence for a question: the sources the brain read, with their passages.
61
+
62
+ Cite each claim with the source it came from (``source.title``, ``source.url``).
63
+ ``scope="broad"`` is for questions about the whole company or an area: it also returns
64
+ the brain's topics, the most relevant first (a second API call). ``max_chars``
65
+ (1,000 to 40,000, default 12,000) caps the passages' total length, ``per_source``
66
+ (1 to 10, default 3) the passages per source. No AI model writes anything here.
67
+ """
68
+ return await self._run(flows.recall(query, scope, max_chars, per_source))
69
+
70
+ async def answer(
71
+ self, query: str, *, search_type: Optional[str] = None, top_k: Optional[int] = None
72
+ ) -> Answer:
73
+ """A written answer from the brain's own model. Counts toward the workspace's AI usage.
74
+
75
+ Prefer :meth:`recall` when your own model writes the answer: it returns the sources to
76
+ cite. ``search_type`` picks the retrieval strategy (``"GRAPH_COMPLETION"`` by default,
77
+ ``"RAG_COMPLETION"``, ``"CHUNKS"``…).
78
+ """
79
+ return await self._run(flows.answer(query, search_type, top_k))
80
+
81
+ async def add(
82
+ self,
83
+ text: Optional[str] = None,
84
+ *,
85
+ file: Optional[FileInput] = None,
86
+ url: Optional[str] = None,
87
+ filename: Optional[str] = None,
88
+ ) -> AddResult:
89
+ """Put knowledge in the brain: some ``text``, a ``file`` (path, bytes or binary file) or
90
+ a ``url``. It is built in the background; ask about it a little later.
91
+
92
+ Each call becomes a document of its own. To keep a document you will edit, create a
93
+ page instead (:meth:`Pages.create`).
94
+ """
95
+ return await self._run(flows.add(text, file, url, filename))
96
+
97
+ async def status(self) -> BrainStatus:
98
+ """How many items the brain holds, and how many are still being built."""
99
+ return await self._run(flows.status())
100
+
101
+ async def map(self) -> BrainMap:
102
+ """What the brain is about: every topic of its pages. A guide to where to look: read
103
+ and cite the pages it names, never the map."""
104
+ return await self._run(flows.brain_map(None))
105
+
106
+ async def topic(self, name: str) -> Topic:
107
+ """One topic of the map: its summary, latest changes and pages."""
108
+ return await self._run(flows.brain_map(name))
109
+
110
+ async def entity(self, name: str) -> Entity:
111
+ """One thing the brain knows about, its links and the pages that mention it."""
112
+ return await self._run(flows.entity(name))
113
+
114
+ async def path(self, start: str, goal: str) -> EntityPath:
115
+ """How two things connect, link by link, with the pages behind each link."""
116
+ return await self._run(flows.entity_path(start, goal))
117
+
118
+ async def changes(self, since: Optional[str] = None) -> Changes:
119
+ """What changed since ``since`` (an ISO date or time; default a week ago, at most 90
120
+ days): what the company changed first, then pages and synced sources."""
121
+ return await self._run(flows.changes(since))
122
+
123
+ async def authors(self, topic: str, *, limit: Optional[int] = None) -> Authors:
124
+ """Who wrote the pages about ``topic``, most pages first. Authorship, not expertise."""
125
+ return await self._run(flows.authors(topic, limit))
126
+
127
+
128
+ class Pages(_Resource):
129
+ """Pages: documents the brain is the home of, edited in place with full history.
130
+
131
+ Every method that takes ``ref`` accepts a page id, or a title, slug or part of a title
132
+ matching exactly one page (else :class:`~noetix.AmbiguousError`).
133
+ """
134
+
135
+ async def list(self) -> List[Page]:
136
+ """Every page, without content."""
137
+ return await self._run(flows.pages_list())
138
+
139
+ async def resolve(self, ref: str) -> List[Page]:
140
+ """The pages matching an id, title, slug or part of a title."""
141
+ return await self._run(flows.pages_resolve(ref))
142
+
143
+ async def get(self, ref: str) -> Page:
144
+ """One page with its current content."""
145
+ return await self._run(flows.pages_get(ref))
146
+
147
+ async def create(
148
+ self,
149
+ title: str,
150
+ content: str,
151
+ *,
152
+ summary: str = "",
153
+ change: Optional[str] = None,
154
+ change_reason: Optional[str] = None,
155
+ effective_on: Optional[str] = None,
156
+ wait: bool = False,
157
+ ) -> Page:
158
+ """A new page. Pass ``change`` when it records something the company changed or decided
159
+ (see :meth:`edit`). ``wait=True`` returns only once the brain has built it."""
160
+ return await self._run(
161
+ flows.pages_create(title, content, summary, change, change_reason, effective_on, wait)
162
+ )
163
+
164
+ async def edit(
165
+ self,
166
+ ref: str,
167
+ old_text: Optional[str] = None,
168
+ new_text: Optional[str] = None,
169
+ *,
170
+ edits: Optional[Sequence[EditPair]] = None,
171
+ base_version: Optional[int] = None,
172
+ summary: str = "",
173
+ change: Optional[str] = None,
174
+ change_reason: Optional[str] = None,
175
+ effective_on: Optional[str] = None,
176
+ wait: bool = False,
177
+ ) -> PageEdit:
178
+ """Replace ``old_text``, which must appear exactly once, with ``new_text``. An empty
179
+ ``old_text`` appends. ``edits=[(old, new), ...]`` applies several at once.
180
+
181
+ Pass the ``base_version`` you read to be refused (:class:`~noetix.StaleVersionError`)
182
+ rather than edit a page someone changed since. When the edit changes what the company
183
+ does (a price, an owner, a rule), set ``change`` to what changed, in one line;
184
+ ``change_reason`` says why and ``effective_on`` (YYYY-MM-DD) when it took effect.
185
+ """
186
+ return await self._run(
187
+ flows.pages_edit(
188
+ ref,
189
+ old_text,
190
+ new_text,
191
+ edits,
192
+ base_version,
193
+ summary,
194
+ change,
195
+ change_reason,
196
+ effective_on,
197
+ wait,
198
+ )
199
+ )
200
+
201
+ async def replace(
202
+ self,
203
+ ref: str,
204
+ content: str,
205
+ *,
206
+ base_version: int,
207
+ summary: str = "",
208
+ change: Optional[str] = None,
209
+ change_reason: Optional[str] = None,
210
+ effective_on: Optional[str] = None,
211
+ wait: bool = False,
212
+ ) -> PageEdit:
213
+ """Replace the whole content. ``base_version`` is required: the version you read."""
214
+ return await self._run(
215
+ flows.pages_replace(
216
+ ref, content, base_version, summary, change, change_reason, effective_on, wait
217
+ )
218
+ )
219
+
220
+ async def note(self, text: str) -> NoteResult:
221
+ """Add a dated line to the Notes page, for a fact with no page of its own."""
222
+ return await self._run(flows.pages_note(text))
223
+
224
+ async def history(self, ref: str) -> List[PageVersion]:
225
+ """The page's versions, newest first. Versions with ``change`` set changed what the
226
+ company does; the rest only changed wording."""
227
+ return await self._run(flows.pages_history(ref))
228
+
229
+ async def version(self, ref: str, version: int) -> PageVersion:
230
+ """One past version with its content: what the page said then, not now."""
231
+ return await self._run(flows.pages_version(ref, version))
232
+
233
+ async def diff(self, ref: str, old: int, new: int) -> PageDiff:
234
+ """How two versions differ."""
235
+ return await self._run(flows.pages_diff(ref, old, new))
236
+
237
+ async def revert(self, ref: str, version: int) -> Page:
238
+ """Bring back what ``version`` said, as a new version. Nothing is lost."""
239
+ return await self._run(flows.pages_revert(ref, version))
240
+
241
+ async def delete(self, ref: str) -> Page:
242
+ """Take a page out of the brain. It can be restored (:meth:`restore`). Admins only."""
243
+ return await self._run(flows.pages_delete(ref))
244
+
245
+ async def deleted(self) -> List[Page]:
246
+ """Pages that were deleted and can be restored."""
247
+ return await self._run(flows.pages_deleted())
248
+
249
+ async def restore(self, page_id: str) -> Page:
250
+ """Bring a deleted page back, by its id (see :meth:`deleted`)."""
251
+ return await self._run(flows.pages_restore(page_id))
252
+
253
+
254
+ class Skills(_Resource):
255
+ """Skills: how the company does things, written procedures agents follow."""
256
+
257
+ async def list(self, status: str = "active") -> List[Skill]:
258
+ """The skills with ``status``: ``"active"`` (what agents are served), ``"draft"``,
259
+ ``"archived"`` or ``"all"``."""
260
+ return await self._run(flows.skills_list(status))
261
+
262
+ async def search(self, query: str, *, limit: Optional[int] = None) -> List[Skill]:
263
+ """Skills relevant to a task, most relevant first (up to ``limit``, default 10).
264
+ Nothing is returned when no skill is close enough."""
265
+ return await self._run(flows.skills_search(query, limit))
266
+
267
+ async def get(self, skill_id: str) -> Skill:
268
+ """One skill with its procedure and SKILL.md."""
269
+ return await self._run(flows.skills_get(skill_id))
270
+
271
+ async def use(self, name: str) -> Skill:
272
+ """The active skill called ``name``, with its procedure and the pages it relies on.
273
+ Records that it was used."""
274
+ return await self._run(flows.skills_use(name))
275
+
276
+ async def create(
277
+ self,
278
+ document: Optional[str] = None,
279
+ *,
280
+ name: Optional[str] = None,
281
+ description: Optional[str] = None,
282
+ procedure: Optional[str] = None,
283
+ files: Optional[Dict[str, str]] = None,
284
+ draft: bool = False,
285
+ ) -> Skill:
286
+ """A new skill, from a whole SKILL.md (``document``) or from its parts.
287
+
288
+ A member's new skill is always a draft until an admin publishes it; ``draft=True``
289
+ keeps an admin's one a draft too. ``files`` maps a path to its contents.
290
+ """
291
+ return await self._run(flows.skills_create(document, name, description, procedure, files, draft))
292
+
293
+
294
+ class Gaps(_Resource):
295
+ """Knowledge gaps: questions the brain had nothing for, most asked first."""
296
+
297
+ async def list(self, status: str = "open", *, limit: Optional[int] = None) -> List[Gap]:
298
+ """Gaps with ``status`` (``"open"``, ``"filled"``, ``"dismissed"`` or ``"all"``)."""
299
+ return await self._run(flows.gaps_list(status, limit))
300
+
301
+ async def flag(self, question: str, *, context: Optional[str] = None) -> Gap:
302
+ """Record a question the brain couldn't answer. The same question counts again."""
303
+ return await self._run(flows.gaps_flag(question, context))
304
+
305
+ async def close(
306
+ self,
307
+ gap_id: str,
308
+ status: str = "filled",
309
+ *,
310
+ note: Optional[str] = None,
311
+ page_id: Optional[str] = None,
312
+ ) -> Gap:
313
+ """Mark a gap ``"filled"`` (``page_id``: the page that answers it) or ``"dismissed"``."""
314
+ return await self._run(flows.gaps_close(gap_id, status, note, page_id))
315
+
316
+
317
+ class BlockersResource(_Resource):
318
+ """What is stuck in connected Linear and GitHub."""
319
+
320
+ async def list(self) -> Blockers:
321
+ """Blocked, overdue and stale work, projects at risk, urgent work nobody owns."""
322
+ return await self._run(flows.blockers())
323
+
324
+
325
+ class MemoryResource(_Resource):
326
+ """The key owner's private memory: what agents learned about them. Never the brain.
327
+
328
+ A key acts as the person who created it, so these are *that person's* memories. Don't use
329
+ a personal key in a service other people talk to.
330
+ """
331
+
332
+ async def list(self) -> List[Memory]:
333
+ """Every saved memory."""
334
+ return await self._run(flows.memory_list())
335
+
336
+ async def add(self, text: str, kind: str, *, source: Optional[str] = None) -> Memory:
337
+ """Save a memory. ``kind``: ``"preference"`` (how they like things done), ``"about_me"``
338
+ (their role and background) or ``"work"`` (their current work, this workspace only).
339
+ ``duplicate`` on the result means the same text was already saved; ``over_cap`` that
340
+ more are saved than agents load, so tidy up."""
341
+ return await self._run(flows.memory_add(text, kind, source))
342
+
343
+ async def edit(self, memory_id: str, text: str) -> Memory:
344
+ """Rewrite a memory."""
345
+ return await self._run(flows.memory_edit(memory_id, text))
346
+
347
+ async def delete(self, memory_id: str) -> None:
348
+ """Forget a memory."""
349
+ return await self._run(flows.memory_delete(memory_id))
350
+
351
+
352
+ class ProfileResource(_Resource):
353
+ """The key owner's profile: what they want agents to know about them. Private to them."""
354
+
355
+ async def get(self) -> Profile:
356
+ """The profile, with every memory."""
357
+ return await self._run(flows.profile_get())
358
+
359
+ async def update(
360
+ self,
361
+ *,
362
+ call_me: Optional[str] = None,
363
+ work: Optional[str] = None,
364
+ preferences: Optional[str] = None,
365
+ memory_on: Optional[bool] = None,
366
+ ) -> Profile:
367
+ """Change the fields you pass; the rest stay as they are."""
368
+ return await self._run(flows.profile_update(call_me, work, preferences, memory_on))
369
+
370
+
371
+ class WorkspaceResource(_Resource):
372
+ """The workspace the key belongs to."""
373
+
374
+ async def get(self) -> Workspace:
375
+ """Its name, your role and its plan."""
376
+ return await self._run(flows.workspace_get())
377
+
378
+
379
+ class UsageResource(_Resource):
380
+ """What the workspace uses against its plan."""
381
+
382
+ async def get(self) -> Usage:
383
+ """The plan, each limit and what is used, this month's API calls and AI usage."""
384
+ return await self._run(flows.usage_get())
385
+
386
+
387
+ class ApiKeys(_Resource):
388
+ """API keys of the key's owner. A key acts as the person who created it."""
389
+
390
+ async def list(self) -> List[ApiKey]:
391
+ """Your keys, masked."""
392
+ return await self._run(flows.api_keys_list())
393
+
394
+ async def create(self, name: Optional[str] = None) -> ApiKey:
395
+ """A new key. Its ``key`` is shown this once: store it now."""
396
+ return await self._run(flows.api_keys_create(name))
397
+
398
+ async def delete(self, key_id: str) -> None:
399
+ """Delete a key. Anything using it stops working at once."""
400
+ return await self._run(flows.api_keys_delete(key_id))
401
+
402
+
403
+ __all__ = [
404
+ "ApiKeys",
405
+ "BlockersResource",
406
+ "Brain",
407
+ "Gaps",
408
+ "MemoryResource",
409
+ "Pages",
410
+ "ProfileResource",
411
+ "Skills",
412
+ "UsageResource",
413
+ "WorkspaceResource",
414
+ ]