zurvan 0.1.0__tar.gz

zurvan-0.1.0/.gitignore

@@ -0,0 +1,35 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Build artefacts
+build/
+dist/
+*.egg-info/
+*.egg
+
+# Editor / OS
+.DS_Store
+.vscode/
+.idea/
+*.swp
+
+# Tests / coverage
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# Logs
+.logs/
+.venv
+.vscode
+.env

zurvan-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ali Afsahnoudeh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

zurvan-0.1.0/PKG-INFO

@@ -0,0 +1,140 @@
+Metadata-Version: 2.4
+Name: zurvan
+Version: 0.1.0
+Summary: A small, composable Python framework for building goal-directed LLM agents (GAME loop + Capability hooks).
+Project-URL: Homepage, https://github.com/aliafsahnoudeh/zurvan
+Project-URL: Repository, https://github.com/aliafsahnoudeh/zurvan
+Project-URL: Issues, https://github.com/aliafsahnoudeh/zurvan/issues
+Author-email: Ali Afsah-Noudeh <aliafsah1988@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,capability,framework,game-loop,llm
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: litellm>=1.50
+Requires-Dist: pydantic>=2
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# zurvan
+
+A small, composable Python framework for building goal-directed LLM agents.
+
+## What it is
+
+`zurvan` runs a **GAME loop** — Goals, Actions, Memory, Environment — over
+an LLM. Behaviour like plan-first, time-aware, prompt-injection-resistant,
+or progress-tracking is composed by passing a list of `Capability`
+instances rather than by subclassing `Agent`. With no capabilities it
+reduces to a plain Goals → Actions → Memory cycle.
+
+LLM providers are abstracted behind `AgentLanguage`. Built-in subclasses
+(via [LiteLLM](https://github.com/BerriAI/litellm)) cover OpenAI, Gemini,
+and Groq.
+
+## Install
+
+```bash
+pip install zurvan
+```
+
+Requires Python 3.11+.
+
+## Quick start
+
+```python
+from zurvan import (
+    Action,
+    ActionRegistry,
+    Agent,
+    AgentFunctionCallingActionLanguageOpenAI,
+    Environment,
+    Goal,
+)
+
+def terminate(message: str) -> str:
+    return message
+
+actions = ActionRegistry()
+actions.register(Action(
+    name="terminate",
+    function=terminate,
+    description="End the conversation with a final message.",
+    parameters={
+        "type": "object",
+        "properties": {"message": {"type": "string"}},
+        "required": ["message"],
+    },
+    terminal=True,
+))
+
+agent = Agent(
+    goals=[Goal(priority=1, name="Greet", description="Greet the user warmly.")],
+    agent_language=AgentFunctionCallingActionLanguageOpenAI(model="openai/gpt-4o-mini"),
+    action_registry=actions,
+    environment=Environment(),
+)
+
+memory = agent.run("Say hi.")
+```
+
+## Pydantic-validated tool inputs
+
+`Action` accepts either a JSON-Schema dict (`parameters=`) or a Pydantic
+model (`input_model=`). With a model, the schema sent to the LLM is
+derived from the model and the model's args are **validated before the
+function runs** — a `ValidationError` is caught by `Environment` and
+fed back to the LLM as a failed-tool result, so the model gets a chance
+to retry with corrected args.
+
+```python
+from typing import Literal
+from pydantic import BaseModel
+from zurvan import Action
+
+class GetWeatherArgs(BaseModel):
+    city: str
+    unit: Literal["c", "f"] = "c"
+
+def get_weather(city: str, unit: str = "c") -> str:
+    return f"It's nice in {city} ({unit}°)"
+
+action = Action(
+    name="get_weather",
+    function=get_weather,
+    description="Look up the weather for a city.",
+    input_model=GetWeatherArgs,
+)
+```
+
+`parameters=` and `input_model=` are mutually exclusive — pass exactly one.
+
+## Capabilities
+
+Capabilities hook into every loop phase (`init`, `start_agent_loop`,
+`process_prompt`, `process_response`, `process_action`, `process_result`,
+`process_new_memories`, `end_agent_loop`, `should_terminate`,
+`terminate`). Compose them — don't subclass `Agent`.
+
+```python
+from zurvan import Agent, CanaryCapability, TimeAwareCapability
+
+agent = Agent(
+    ...,
+    capabilities=[CanaryCapability(), TimeAwareCapability()],
+)
+```
+
+## License
+
+MIT.

zurvan-0.1.0/README.md

@@ -0,0 +1,112 @@
+# zurvan
+
+A small, composable Python framework for building goal-directed LLM agents.
+
+## What it is
+
+`zurvan` runs a **GAME loop** — Goals, Actions, Memory, Environment — over
+an LLM. Behaviour like plan-first, time-aware, prompt-injection-resistant,
+or progress-tracking is composed by passing a list of `Capability`
+instances rather than by subclassing `Agent`. With no capabilities it
+reduces to a plain Goals → Actions → Memory cycle.
+
+LLM providers are abstracted behind `AgentLanguage`. Built-in subclasses
+(via [LiteLLM](https://github.com/BerriAI/litellm)) cover OpenAI, Gemini,
+and Groq.
+
+## Install
+
+```bash
+pip install zurvan
+```
+
+Requires Python 3.11+.
+
+## Quick start
+
+```python
+from zurvan import (
+    Action,
+    ActionRegistry,
+    Agent,
+    AgentFunctionCallingActionLanguageOpenAI,
+    Environment,
+    Goal,
+)
+
+def terminate(message: str) -> str:
+    return message
+
+actions = ActionRegistry()
+actions.register(Action(
+    name="terminate",
+    function=terminate,
+    description="End the conversation with a final message.",
+    parameters={
+        "type": "object",
+        "properties": {"message": {"type": "string"}},
+        "required": ["message"],
+    },
+    terminal=True,
+))
+
+agent = Agent(
+    goals=[Goal(priority=1, name="Greet", description="Greet the user warmly.")],
+    agent_language=AgentFunctionCallingActionLanguageOpenAI(model="openai/gpt-4o-mini"),
+    action_registry=actions,
+    environment=Environment(),
+)
+
+memory = agent.run("Say hi.")
+```
+
+## Pydantic-validated tool inputs
+
+`Action` accepts either a JSON-Schema dict (`parameters=`) or a Pydantic
+model (`input_model=`). With a model, the schema sent to the LLM is
+derived from the model and the model's args are **validated before the
+function runs** — a `ValidationError` is caught by `Environment` and
+fed back to the LLM as a failed-tool result, so the model gets a chance
+to retry with corrected args.
+
+```python
+from typing import Literal
+from pydantic import BaseModel
+from zurvan import Action
+
+class GetWeatherArgs(BaseModel):
+    city: str
+    unit: Literal["c", "f"] = "c"
+
+def get_weather(city: str, unit: str = "c") -> str:
+    return f"It's nice in {city} ({unit}°)"
+
+action = Action(
+    name="get_weather",
+    function=get_weather,
+    description="Look up the weather for a city.",
+    input_model=GetWeatherArgs,
+)
+```
+
+`parameters=` and `input_model=` are mutually exclusive — pass exactly one.
+
+## Capabilities
+
+Capabilities hook into every loop phase (`init`, `start_agent_loop`,
+`process_prompt`, `process_response`, `process_action`, `process_result`,
+`process_new_memories`, `end_agent_loop`, `should_terminate`,
+`terminate`). Compose them — don't subclass `Agent`.
+
+```python
+from zurvan import Agent, CanaryCapability, TimeAwareCapability
+
+agent = Agent(
+    ...,
+    capabilities=[CanaryCapability(), TimeAwareCapability()],
+)
+```
+
+## License
+
+MIT.

zurvan-0.1.0/examples/capabilities/README.md

@@ -0,0 +1,21 @@
+# Example capabilities (illustrative — not tested, not shipped)
+
+The capabilities in this directory are **sketches**, not part of the
+installed package. They reference helpers (`prompt_llm`,
+`action_context.get_action_registry()`) that don't exist in zurvan and
+will not run as-is.
+
+They live here as design references for users writing their own
+capabilities — patterns for "plan first" and "track progress after
+each iteration" — not as drop-in code.
+
+If you want a working version, you'll need to:
+
+1. Replace `prompt_llm(...)` calls with `agent.agent_language.generate_response(Prompt(messages=[...]))`.
+2. Get the `ActionRegistry` from the agent (`agent.actions`) rather
+   than via `action_context.get_action_registry()` (no such method).
+3. Decide where the plan/progress prompt should run — `init` for
+   plan-first, `end_agent_loop` for progress-tracking — and wire it
+   end-to-end.
+
+Tested, working capabilities live in [src/zurvan/capabilities/](../../src/zurvan/capabilities/).

zurvan-0.1.0/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "zurvan"
+version = "0.1.0"
+description = "A small, composable Python framework for building goal-directed LLM agents (GAME loop + Capability hooks)."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+authors = [{ name = "Ali Afsah-Noudeh", email = "aliafsah1988@gmail.com" }]
+keywords = ["agent", "llm", "framework", "game-loop", "capability"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Operating System :: OS Independent",
+]
+dependencies = ["litellm>=1.50", "pydantic>=2"]
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "pytest-cov>=5", "ruff>=0.6"]
+
+[project.urls]
+Homepage = "https://github.com/aliafsahnoudeh/zurvan"
+Repository = "https://github.com/aliafsahnoudeh/zurvan"
+Issues = "https://github.com/aliafsahnoudeh/zurvan/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/zurvan"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/zurvan", "README.md", "LICENSE", "pyproject.toml"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra --strict-markers"
+filterwarnings = [
+    "ignore::DeprecationWarning:pydantic.*",
+    "ignore::DeprecationWarning:litellm.*",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"

zurvan-0.1.0/src/zurvan/__init__.py

@@ -0,0 +1,75 @@
+"""zurvan — composable Python framework for goal-directed LLM agents.
+
+The package implements the **GAME loop** (Goals, Actions, Memory,
+Environment) and a :class:`Capability` hook system. Behaviour is
+composed by passing a list of capabilities to the :class:`Agent`,
+not by subclassing.
+
+LLM providers are abstracted behind :class:`AgentLanguage`. The
+function-calling subclasses (Gemini, Groq, OpenAI) talk to providers
+via LiteLLM.
+"""
+
+from zurvan.action import Action
+from zurvan.action_context import ActionContext
+from zurvan.action_registry import ActionRegistry
+from zurvan.agent import Agent
+from zurvan.agent_function_calling_action_language import (
+    AgentFunctionCallingActionLanguage,
+)
+from zurvan.agent_function_calling_action_language_gemini import (
+    AgentFunctionCallingActionLanguageGemini,
+)
+from zurvan.agent_function_calling_action_language_groq import (
+    AgentFunctionCallingActionLanguageGroq,
+)
+from zurvan.agent_function_calling_action_language_openai import (
+    AgentFunctionCallingActionLanguageOpenAI,
+)
+from zurvan.agent_language import AgentLanguage
+from zurvan.capabilities.canary_capability import (
+    CanaryCapability,
+    PromptInjectionDetected,
+)
+from zurvan.capabilities.time_aware_capability import TimeAwareCapability
+from zurvan.capability import Capability
+from zurvan.decorators import register_tool
+from zurvan.environment import Environment
+from zurvan.goal import Goal
+from zurvan.logger.logger import LogLevel, Logger
+from zurvan.memory import Memory
+from zurvan.prompt import Prompt
+from zurvan.token_tracker import TokenTracker
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    # Core GAME primitives
+    "Action",
+    "ActionContext",
+    "ActionRegistry",
+    "Agent",
+    "Capability",
+    "Environment",
+    "Goal",
+    "Memory",
+    "Prompt",
+    # Logging
+    "LogLevel",
+    "Logger",
+    # Tool decorator
+    "register_tool",
+    # Token tracking
+    "TokenTracker",
+    # Agent languages
+    "AgentLanguage",
+    "AgentFunctionCallingActionLanguage",
+    "AgentFunctionCallingActionLanguageGemini",
+    "AgentFunctionCallingActionLanguageGroq",
+    "AgentFunctionCallingActionLanguageOpenAI",
+    # Capabilities
+    "CanaryCapability",
+    "PromptInjectionDetected",
+    "TimeAwareCapability",
+]

zurvan-0.1.0/src/zurvan/action.py

@@ -0,0 +1,64 @@
+"""Action — the interface definition of what an agent can do.
+
+Two equivalent shapes are supported:
+
+1. **Dict / JSON Schema** (the original): pass a JSON-Schema dict as
+   ``parameters=``. Nothing validates the model's args before
+   ``function`` runs — it's on the LLM to send the right shape.
+2. **Pydantic model**: pass a ``BaseModel`` subclass as
+   ``input_model=``. The schema sent to the LLM is derived from the
+   model and the model's args are **validated before** ``function``
+   runs. ``pydantic.ValidationError`` is allowed to propagate and is
+   trapped by ``Environment.execute_action`` like any action exception
+   — the failure goes back to the LLM as a tool result, giving the
+   model a chance to retry with corrected args.
+
+The two paths are mutually exclusive — pass exactly one.
+"""
+
+from typing import Any, Callable, Dict, Optional, Type
+
+from pydantic import BaseModel
+
+
+class Action:
+    def __init__(
+        self,
+        name: str,
+        function: Callable,
+        description: str,
+        parameters: Optional[Dict] = None,
+        input_model: Optional[Type[BaseModel]] = None,
+        terminal: bool = False,
+    ):
+        if parameters is None and input_model is None:
+            raise ValueError(
+                "Action requires either `parameters` (a JSON-Schema dict) "
+                "or `input_model` (a Pydantic BaseModel subclass)."
+            )
+        if parameters is not None and input_model is not None:
+            raise ValueError(
+                "Action accepts either `parameters` or `input_model`, not both."
+            )
+
+        self.name = name
+        self.function = function
+        self.description = description
+        self.terminal = terminal
+        self.input_model = input_model
+        self.parameters = (
+            input_model.model_json_schema() if input_model is not None else parameters
+        )
+
+    def execute(self, **args) -> Any:
+        """Execute the action's function.
+
+        With ``input_model`` set, args are first validated through the
+        model. ``pydantic.ValidationError`` propagates on failure —
+        ``Environment.execute_action`` catches it and surfaces the
+        failure to the LLM so the model can retry with corrected args.
+        """
+        if self.input_model is not None:
+            validated = self.input_model(**args)
+            return self.function(**validated.model_dump())
+        return self.function(**args)

zurvan-0.1.0/src/zurvan/action_context.py

@@ -0,0 +1,14 @@
+from typing import Dict
+import uuid
+
+
+class ActionContext:
+    def __init__(self, properties: Dict = None):
+        self.context_id = str(uuid.uuid4())
+        self.properties = properties or {}
+
+    def get(self, key: str, default=None):
+        return self.properties.get(key, default)
+
+    def get_memory(self):
+        return self.properties.get("memory", None)

zurvan-0.1.0/src/zurvan/action_registry.py

@@ -0,0 +1,54 @@
+from typing import List
+
+from zurvan.action import Action
+from zurvan.decorators import tools, tools_by_tag  # the global dicts
+
+
+class ActionRegistry:
+    def __init__(self, tags: list[str] | None = None):
+        self.actions = {}
+        if tags:
+            self._load_from_tags(tags)
+
+    def _load_from_tags(self, tags: list[str]):
+        """Load tools matching any of the given tags via tools_by_tag."""
+        seen = set()
+        for tag in tags:
+            for tool_name in tools_by_tag.get(tag, []):
+                if tool_name not in seen:
+                    seen.add(tool_name)
+                    desc = tools[tool_name]
+                    self.register(
+                        Action(
+                            name=tool_name,
+                            function=desc["function"],
+                            description=desc["description"],
+                            parameters=desc.get("parameters", {}),
+                            terminal=desc.get("terminal", False),
+                        )
+                    )
+
+    def register(self, action: Action):
+        self.actions[action.name] = action
+
+    def get_action(self, name: str) -> Action | None:
+        return self.actions.get(name, None)
+
+    def get_actions(self) -> List[Action]:
+        """Get all registered actions"""
+        return list(self.actions.values())
+
+    def register_from_tools(self, tags: list[str] | None = None):
+        """Load decorated tools into this registry, optionally filtered by tags."""
+        for name, desc in tools.items():
+            if tags and not set(tags) & set(desc.get("tags", [])):
+                continue
+            self.register(
+                Action(
+                    name=name,
+                    function=desc["function"],
+                    description=desc["description"],
+                    parameters=desc.get("parameters", {}),
+                    terminal=desc.get("terminal", False),
+                )
+            )

zurvan-0.1.0/src/zurvan/action_transaction.py

@@ -0,0 +1,38 @@
+import uuid
+
+from zurvan.reversible_action import ReversibleAction
+
+
+class ActionTransaction:
+    def __init__(self):
+        self.actions = []
+        self.executed = []
+        self.committed = False
+        self.transaction_id = str(uuid.uuid4())
+
+    def add(self, action: ReversibleAction, **args):
+        """Queue an action for execution."""
+        if self.committed:
+            raise ValueError("Transaction already committed")
+        self.actions.append((action, args))
+
+    async def execute(self):
+        """Execute all actions in the transaction."""
+        try:
+            for action, args in self.actions:
+                result = action.run(**args)
+                self.executed.append(action)
+        except Exception as e:
+            # If any action fails, reverse everything done so far
+            await self.rollback()
+            raise e
+
+    async def rollback(self):
+        """Reverse all executed actions in reverse order."""
+        for action in reversed(self.executed):
+            await action.undo()
+        self.executed = []
+
+    def commit(self):
+        """Mark transaction as committed."""
+        self.committed = True