state-mesh 0.1.0__tar.gz

state_mesh-0.1.0/.gitignore

@@ -0,0 +1,206 @@
+# Created by https://www.toptal.com/developers/gitignore/api/python,react,rust
+# Edit at https://www.toptal.com/developers/gitignore?templates=python,react,rust
+
+### Python ###
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+### Python Patch ###
+# Poetry local configuration file - https://python-poetry.org/docs/configuration/#local-configuration
+poetry.toml
+
+# ruff
+.ruff_cache/
+
+# LSP config files
+pyrightconfig.json
+
+### react ###
+.DS_*
+logs
+**/*.backup.*
+**/*.back.*
+
+node_modules
+bower_components
+
+*.sublime*
+
+psd
+thumb
+sketch
+
+### Rust ###
+# Generated by Cargo
+# will have compiled files and executables
+debug/
+
+# Remove Cargo.lock from gitignore if creating an executable, leave it for libraries
+# More information here https://doc.rust-lang.org/cargo/guide/cargo-toml-vs-cargo-lock.html
+Cargo.lock
+
+# These are backup files generated by rustfmt
+**/*.rs.bk
+
+# MSVC Windows builds of rustc generate these, which store debugging information
+*.pdb
+
+# End of https://www.toptal.com/developers/gitignore/api/python,react,rust

state_mesh-0.1.0/PKG-INFO

@@ -0,0 +1,88 @@
+Metadata-Version: 2.4
+Name: state-mesh
+Version: 0.1.0
+Summary: Async-native agentic pipeline runtime for Python backend engineers
+Project-URL: Homepage, https://github.com/statemesh-123/state-mesh-agent-runtime
+Project-URL: Repository, https://github.com/statemesh-123/state-mesh-agent-runtime
+Project-URL: Issues, https://github.com/statemesh-123/state-mesh-agent-runtime/issues
+Author: Meghala
+Author-email: Jayaprabha <statemesh@gmail.com>
+License: MIT
+Keywords: agent,async,llm,pipeline,runtime
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Requires-Dist: anyio>=4.0
+Requires-Dist: fastapi>=0.100
+Requires-Dist: mcp>=1.0
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: httpx; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Provides-Extra: otel
+Requires-Dist: opentelemetry-api>=1.20; extra == 'otel'
+Requires-Dist: opentelemetry-sdk>=1.20; extra == 'otel'
+Provides-Extra: postgres
+Requires-Dist: asyncpg>=0.29; extra == 'postgres'
+Provides-Extra: redis
+Requires-Dist: redis>=5.0; extra == 'redis'
+Provides-Extra: toxicity
+Requires-Dist: detoxify>=0.5; extra == 'toxicity'
+Description-Content-Type: text/markdown
+
+# State-Mesh
+
+Async-native agentic pipeline runtime for Python backend engineers.
+
+## Why State-Mesh
+
+- **Typed state** — Pydantic models flow through every step, no silent dict mutations
+- **Built-in MCP** — register MCP servers once, every step can call any tool
+- **Production-ready** — guardrails, structured output retry, OTel tracing, pipeline resumption out of the box
+
+## Features
+
+- Async-first step execution with retry, timeout, and branching
+- Parallel step execution with `asyncio.gather`
+- Structured output contracts with automatic LLM retry
+- Guard chain — schema, PII, confidence, toxicity guards built in
+- MCP tool bus (SSE + stdio transport)
+- OpenTelemetry tracing with swappable exporters
+- Redis state backend with pipeline resumption
+- FastAPI integration — `mount_pipeline`, `stream_pipeline`, `pipeline_router`
+- Human-in-the-loop with timeout and fallback
+
+## Install
+
+```bash
+pip install state-mesh
+pip install "state-mesh[redis]"   # Redis backend
+pip install "state-mesh[otel]"    # OpenTelemetry
+```
+
+## Quickstart
+
+```python
+from state_mesh import step, Pipeline, Context, OutputContract
+from pydantic import BaseModel
+
+class Result(BaseModel):
+    summary: str
+
+@step(output_contract=OutputContract(target_schema=Result))
+async def summarise(prompt: str) -> str:
+    return await my_llm(prompt)
+
+pipeline = Pipeline(steps=[summarise], name="summarise")
+result = await pipeline.run(Context(state={}))
+```
+
+## License
+
+MIT

state_mesh-0.1.0/README.md

@@ -0,0 +1,50 @@
+# State-Mesh
+
+Async-native agentic pipeline runtime for Python backend engineers.
+
+## Why State-Mesh
+
+- **Typed state** — Pydantic models flow through every step, no silent dict mutations
+- **Built-in MCP** — register MCP servers once, every step can call any tool
+- **Production-ready** — guardrails, structured output retry, OTel tracing, pipeline resumption out of the box
+
+## Features
+
+- Async-first step execution with retry, timeout, and branching
+- Parallel step execution with `asyncio.gather`
+- Structured output contracts with automatic LLM retry
+- Guard chain — schema, PII, confidence, toxicity guards built in
+- MCP tool bus (SSE + stdio transport)
+- OpenTelemetry tracing with swappable exporters
+- Redis state backend with pipeline resumption
+- FastAPI integration — `mount_pipeline`, `stream_pipeline`, `pipeline_router`
+- Human-in-the-loop with timeout and fallback
+
+## Install
+
+```bash
+pip install state-mesh
+pip install "state-mesh[redis]"   # Redis backend
+pip install "state-mesh[otel]"    # OpenTelemetry
+```
+
+## Quickstart
+
+```python
+from state_mesh import step, Pipeline, Context, OutputContract
+from pydantic import BaseModel
+
+class Result(BaseModel):
+    summary: str
+
+@step(output_contract=OutputContract(target_schema=Result))
+async def summarise(prompt: str) -> str:
+    return await my_llm(prompt)
+
+pipeline = Pipeline(steps=[summarise], name="summarise")
+result = await pipeline.run(Context(state={}))
+```
+
+## License
+
+MIT

state_mesh-0.1.0/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "state-mesh"
+version = "0.1.0"
+description = "Async-native agentic pipeline runtime for Python backend engineers"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.11"
+authors = [
+    { name = "Jayaprabha", email = "statemesh@gmail.com" },
+    { name = "Meghala" },
+]
+keywords = ["agent", "pipeline", "llm", "async", "runtime"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries",
+]
+
+dependencies = [
+    "pydantic>=2.0",
+    "anyio>=4.0",
+    "fastapi>=0.100",
+    "mcp>=1.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/statemesh-123/state-mesh-agent-runtime"
+Repository = "https://github.com/statemesh-123/state-mesh-agent-runtime"
+Issues = "https://github.com/statemesh-123/state-mesh-agent-runtime/issues"
+
+[project.optional-dependencies]
+redis = ["redis>=5.0"]
+postgres = ["asyncpg>=0.29"]
+otel = ["opentelemetry-api>=1.20", "opentelemetry-sdk>=1.20"]
+toxicity = ["detoxify>=0.5"]
+dev = ["pytest>=8.0", "pytest-asyncio>=0.23", "ruff", "httpx"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["state_mesh"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+
+[tool.ruff]
+line-length = 88

state_mesh-0.1.0/requirements.txt

@@ -0,0 +1,19 @@
+annotated-types==0.7.0
+colorama==0.4.6
+iniconfig==2.3.0
+packaging==26.2
+pluggy==1.6.0
+pydantic==2.13.4
+pydantic_core==2.46.4
+Pygments==2.20.0
+pytest==9.1.0
+typing-inspection==0.4.2
+typing_extensions==4.15.0
+pytest-asyncio
+opentelemetry-api 
+opentelemetry-sdk
+fastapi
+mcp
+redis
+detoxify
+httpx2

state_mesh-0.1.0/state_mesh/__init__.py

@@ -0,0 +1,26 @@
+from state_mesh.core.context import Context, Flag
+from state_mesh.core.step import Step, Branch, RetryConfig, step
+from state_mesh.core.pipeline import Pipeline, PipelineResult
+from state_mesh.guardrails.base import Guard, GuardResult
+from state_mesh.guardrails.schema import SchemaGuard
+from state_mesh.guardrails.content import PIIGuard
+from state_mesh.output.contract import OutputContract
+from state_mesh.mcp.server_manager import MCPServerConfig, MCPServerManager
+
+__all__ = [
+    "step",
+    "Step",
+    "Pipeline",
+    "Context",
+    "RetryConfig",
+    "Branch",
+    "PipelineResult",
+    "Guard",
+    "GuardResult",
+    "SchemaGuard",
+    "PIIGuard",
+    "OutputContract",
+    "Flag",
+    "MCPServerConfig",
+    "MCPServerManager",
+]

state_mesh-0.1.0/state_mesh/core/context.py

@@ -0,0 +1,122 @@
+from __future__ import annotations
+
+import uuid
+from datetime import datetime, timezone
+from typing import Any, Generic, TypeVar, Literal, TYPE_CHECKING
+from pydantic import BaseModel, Field
+
+if TYPE_CHECKING:
+    from bus import MCPBus
+
+StateSchema = TypeVar("StateSchema", bound=BaseModel)
+
+
+class Flag(BaseModel):
+    step_name:str 
+    severity: Literal["info","warn","error"]
+    timestamp:datetime=Field(default_factory=lambda:datetime.now(timezone.utc))
+    flag_type: str
+    reason:str
+    payload:dict[str,Any]=Field(default_factory=dict)
+
+class ContextMutationError(Exception):
+    pass
+    
+class Context(Generic[StateSchema]):
+    """
+    Context is the main object that is passed to all steps.
+    It contains the state, run_id, trace_id, pipeline_name and flags.
+    """
+    def __init__(self,state,run_id=None,trace_id=None,pipeline_name="unnamed",tools:MCPBus|None=None):
+        self._state = state
+        self._run_id = run_id or str(uuid.uuid4())
+        self._trace_id = trace_id or str(uuid.uuid4())
+        self._pipeline_name = pipeline_name
+        self._flags:list[Flag] = []
+        self._extras:dict[str,Any]={}
+        self._tools=tools
+        self._step_name=None
+       
+    @property
+    def state(self) -> StateSchema:
+        return self._state
+    
+    @property
+    def tools(self) -> MCPBus|None:
+        return self._tools
+        
+    @property
+    def run_id(self) -> str:
+        return self._run_id
+    
+    @property
+    def trace_id(self) -> str:
+        return self._trace_id
+    
+    @property
+    def pipeline_name(self) -> str:
+        return self._pipeline_name 
+
+    @property
+    def flags(self) -> list[Flag]:
+        flag=self._flags.copy() # sp the user wont be able directly modify this
+        return flag
+    
+    def set(self,key:str,value:Any)->None:
+        if key in self._extras:
+            raise ContextMutationError(f"Key {key} already exists in extras")
+        self._extras[key]=value
+    
+    def get(self,key:str,default:Any=None)->Any:
+        return self._extras.get(key,default)
+    
+    def emit_flag(self,flag_type:str,reason:str,severity:Literal["info","warn","error"]="warn",payload:dict[str,Any]|None=None)->None:
+        self._flags.append(Flag(
+            step_name=self._step_name,
+            severity=severity,
+            flag_type=flag_type,
+            reason=reason,
+            payload=payload or {}
+        ))
+        
+    def _set_current_step(self, step_name: str) -> None:
+        self._step_name = step_name
+
+    def _replace_state(self, new_state: StateSchema) -> None:
+        self._state = new_state
+    
+    #serialize the context for pipeline resumption
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "state": self._state.model_dump() if isinstance(self._state, BaseModel) else self._state,
+            "run_id": self._run_id,
+            "trace_id": self._trace_id,
+            "pipeline_name": self._pipeline_name,
+            "extras": self._extras,
+            "flags": [f.model_dump() for f in self._flags],
+            "last_completed_step": self._step_name,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any], state_schema: type[BaseModel]) -> Context:
+        ctx = cls(
+            state=state_schema(**data["state"]),
+            run_id=data["run_id"],
+            trace_id=data["trace_id"],
+            pipeline_name=data["pipeline_name"],
+        )
+        ctx._extras = data["extras"]
+        ctx._flags = [Flag(**f) for f in data["flags"]]
+        ctx._step_name = data.get("last_completed_step")
+        return ctx
+    
+    def __repr__(self) -> str:
+        return (
+        f"Context(run_id={self._run_id!r}, "
+        f"step={self._step_name!r}, "
+        f"flags={len(self._flags)})"
+    )
+        
+        
+
+        

state_mesh-0.1.0/state_mesh/core/human_input.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+
+class HumanInput:
+    def __init__(
+        self,
+        prompt: str,
+        response_key: str,
+        timeout_seconds: float = 300.0,
+        fallback_step: str | None = None,
+    ):
+        self.prompt = prompt
+        self.response_key = response_key
+        self.timeout_seconds = timeout_seconds
+        self.fallback_step = fallback_step

state_mesh-0.1.0/state_mesh/core/parallel.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+import asyncio
+
+from state_mesh.core.context import Context
+from state_mesh.core.step import Step, StepResult
+
+
+class Parallel:
+    def __init__(self, steps: list[Step], name: str = "parallel"):
+        self.name = name
+        self.steps = steps
+
+    async def execute(self, ctx: Context) -> list[StepResult]:
+        results: list[StepResult] = list(
+            await asyncio.gather(*[step.execute(ctx) for step in self.steps], return_exceptions=True)
+        )
+
+        for step, result in zip(self.steps, results):
+            if not isinstance(result, BaseException) and result.status == "success":
+                ctx.set(step.name, result.output)
+
+        return results