penhin 0.1.1__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 (47) hide show
  1. penhin/__init__.py +61 -0
  2. penhin/_async.py +53 -0
  3. penhin/_atomic.py +41 -0
  4. penhin/_checkpoints.py +92 -0
  5. penhin/agent.py +497 -0
  6. penhin/auth/__init__.py +31 -0
  7. penhin/auth/browser.py +31 -0
  8. penhin/auth/interaction.py +8 -0
  9. penhin/auth/models.py +70 -0
  10. penhin/auth/oauth/__init__.py +5 -0
  11. penhin/auth/oauth/_flows.py +447 -0
  12. penhin/auth/providers.py +82 -0
  13. penhin/auth/resolver.py +45 -0
  14. penhin/auth/secrets.py +83 -0
  15. penhin/auth/service.py +70 -0
  16. penhin/auth/storage.py +261 -0
  17. penhin/budget.py +111 -0
  18. penhin/cancellation.py +95 -0
  19. penhin/context/__init__.py +13 -0
  20. penhin/context/_preparation.py +240 -0
  21. penhin/context/compaction.py +194 -0
  22. penhin/context/projection.py +31 -0
  23. penhin/context/tokens.py +111 -0
  24. penhin/events.py +165 -0
  25. penhin/execution.py +141 -0
  26. penhin/models/__init__.py +20 -0
  27. penhin/models/client.py +263 -0
  28. penhin/models/messages.py +128 -0
  29. penhin/models/profiles.py +86 -0
  30. penhin/models/retry.py +90 -0
  31. penhin/models/types.py +52 -0
  32. penhin/plugins.py +138 -0
  33. penhin/providers/__init__.py +13 -0
  34. penhin/providers/_payloads.py +120 -0
  35. penhin/providers/anthropic.py +182 -0
  36. penhin/providers/deepseek.py +248 -0
  37. penhin/providers/gemini.py +246 -0
  38. penhin/providers/openai.py +375 -0
  39. penhin/providers/registry.py +89 -0
  40. penhin/py.typed +0 -0
  41. penhin/session.py +408 -0
  42. penhin/tools.py +185 -0
  43. penhin-0.1.1.dist-info/METADATA +407 -0
  44. penhin-0.1.1.dist-info/RECORD +47 -0
  45. penhin-0.1.1.dist-info/WHEEL +5 -0
  46. penhin-0.1.1.dist-info/licenses/LICENSE +21 -0
  47. penhin-0.1.1.dist-info/top_level.txt +1 -0
penhin/__init__.py ADDED
@@ -0,0 +1,61 @@
1
+ """Penhin: an embeddable Agent core; applications supply identity and capabilities."""
2
+
3
+ from .context import AutoCompaction, Compactor, Context, model_summarizer
4
+ from .plugins import Plugin, PluginBusy, PluginRuntime, discover_plugins, load_plugin
5
+ from .agent import Agent, InterruptedTool, Permission
6
+ from .events import AgentEvent, Event, RunResult
7
+ from .execution import ModelExecutor, ModelExecutorClosed, ModelQueueFull
8
+ from .budget import BudgetExceeded, ResourceBudget
9
+ from .models import CircuitBreaker, CircuitBreakerOpen, ModelClient
10
+ from .session import (
11
+ FileSessionStore,
12
+ MemorySessionStore,
13
+ Session,
14
+ SessionConflict,
15
+ SessionStatus,
16
+ SessionStore,
17
+ SessionView,
18
+ WaitRequest,
19
+ )
20
+ from .tools import CancellationToken, Tool, ToolContext, ToolInput, ToolResult, ToolWait, tool
21
+
22
+ __all__ = [
23
+ "Agent",
24
+ "AgentEvent",
25
+ "AutoCompaction",
26
+ "BudgetExceeded",
27
+ "CancellationToken",
28
+ "CircuitBreaker",
29
+ "CircuitBreakerOpen",
30
+ "Compactor",
31
+ "Context",
32
+ "Event",
33
+ "FileSessionStore",
34
+ "InterruptedTool",
35
+ "MemorySessionStore",
36
+ "ModelClient",
37
+ "ModelExecutor",
38
+ "ModelExecutorClosed",
39
+ "ModelQueueFull",
40
+ "Permission",
41
+ "Plugin",
42
+ "PluginBusy",
43
+ "PluginRuntime",
44
+ "RunResult",
45
+ "ResourceBudget",
46
+ "Session",
47
+ "SessionConflict",
48
+ "SessionStatus",
49
+ "SessionStore",
50
+ "SessionView",
51
+ "Tool",
52
+ "ToolContext",
53
+ "ToolInput",
54
+ "ToolResult",
55
+ "ToolWait",
56
+ "WaitRequest",
57
+ "discover_plugins",
58
+ "load_plugin",
59
+ "model_summarizer",
60
+ "tool",
61
+ ]
penhin/_async.py ADDED
@@ -0,0 +1,53 @@
1
+ """Worker execution that retains ownership until cancellation has drained the worker."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import asyncio
6
+ import contextvars
7
+ import inspect
8
+ from concurrent.futures import ThreadPoolExecutor
9
+ from typing import Any, Callable
10
+
11
+ from .cancellation import current_cancellation
12
+
13
+
14
+ async def invoke_function(function: Callable, *args: Any, **kwargs: Any) -> Any:
15
+ if inspect.iscoroutinefunction(function):
16
+ return await function(*args, **kwargs)
17
+ task = asyncio.create_task(asyncio.to_thread(function, *args, **kwargs))
18
+ value = await _drain(task)
19
+ return await value if inspect.isawaitable(value) else value
20
+
21
+
22
+ async def _drain(task: asyncio.Future) -> Any:
23
+ try:
24
+ return await asyncio.shield(task)
25
+ except asyncio.CancelledError:
26
+ cancellation = current_cancellation()
27
+ if cancellation is not None:
28
+ cancellation.cancel()
29
+ # Every wait must be shielded: repeated cancellation must not release
30
+ # lifecycle leases while the Python thread still uses plugin resources.
31
+ while not task.done():
32
+ try:
33
+ await asyncio.shield(task)
34
+ except asyncio.CancelledError:
35
+ continue
36
+ except BaseException:
37
+ break
38
+ if not task.cancelled():
39
+ task.exception() # Retrieve a worker failure without replacing cancellation.
40
+ raise
41
+
42
+
43
+ async def invoke_model(function: Callable, *args: Any, **kwargs: Any) -> Any:
44
+ """Keep model threads independent of the executor used by their callbacks.
45
+
46
+ Each active call owns one thread. Streaming callbacks synchronously wait for
47
+ delivery, so at most one text chunk per call is in flight. Draining before
48
+ shutdown preserves leases and propagates the caller's context variables.
49
+ """
50
+ context = contextvars.copy_context()
51
+ with ThreadPoolExecutor(max_workers=1, thread_name_prefix="penhin-model") as executor:
52
+ future = executor.submit(context.run, function, *args, **kwargs)
53
+ return await _drain(asyncio.wrap_future(future))
penhin/_atomic.py ADDED
@@ -0,0 +1,41 @@
1
+ """Private atomic file publication shared by session and credential stores."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import os
6
+ import threading
7
+ from pathlib import Path
8
+
9
+
10
+ def atomic_write_text(
11
+ path: Path,
12
+ content: str,
13
+ mode: int | None = None,
14
+ *,
15
+ fsync_directory: bool = False,
16
+ ) -> None:
17
+ path.parent.mkdir(parents=True, exist_ok=True)
18
+ temp_path = path.with_name(f".{path.name}.{os.getpid()}.{threading.get_ident()}.tmp")
19
+ try:
20
+ descriptor = os.open(
21
+ temp_path, os.O_WRONLY | os.O_CREAT | os.O_EXCL, mode if mode is not None else 0o666
22
+ )
23
+ with os.fdopen(descriptor, "w", encoding="utf-8") as stream:
24
+ stream.write(content)
25
+ stream.flush()
26
+ os.fsync(stream.fileno())
27
+ temp_path.replace(path)
28
+ if mode is not None:
29
+ os.chmod(path, mode)
30
+ if fsync_directory:
31
+ try:
32
+ directory_fd = os.open(path.parent, os.O_RDONLY)
33
+ try:
34
+ os.fsync(directory_fd)
35
+ finally:
36
+ os.close(directory_fd)
37
+ except OSError:
38
+ pass
39
+ except Exception:
40
+ temp_path.unlink(missing_ok=True)
41
+ raise
penhin/_checkpoints.py ADDED
@@ -0,0 +1,92 @@
1
+ """Compact checkpoints relative to a full anchor; reads never traverse delta chains."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import json
6
+ from collections.abc import Callable
7
+ from typing import Any, Literal
8
+
9
+ from pydantic import BaseModel, ConfigDict, Field, JsonValue
10
+
11
+ _STATE_SCHEMA = "penhin.session/v1"
12
+ _UPDATES = {"metadata", "pending", "waiting", "needs_response"}
13
+
14
+
15
+ class _Delta(BaseModel):
16
+ model_config = ConfigDict(extra="forbid", strict=True)
17
+
18
+ schema_version: Literal["penhin.checkpoint/v1"]
19
+ id: str
20
+ revision: int = Field(ge=1)
21
+ base_revision: int = Field(ge=0)
22
+ message_prefix: int = Field(ge=0)
23
+ messages: list[dict[str, JsonValue]]
24
+ updates: dict[str, JsonValue]
25
+
26
+
27
+ def _anchor(record: dict[str, Any], read: Callable[[int], dict[str, Any]]) -> dict[str, Any]:
28
+ if record.get("schema_version") == _STATE_SCHEMA:
29
+ return record
30
+ delta = _Delta.model_validate(record)
31
+ if delta.base_revision >= delta.revision or delta.updates.keys() - _UPDATES:
32
+ raise ValueError("invalid checkpoint delta")
33
+ base = read(delta.base_revision)
34
+ if (
35
+ base.get("schema_version") != _STATE_SCHEMA
36
+ or base.get("id") != delta.id
37
+ or base.get("revision") != delta.base_revision
38
+ ):
39
+ raise ValueError("checkpoint anchor identity mismatch or non-full anchor")
40
+ if delta.message_prefix > len(base["messages"]):
41
+ raise ValueError("checkpoint prefix exceeds anchor history")
42
+ return base
43
+
44
+
45
+ def decode(record: dict[str, Any], read: Callable[[int], dict[str, Any]]) -> dict[str, Any]:
46
+ base = _anchor(record, read)
47
+ if base is record:
48
+ return record
49
+ return {
50
+ **base,
51
+ **record["updates"],
52
+ "revision": record["revision"],
53
+ "messages": base["messages"][: record["message_prefix"]] + record["messages"],
54
+ }
55
+
56
+
57
+ def encode(
58
+ state: dict[str, Any],
59
+ previous: dict[str, Any] | None,
60
+ read: Callable[[int], dict[str, Any]],
61
+ interval: int,
62
+ ) -> str:
63
+ def dump(value):
64
+ return json.dumps(value, ensure_ascii=False, allow_nan=False, separators=(",", ":"))
65
+
66
+ full = dump(state)
67
+ if previous is not None and (
68
+ previous.get("id") != state["id"] or previous.get("revision") != state["revision"] - 1
69
+ ):
70
+ raise ValueError("checkpoint identity mismatch")
71
+ if previous is None or interval == 1:
72
+ return full
73
+ base = _anchor(previous, read)
74
+ if state["revision"] - base["revision"] >= interval:
75
+ return full
76
+ prefix = 0
77
+ for old, new in zip(base["messages"], state["messages"]):
78
+ if old != new:
79
+ break
80
+ prefix += 1
81
+ delta = dump(
82
+ {
83
+ "schema_version": "penhin.checkpoint/v1",
84
+ "id": state["id"],
85
+ "revision": state["revision"],
86
+ "base_revision": base["revision"],
87
+ "message_prefix": prefix,
88
+ "messages": state["messages"][prefix:],
89
+ "updates": {key: state[key] for key in sorted(_UPDATES) if state[key] != base.get(key)},
90
+ }
91
+ )
92
+ return delta if len(delta) < len(full) else full