functualize-ai 0.1.0__tar.gz

functualize_ai-0.1.0/.gitignore

@@ -0,0 +1,101 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg-info/
+*.egg
+dist/
+build/
+*.whl
+
+# Agents
+.spec/archive/
+.spec/features/
+.spec/scrutiny-reports/
+.spec/.agentic-coding
+.spec/STATE.md
+.spec/PROJECT.md
+.spec/REQUIREMENTS.md
+.spec/ROADMAP.md
+.opencode/
+
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# Testing
+.coverage
+.pytest_cache/
+htmlcov/
+.hypothesis/
+snapshot_report.html
+_*_result*.txt
+_debug.txt
+_tui_debug.txt
+_tui_eval_debug.txt
+
+# IDE
+.idea/
+*.swp
+*.swo
+*~
+*.code-workspace
+
+# Coding-agent tooling state (guards — these dirs are not part of the repo)
+.kiro/
+.moai/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Environment / secrets
+.env
+.env.*
+!.env.example
+
+# Agent scratch space (test output, temp scripts)
+tmp/
+
+# Local-only files (not for the repo)
+*.local.md
+*.local.*
+
+# Personal notes
+HUMAN_NOTE.md
+
+# Distribution
+dist/
+
+# Documentation site build output
+site/
+
+# uv
+.python-version
+.functualize/cache.json
+.functualize_cache.json
+.todos/
+.sidecar/
+.sidecar-agent
+.sidecar-task
+.sidecar-pr
+.sidecar-start.sh
+.sidecar-base
+.td-root
+.functualize/
+.import_linter_cache/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+
+# OmO / OpenCode agent run-continuation scratch state
+.omo/
+.mcp.json
+.agentsroom/handoff-transcript-*.txt
+.agentsroom/handoff-summary-*.md
+
+# Internal pre-release audit reports (contain session IDs / local infra notes)
+.release/

functualize_ai-0.1.0/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: functualize-ai
+Version: 0.1.0
+Summary: AI Domain SDK for functualize — LLM interaction capabilities
+Author-email: Mohammad Hakim Adiprasetya <viltohmyst@gmail.com>
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: functualize-state
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
+Requires-Dist: pytest>=7.4.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# functualize-ai
+
+> **Status: Published** — Independently installable from PyPI.
+
+AI Domain SDK for functualize — provider-agnostic LLM interaction capabilities.
+
+Provides the `AI` capability class with structured output, tool calling, streaming,
+and extraction methods backed by a pluggable `AIProvider` protocol. Includes
+deny-by-default tool visibility via `ToolScope`, cumulative budget enforcement,
+lifecycle event emission, and a deterministic `MockAI` testing double for unit
+testing without network calls or API keys.
+
+## Installation
+
+```bash
+pip install functualize-ai
+```
+
+## Quick Start
+
+```python
+from functualize_ai import AI, ToolScope, AILimits
+from functualize_ai.testing import MockAI
+
+# Use MockAI for deterministic testing (no API key needed)
+ai = MockAI(responses={"*summarize*": "A brief summary of the document."})
+
+# Simple text completion
+result = ai.complete("Please summarize this text")
+print(result)  # "A brief summary of the document."
+
+# Run with tool scope and budget limits
+scope = ToolScope.only(["search", "calculate"])
+limits = AILimits(budget_usd=1.00, max_tool_calls=5)
+ai_result = ai.run("Find the answer", tools=scope, limits=limits)
+print(ai_result.output)
+```
+
+## Features
+
+- **Provider-agnostic AI class** with `complete()`, `run()`, `stream()`, and `extract()` methods for text, structured output, tool calling, and streaming
+- **ToolScope builder** implementing deny-by-default tool visibility — restrict tools by name, tag, group, or plain callables with composable `+` operator
+- **Budget enforcement** tracking cumulative USD spend across calls with automatic `BudgetExceeded` errors when limits are reached
+- **Structured output validation** with automatic retry (up to 3 attempts) against Pydantic models or dataclasses
+- **MockAI testing double** using glob-pattern matching for deterministic, network-free testing with full call recording
+- **Lifecycle event emission** (`AI_CALL_STARTED`, `AI_CALL_COMPLETED`, `AI_CALL_FAILED`, `AI_BUDGET_EXCEEDED`, `AI_TOOL_CALLED`) for observability and audit logging
+- **AIProvider protocol** enabling custom backend implementations (PydanticAI, LiteLLM, or any LLM SDK)
+
+## API Reference
+
+Public classes and functions exported by this plugin:
+
+### Capability
+
+- `AI` — Provider-agnostic LLM interaction class with `complete()`, `run()`, `stream()`, `extract()` methods
+
+### Protocol
+
+- `AIProvider` — Runtime-checkable protocol that AI backend implementations must satisfy
+
+### Tool Scope
+
+- `ToolScope` — Deny-by-default tool visibility builder with `only()`, `tagged()`, `group()`, `functions()` factory methods
+
+### Types
+
+- `AIResult` — Result of an AI run containing `output`, `tool_calls`, `usage`, and `duration_ms`
+- `TokenUsage` — Token usage statistics (`prompt_tokens`, `completion_tokens`, `total_tokens`, `cost_usd`)
+- `ToolDef` — Provider-agnostic tool definition with name, description, and parameters schema
+- `AILimits` — Budget and constraint caps (`max_tool_calls`, `max_tokens`, `budget_usd`, `timeout_seconds`)
+- `ToolCallRecord` — Record of a single tool call with name, args, result, and duration
+
+### Configuration
+
+- `AIConfig` — Pydantic model for AI domain configuration (provider, model, max_tokens, budget_usd, timeout_seconds)
+
+### Errors
+
+- `AINotAvailable` — Raised when no AI provider is configured
+- `BudgetExceeded` — Raised when cumulative spend reaches the budget limit
+- `ToolNotPermitted` — Raised when a tool call is not permitted by the current ToolScope
+
+### Events
+
+- `AI_CALL_STARTED` — Emitted when an AI call begins
+- `AI_CALL_COMPLETED` — Emitted when an AI call completes successfully
+- `AI_CALL_FAILED` — Emitted when an AI call fails
+- `AI_BUDGET_EXCEEDED` — Emitted when budget is exceeded
+- `AI_TOOL_CALLED` — Emitted when a tool is called during a run
+
+### Testing
+
+- `MockAI` — Pattern-matching AI mock for deterministic testing
+- `MockAICall` — Record of a single MockAI call (prompt, response_model, response)
+
+### Provider Discovery
+
+- `discover_ai_providers()` — Discover available AI provider entry points
+- `select_ai_provider()` — Select a provider by name from discovered providers
+- `resolve_ai_provider()` — Resolve and instantiate the configured AI provider
+
+### State Fallback
+
+- `EphemeralStateBackend` — In-memory state backend for when no persistent state is available
+- `StrictStateBackendWrapper` — Wrapper enforcing strict key access on a state backend
+- `resolve_ai_state_backend()` — Resolve the AI state backend from context
+
+## Development
+
+Run plugin tests:
+
+```bash
+uv run pytest plugins/functualize-ai/tests/ -v
+```

functualize_ai-0.1.0/README.md

@@ -0,0 +1,114 @@
+# functualize-ai
+
+> **Status: Published** — Independently installable from PyPI.
+
+AI Domain SDK for functualize — provider-agnostic LLM interaction capabilities.
+
+Provides the `AI` capability class with structured output, tool calling, streaming,
+and extraction methods backed by a pluggable `AIProvider` protocol. Includes
+deny-by-default tool visibility via `ToolScope`, cumulative budget enforcement,
+lifecycle event emission, and a deterministic `MockAI` testing double for unit
+testing without network calls or API keys.
+
+## Installation
+
+```bash
+pip install functualize-ai
+```
+
+## Quick Start
+
+```python
+from functualize_ai import AI, ToolScope, AILimits
+from functualize_ai.testing import MockAI
+
+# Use MockAI for deterministic testing (no API key needed)
+ai = MockAI(responses={"*summarize*": "A brief summary of the document."})
+
+# Simple text completion
+result = ai.complete("Please summarize this text")
+print(result)  # "A brief summary of the document."
+
+# Run with tool scope and budget limits
+scope = ToolScope.only(["search", "calculate"])
+limits = AILimits(budget_usd=1.00, max_tool_calls=5)
+ai_result = ai.run("Find the answer", tools=scope, limits=limits)
+print(ai_result.output)
+```
+
+## Features
+
+- **Provider-agnostic AI class** with `complete()`, `run()`, `stream()`, and `extract()` methods for text, structured output, tool calling, and streaming
+- **ToolScope builder** implementing deny-by-default tool visibility — restrict tools by name, tag, group, or plain callables with composable `+` operator
+- **Budget enforcement** tracking cumulative USD spend across calls with automatic `BudgetExceeded` errors when limits are reached
+- **Structured output validation** with automatic retry (up to 3 attempts) against Pydantic models or dataclasses
+- **MockAI testing double** using glob-pattern matching for deterministic, network-free testing with full call recording
+- **Lifecycle event emission** (`AI_CALL_STARTED`, `AI_CALL_COMPLETED`, `AI_CALL_FAILED`, `AI_BUDGET_EXCEEDED`, `AI_TOOL_CALLED`) for observability and audit logging
+- **AIProvider protocol** enabling custom backend implementations (PydanticAI, LiteLLM, or any LLM SDK)
+
+## API Reference
+
+Public classes and functions exported by this plugin:
+
+### Capability
+
+- `AI` — Provider-agnostic LLM interaction class with `complete()`, `run()`, `stream()`, `extract()` methods
+
+### Protocol
+
+- `AIProvider` — Runtime-checkable protocol that AI backend implementations must satisfy
+
+### Tool Scope
+
+- `ToolScope` — Deny-by-default tool visibility builder with `only()`, `tagged()`, `group()`, `functions()` factory methods
+
+### Types
+
+- `AIResult` — Result of an AI run containing `output`, `tool_calls`, `usage`, and `duration_ms`
+- `TokenUsage` — Token usage statistics (`prompt_tokens`, `completion_tokens`, `total_tokens`, `cost_usd`)
+- `ToolDef` — Provider-agnostic tool definition with name, description, and parameters schema
+- `AILimits` — Budget and constraint caps (`max_tool_calls`, `max_tokens`, `budget_usd`, `timeout_seconds`)
+- `ToolCallRecord` — Record of a single tool call with name, args, result, and duration
+
+### Configuration
+
+- `AIConfig` — Pydantic model for AI domain configuration (provider, model, max_tokens, budget_usd, timeout_seconds)
+
+### Errors
+
+- `AINotAvailable` — Raised when no AI provider is configured
+- `BudgetExceeded` — Raised when cumulative spend reaches the budget limit
+- `ToolNotPermitted` — Raised when a tool call is not permitted by the current ToolScope
+
+### Events
+
+- `AI_CALL_STARTED` — Emitted when an AI call begins
+- `AI_CALL_COMPLETED` — Emitted when an AI call completes successfully
+- `AI_CALL_FAILED` — Emitted when an AI call fails
+- `AI_BUDGET_EXCEEDED` — Emitted when budget is exceeded
+- `AI_TOOL_CALLED` — Emitted when a tool is called during a run
+
+### Testing
+
+- `MockAI` — Pattern-matching AI mock for deterministic testing
+- `MockAICall` — Record of a single MockAI call (prompt, response_model, response)
+
+### Provider Discovery
+
+- `discover_ai_providers()` — Discover available AI provider entry points
+- `select_ai_provider()` — Select a provider by name from discovered providers
+- `resolve_ai_provider()` — Resolve and instantiate the configured AI provider
+
+### State Fallback
+
+- `EphemeralStateBackend` — In-memory state backend for when no persistent state is available
+- `StrictStateBackendWrapper` — Wrapper enforcing strict key access on a state backend
+- `resolve_ai_state_backend()` — Resolve the AI state backend from context
+
+## Development
+
+Run plugin tests:
+
+```bash
+uv run pytest plugins/functualize-ai/tests/ -v
+```

functualize_ai-0.1.0/examples/README.md

@@ -0,0 +1,13 @@
+# functualize-ai Examples
+
+The AI domain SDK: provider-agnostic `AI` capability with structured output, `ToolScope`, `AILimits`, and the `MockAI` testing double.
+
+| Directory | Demonstrates |
+|-----------|--------------|
+| [`summarize/`](summarize/) | A job calling `ai.complete()` with a Pydantic `response_model`, runnable without API keys via `MockAI` |
+
+```bash
+uv run pytest plugins/functualize-ai/examples/ -v
+```
+
+For a real LLM backend, see [`functualize-ai-pydantic/examples/`](../../functualize-ai-pydantic/examples/).

functualize_ai-0.1.0/examples/summarize/summarize.py

@@ -0,0 +1,48 @@
+"""Provider-agnostic AI job: structured summary of a text.
+
+Run with:
+    func summarize.py run --text "Functualize is a CLI framework..."
+
+Uses MockAI so it works without API keys; with a provider plugin
+installed (e.g. functualize-ai-pydantic) declare `ai: AI` as a job
+parameter instead and the framework injects the real provider.
+"""
+
+from functualize_ai.testing import MockAI
+from pydantic import BaseModel, Field
+
+from functualize.job import RunContext
+
+
+class SummarizeConfig(BaseModel):
+    """Configuration for the summarize job."""
+
+    text: str = Field(description="Text to summarize")
+    max_points: int = Field(default=3, ge=1, le=10, description="Bullet points")
+
+
+class Summary(BaseModel):
+    """Structured output the AI must produce."""
+
+    title: str
+    bullet_points: list[str]
+
+
+def run(config: SummarizeConfig, rc: RunContext) -> Summary:
+    """Summarize text into structured bullet points."""
+    ai = MockAI(
+        responses={
+            "*Summarize*": Summary(
+                title="Summary",
+                bullet_points=[f"Point about: {config.text[:40]}"] * config.max_points,
+            ),
+        }
+    )
+
+    summary = ai.complete(
+        f"Summarize in {config.max_points} bullet points: {config.text}",
+        response_model=Summary,
+    )
+    for point in summary.bullet_points:
+        rc.log(f"• {point}")
+    return summary

functualize_ai-0.1.0/examples/summarize/test_summarize.py

@@ -0,0 +1,16 @@
+"""Tests for the summarize example."""
+
+import sys
+from pathlib import Path
+from unittest.mock import MagicMock
+
+sys.path.insert(0, str(Path(__file__).parent))
+
+from summarize import SummarizeConfig, Summary, run
+
+
+def test_returns_structured_summary():
+    config = SummarizeConfig(text="Functualize is a CLI framework", max_points=2)
+    summary = run(config, MagicMock())
+    assert isinstance(summary, Summary)
+    assert len(summary.bullet_points) == 2

functualize_ai-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[project]
+name = "functualize-ai"
+version = "0.1.0"
+description = "AI Domain SDK for functualize — LLM interaction capabilities"
+readme = "README.md"
+license = "MIT"
+authors = [
+    { name = "Mohammad Hakim Adiprasetya", email = "viltohmyst@gmail.com" }
+]
+requires-python = ">=3.11"
+dependencies = [
+    "pydantic>=2.0.0",
+    "functualize-state",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+
+[project.entry-points."functualize.domains"]
+ai = "functualize_ai._metadata:domain_metadata"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.4.0",
+    "pytest-cov>=4.1.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/functualize_ai"]

functualize_ai-0.1.0/src/functualize_ai/__init__.py

@@ -0,0 +1,150 @@
+"""functualize-ai — AI Domain SDK.
+
+Provides the AI capability class, AIProvider protocol, ToolScope builder,
+shared types, configuration, errors, event constants, gate strategy,
+and testing doubles for LLM interaction capabilities.
+
+Uses lazy imports via __getattr__ to avoid loading heavy dependencies
+(pydantic, importlib.metadata) until first attribute access. This keeps
+domain metadata discovery fast (~5ms instead of ~360ms).
+"""
+
+from __future__ import annotations
+
+# Only domain_metadata is loaded eagerly (needed for entry point discovery)
+from functualize_ai._metadata import domain_metadata
+
+__all__ = [
+    # Capability Class
+    "AI",
+    # Protocol
+    "AIProvider",
+    # ToolScope
+    "ToolScope",
+    # Types
+    "AIResult",
+    "TokenUsage",
+    "ToolDef",
+    "AILimits",
+    "ToolCallRecord",
+    # Config
+    "AIConfig",
+    # Errors
+    "AINotAvailableError",
+    "BudgetExceededError",
+    "ToolNotPermittedError",
+    # Event Constants
+    "AI_CALL_STARTED",
+    "AI_CALL_COMPLETED",
+    "AI_CALL_FAILED",
+    "AI_BUDGET_EXCEEDED",
+    "AI_TOOL_CALLED",
+    # Gate Strategy
+    "AI_INBOUND_STRATEGY_NAME",
+    "AI_INBOUND_PRESET_NAME",
+    "AI_INBOUND_PRESET_STRATEGIES",
+    "AI_PRESET_NAME",
+    "AI_PRESET_STRATEGIES",
+    "AIInboundGateResolver",
+    "register_ai_inbound_gate_strategy",
+    # State Fallback
+    "EphemeralStateBackend",
+    "StrictStateBackendWrapper",
+    "resolve_ai_state_backend",
+    # Provider Discovery
+    "discover_ai_providers",
+    "select_ai_provider",
+    "resolve_ai_provider",
+    # Metadata
+    "domain_metadata",
+]
+
+# Lazy import mapping: attribute name → (module, name)
+_LAZY_IMPORTS: dict[str, tuple[str, str]] = {
+    # _ai
+    "AI": ("functualize_ai._ai", "AI"),
+    # _config
+    "AIConfig": ("functualize_ai._config", "AIConfig"),
+    # _errors
+    "AINotAvailableError": ("functualize_ai._errors", "AINotAvailableError"),
+    "BudgetExceededError": ("functualize_ai._errors", "BudgetExceededError"),
+    "ToolNotPermittedError": ("functualize_ai._errors", "ToolNotPermittedError"),
+    # _events
+    "AI_BUDGET_EXCEEDED": ("functualize_ai._events", "AI_BUDGET_EXCEEDED"),
+    "AI_CALL_COMPLETED": ("functualize_ai._events", "AI_CALL_COMPLETED"),
+    "AI_CALL_FAILED": ("functualize_ai._events", "AI_CALL_FAILED"),
+    "AI_CALL_STARTED": ("functualize_ai._events", "AI_CALL_STARTED"),
+    "AI_TOOL_CALLED": ("functualize_ai._events", "AI_TOOL_CALLED"),
+    # _gate_strategy
+    "AI_INBOUND_PRESET_NAME": (
+        "functualize_ai._gate_strategy",
+        "AI_INBOUND_PRESET_NAME",
+    ),
+    "AI_INBOUND_PRESET_STRATEGIES": (
+        "functualize_ai._gate_strategy",
+        "AI_INBOUND_PRESET_STRATEGIES",
+    ),
+    "AI_INBOUND_STRATEGY_NAME": (
+        "functualize_ai._gate_strategy",
+        "AI_INBOUND_STRATEGY_NAME",
+    ),
+    "AI_PRESET_NAME": ("functualize_ai._gate_strategy", "AI_PRESET_NAME"),
+    "AI_PRESET_STRATEGIES": ("functualize_ai._gate_strategy", "AI_PRESET_STRATEGIES"),
+    "AIInboundGateResolver": (
+        "functualize_ai._gate_strategy",
+        "AIInboundGateResolver",
+    ),
+    "register_ai_inbound_gate_strategy": (
+        "functualize_ai._gate_strategy",
+        "register_ai_inbound_gate_strategy",
+    ),
+    # _protocols
+    "AIProvider": ("functualize_ai._protocols", "AIProvider"),
+    # _provider_discovery
+    "discover_ai_providers": (
+        "functualize_ai._provider_discovery",
+        "discover_ai_providers",
+    ),
+    "resolve_ai_provider": (
+        "functualize_ai._provider_discovery",
+        "resolve_ai_provider",
+    ),
+    "select_ai_provider": (
+        "functualize_ai._provider_discovery",
+        "select_ai_provider",
+    ),
+    # _state_fallback
+    "EphemeralStateBackend": (
+        "functualize_ai._state_fallback",
+        "EphemeralStateBackend",
+    ),
+    "StrictStateBackendWrapper": (
+        "functualize_ai._state_fallback",
+        "StrictStateBackendWrapper",
+    ),
+    "resolve_ai_state_backend": (
+        "functualize_ai._state_fallback",
+        "resolve_ai_state_backend",
+    ),
+    # _tool_scope
+    "ToolScope": ("functualize_ai._tool_scope", "ToolScope"),
+    # _types
+    "AILimits": ("functualize_ai._types", "AILimits"),
+    "AIResult": ("functualize_ai._types", "AIResult"),
+    "TokenUsage": ("functualize_ai._types", "TokenUsage"),
+    "ToolCallRecord": ("functualize_ai._types", "ToolCallRecord"),
+    "ToolDef": ("functualize_ai._types", "ToolDef"),
+}
+
+
+def __getattr__(name: str) -> object:
+    if name in _LAZY_IMPORTS:
+        module_path, attr_name = _LAZY_IMPORTS[name]
+        import importlib
+
+        module = importlib.import_module(module_path)
+        value = getattr(module, attr_name)
+        # Cache in module globals to avoid repeated __getattr__ calls
+        globals()[name] = value
+        return value
+    raise AttributeError(f"module 'functualize_ai' has no attribute {name!r}")