crewforge 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.
Files changed (61) hide show
  1. crewforge/__init__.py +3 -0
  2. crewforge/__main__.py +4 -0
  3. crewforge/cli.py +128 -0
  4. crewforge/cli_support.py +109 -0
  5. crewforge/core/__init__.py +54 -0
  6. crewforge/core/agent.py +118 -0
  7. crewforge/core/client.py +253 -0
  8. crewforge/core/config.py +181 -0
  9. crewforge/core/crew.py +144 -0
  10. crewforge/core/errors.py +106 -0
  11. crewforge/core/parsing.py +110 -0
  12. crewforge/core/providers.py +131 -0
  13. crewforge/core/usage.py +163 -0
  14. crewforge/py.typed +0 -0
  15. crewforge/recipes/__init__.py +1 -0
  16. crewforge/recipes/api/__init__.py +38 -0
  17. crewforge/recipes/api/agents.py +523 -0
  18. crewforge/recipes/api/analytics.py +99 -0
  19. crewforge/recipes/api/appcheck.py +73 -0
  20. crewforge/recipes/api/cli.py +127 -0
  21. crewforge/recipes/api/formatters.py +32 -0
  22. crewforge/recipes/api/generator.py +37 -0
  23. crewforge/recipes/api/pipeline.py +86 -0
  24. crewforge/recipes/api/scaffold.py +68 -0
  25. crewforge/recipes/api/templates/docker-compose.j2 +9 -0
  26. crewforge/recipes/api/templates/dockerfile.j2 +7 -0
  27. crewforge/recipes/api/templates/env.example.j2 +2 -0
  28. crewforge/recipes/api/templates/fastapi_main.j2 +10 -0
  29. crewforge/recipes/api/templates/model.j2 +4 -0
  30. crewforge/recipes/api/templates/requirements.j2 +6 -0
  31. crewforge/recipes/api/templates/route.j2 +4 -0
  32. crewforge/recipes/api/templates/test.j2 +3 -0
  33. crewforge/recipes/api/utils.py +134 -0
  34. crewforge/recipes/content/__init__.py +20 -0
  35. crewforge/recipes/content/agents.py +735 -0
  36. crewforge/recipes/content/cli.py +128 -0
  37. crewforge/recipes/content/export.py +84 -0
  38. crewforge/recipes/content/pipeline.py +222 -0
  39. crewforge/recipes/content/settings.py +63 -0
  40. crewforge/recipes/content/text.py +57 -0
  41. crewforge/recipes/docs/__init__.py +48 -0
  42. crewforge/recipes/docs/agents.py +426 -0
  43. crewforge/recipes/docs/cli.py +156 -0
  44. crewforge/recipes/docs/export.py +118 -0
  45. crewforge/recipes/docs/index.py +117 -0
  46. crewforge/recipes/docs/ingest.py +212 -0
  47. crewforge/recipes/docs/pipeline.py +223 -0
  48. crewforge/recipes/docs/retrieve.py +70 -0
  49. crewforge/recipes/docs/settings.py +54 -0
  50. crewforge/recipes/review/__init__.py +1 -0
  51. crewforge/recipes/review/agents.py +331 -0
  52. crewforge/recipes/review/cli.py +144 -0
  53. crewforge/recipes/review/pipeline.py +125 -0
  54. crewforge/recipes/review/report.py +103 -0
  55. crewforge/recipes/review/sources.py +89 -0
  56. crewforge-0.1.0.dist-info/METADATA +372 -0
  57. crewforge-0.1.0.dist-info/RECORD +61 -0
  58. crewforge-0.1.0.dist-info/WHEEL +5 -0
  59. crewforge-0.1.0.dist-info/entry_points.txt +2 -0
  60. crewforge-0.1.0.dist-info/licenses/LICENSE +21 -0
  61. crewforge-0.1.0.dist-info/top_level.txt +1 -0
@@ -0,0 +1,73 @@
1
+ """Optional check that a scaffolded app really serves the routes its spec promises.
2
+
3
+ Runs ``from main import app`` in a separate Python process (cwd = the project)
4
+ so the generated code never executes inside crewforge itself. Needs FastAPI
5
+ (``pip install 'crewforge[api]'``); without it the check is skipped and says so.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ import importlib.util
11
+ import json
12
+ import subprocess
13
+ import sys
14
+ from dataclasses import dataclass, field
15
+ from pathlib import Path
16
+ from typing import Any
17
+
18
+ # The app's own OpenAPI document is the stable way to list what it serves
19
+ # (FastAPI's internal route objects change shape between releases).
20
+ _PROBE = (
21
+ "import json, sys; sys.path.insert(0, '.'); from main import app; "
22
+ "print(json.dumps(sorted([m.upper(), p] for p, ops in app.openapi()['paths'].items() "
23
+ "for m in ops if m in ('get', 'post', 'put', 'patch', 'delete'))))"
24
+ )
25
+
26
+
27
+ @dataclass
28
+ class AppCheck:
29
+ ran: bool
30
+ errors: list[str] = field(default_factory=list)
31
+ note: str = ""
32
+
33
+ @property
34
+ def ok(self) -> bool:
35
+ return not self.errors
36
+
37
+
38
+ def spec_operations(spec: dict[str, Any]) -> set[tuple[str, str]]:
39
+ servers = spec.get("servers") or [{}]
40
+ base = str(servers[0].get("url", "") if isinstance(servers[0], dict) else "").rstrip("/")
41
+ ops = set()
42
+ for path, methods in (spec.get("paths") or {}).items():
43
+ for method in methods or {}:
44
+ if method in ("get", "post", "put", "patch", "delete"):
45
+ ops.add((method.upper(), base + path))
46
+ return ops
47
+
48
+
49
+ def check_app(project: str | Path, spec: dict[str, Any], timeout: float = 60) -> AppCheck:
50
+ project = Path(project)
51
+ if not (project / "main.py").exists():
52
+ return AppCheck(False, note="no main.py: app check skipped")
53
+ if importlib.util.find_spec("fastapi") is None:
54
+ return AppCheck(
55
+ False, note="FastAPI not installed: app check skipped (pip install 'crewforge[api]')"
56
+ )
57
+ try:
58
+ proc = subprocess.run(
59
+ [sys.executable, "-c", _PROBE],
60
+ cwd=project,
61
+ capture_output=True,
62
+ text=True,
63
+ timeout=timeout,
64
+ )
65
+ except subprocess.TimeoutExpired:
66
+ return AppCheck(True, [f"importing main.app took longer than {timeout:.0f}s"])
67
+ if proc.returncode != 0:
68
+ last = (proc.stderr.strip().splitlines() or ["unknown error"])[-1]
69
+ return AppCheck(True, [f"cannot import main.app: {last}"])
70
+ served = {(m, p) for m, p in json.loads(proc.stdout)}
71
+ missing = sorted(spec_operations(spec) - served)
72
+ errors = [f"spec operation {m} {p} is not served by the app" for m, p in missing]
73
+ return AppCheck(True, errors, note=f"app serves {len(served)} route(s)")
@@ -0,0 +1,127 @@
1
+ """``crewforge scaffold | validate`` — API scaffolding (ported from apiforge)."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import asyncio
6
+ import json
7
+ import sys
8
+ from pathlib import Path
9
+
10
+ import click
11
+
12
+ from ...cli_support import (
13
+ EXIT_FAILED,
14
+ EXIT_USAGE,
15
+ console,
16
+ err_console,
17
+ fail,
18
+ llm_config,
19
+ print_usage,
20
+ report_crew_failure,
21
+ run,
22
+ )
23
+ from ...core.errors import AgentFailure, CrewFailedError
24
+ from .agents import ValidateAgent, ValidationResult
25
+ from .appcheck import AppCheck, check_app
26
+ from .formatters import OutputFormatter
27
+ from .pipeline import ApiPipeline
28
+ from .scaffold import ProjectScaffold
29
+
30
+
31
+ def _print_validation(v: ValidationResult) -> None:
32
+ color = "green" if v.valid else "red"
33
+ console.print(
34
+ f"[{color}]Validation: {'valid' if v.valid else 'INVALID'} · {v.score}/100[/] "
35
+ f"({v.operations} operation(s) checked, {len(v.errors)} error(s), "
36
+ f"{len(v.warnings)} warning(s))",
37
+ highlight=False,
38
+ )
39
+ for e in v.errors:
40
+ console.print(f" [red]ERROR:[/] {e}", highlight=False, soft_wrap=True)
41
+ for w in v.warnings:
42
+ console.print(f" [yellow]WARN:[/] {w}", highlight=False, soft_wrap=True)
43
+
44
+
45
+ def _print_app_check(check: AppCheck) -> None:
46
+ if not check.ran:
47
+ err_console.print(f"[dim]{check.note}[/]", highlight=False)
48
+ elif check.ok:
49
+ console.print(f"[green]App check: OK[/] — {check.note}", highlight=False)
50
+ else:
51
+ for e in check.errors:
52
+ console.print(f" [red]APP:[/] {e}", highlight=False, soft_wrap=True)
53
+
54
+
55
+ @click.command("scaffold")
56
+ @click.argument("description")
57
+ @click.option(
58
+ "--output", "-o", default="./output", show_default=True, help="Project directory to write."
59
+ )
60
+ @click.option("--force", is_flag=True, help="Write into a non-empty directory.")
61
+ @click.pass_context
62
+ def scaffold(ctx, description, output, force):
63
+ """Turn a plain-English API DESCRIPTION into a FastAPI project + OpenAPI spec.
64
+
65
+ \b
66
+ Example:
67
+ crewforge scaffold "Todo API: list, create and delete todos" -o todo-api
68
+ """
69
+ out = Path(output)
70
+ if out.exists() and any(out.iterdir()) and not force:
71
+ fail(f"{out} is not empty (use --force to write into it)", EXIT_USAGE)
72
+
73
+ result = run(ApiPipeline(llm_config(ctx)).generate(description))
74
+ files = ProjectScaffold(out).scaffold(result)
75
+ console.print(f"[green]Wrote {len(files)} files[/]")
76
+ console.print(OutputFormatter.file_tree(files, out), highlight=False)
77
+ _print_validation(result.validation)
78
+ check = check_app(out, result.openapi_spec)
79
+ _print_app_check(check)
80
+ if result.tracker is not None:
81
+ print_usage(result.tracker)
82
+
83
+ if not result.validation.valid:
84
+ sys.exit(EXIT_FAILED)
85
+ if check.ran and not check.ok:
86
+ # The router agent rewrote the routes; the spec promises routes the app lacks.
87
+ failure = AgentFailure("router", "; ".join(check.errors), "mismatch")
88
+ report_crew_failure(CrewFailedError("scaffold", [failure]))
89
+ sys.exit(EXIT_FAILED)
90
+
91
+
92
+ @click.command("validate")
93
+ @click.argument("path", type=click.Path(exists=True))
94
+ @click.option("--json", "as_json", is_flag=True, help="Print the result as JSON.")
95
+ def validate(path, as_json):
96
+ """Validate an OpenAPI spec file, or a scaffolded project directory, offline.
97
+
98
+ For a directory, its openapi.json is checked and, when FastAPI is installed,
99
+ the app is imported in a subprocess to confirm it serves every operation.
100
+ No LLM call and no API key are needed.
101
+ """
102
+ target = Path(path)
103
+ spec_file = target / "openapi.json" if target.is_dir() else target
104
+ if not spec_file.is_file():
105
+ fail(f"no openapi.json in {target}", EXIT_USAGE)
106
+ try:
107
+ spec = json.loads(spec_file.read_text(encoding="utf-8"))
108
+ except (json.JSONDecodeError, UnicodeDecodeError) as exc:
109
+ fail(f"{spec_file} is not valid JSON: {exc}")
110
+
111
+ result = asyncio.run(ValidateAgent().validate(spec))
112
+ check = check_app(target, spec) if target.is_dir() else AppCheck(False, note="")
113
+ ok = result.valid and (not check.ran or check.ok)
114
+ if as_json:
115
+ data = result.to_dict()
116
+ data["app_check"] = {"ran": check.ran, "errors": check.errors, "note": check.note}
117
+ data["ok"] = ok
118
+ click.echo(json.dumps(data, indent=2))
119
+ else:
120
+ _print_validation(result)
121
+ if target.is_dir():
122
+ _print_app_check(check)
123
+ if not ok:
124
+ sys.exit(EXIT_FAILED)
125
+
126
+
127
+ commands = [scaffold, validate]
@@ -0,0 +1,32 @@
1
+ """Output formatters for the api recipe."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import json
6
+ from pathlib import Path
7
+ from typing import Any
8
+
9
+
10
+ class OutputFormatter:
11
+ @staticmethod
12
+ def to_json(data: dict[str, Any], pretty: bool = True) -> str:
13
+ return json.dumps(data, indent=2 if pretty else None, default=str)
14
+
15
+ @staticmethod
16
+ def to_markdown_table(headers: list[str], rows: list[list[str]]) -> str:
17
+ lines = ["| " + " | ".join(headers) + " |"]
18
+ lines.append("|" + "|".join(["---"] * len(headers)) + "|")
19
+ for row in rows:
20
+ lines.append("| " + " | ".join(row) + " |")
21
+ return "\n".join(lines)
22
+
23
+ @staticmethod
24
+ def wrap_code(code: str, lang: str = "python") -> str:
25
+ return f"```{lang}\n{code}\n```"
26
+
27
+ @staticmethod
28
+ def file_tree(files: dict[str, Path], root: Path) -> str:
29
+ lines = [f"{root.name}/"]
30
+ for path in sorted(files.values()):
31
+ lines.append(f" {path.relative_to(root)}")
32
+ return "\n".join(lines)
@@ -0,0 +1,37 @@
1
+ """Code generator with Jinja2 templates."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from pathlib import Path
6
+ from typing import Any
7
+
8
+ from jinja2 import Environment, FileSystemLoader
9
+
10
+
11
+ class CodeGenerator:
12
+ """Generate code from Jinja2 templates."""
13
+
14
+ def __init__(self, template_dir: str | Path | None = None) -> None:
15
+ td = template_dir or Path(__file__).parent / "templates"
16
+ self.env = Environment(
17
+ loader=FileSystemLoader(str(td)), trim_blocks=True, lstrip_blocks=True
18
+ )
19
+
20
+ def render(self, template_name: str, context: dict[str, Any]) -> str:
21
+ tpl = self.env.get_template(template_name)
22
+ return tpl.render(**context)
23
+
24
+ def render_fastapi_main(self, title: str, routes: list[str]) -> str:
25
+ return self.render("fastapi_main.j2", {"title": title, "routes": routes})
26
+
27
+ def render_route(self, path: str, method: str, func_name: str, params: list[str]) -> str:
28
+ return self.render(
29
+ "route.j2",
30
+ {"path": path, "method": method, "func_name": func_name, "params": params},
31
+ )
32
+
33
+ def render_model(self, name: str, fields: list[dict[str, Any]]) -> str:
34
+ return self.render("model.j2", {"name": name, "fields": fields})
35
+
36
+ def render_test(self, test_name: str, method: str, path: str) -> str:
37
+ return self.render("test.j2", {"test_name": test_name, "method": method, "path": path})
@@ -0,0 +1,86 @@
1
+ """API scaffolding pipeline: parse → spec → (routes ∥ models ∥ auth ∥ tests ∥ docs) → validate."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from dataclasses import dataclass, field
6
+ from typing import Any
7
+
8
+ import httpx
9
+
10
+ from ...core.client import LLMClient
11
+ from ...core.config import LLMConfig
12
+ from ...core.crew import Crew
13
+ from ...core.usage import UsageTracker
14
+ from .agents import (
15
+ APIDescription,
16
+ AuthAgent,
17
+ DocAgent,
18
+ ModelAgent,
19
+ ParserAgent,
20
+ RouterAgent,
21
+ SchemaAgent,
22
+ TestAgent,
23
+ ValidateAgent,
24
+ ValidationResult,
25
+ )
26
+
27
+
28
+ @dataclass
29
+ class PipelineResult:
30
+ description: APIDescription
31
+ openapi_spec: dict[str, Any]
32
+ router_code: str
33
+ model_code: str
34
+ auth_code: str
35
+ test_code: str
36
+ docs: str
37
+ validation: ValidationResult
38
+ token_summary: dict[str, Any] = field(default_factory=dict)
39
+ tracker: UsageTracker | None = field(default=None, repr=False)
40
+
41
+
42
+ class ApiPipeline:
43
+ """Orchestrates the api agents on one crew."""
44
+
45
+ def __init__(
46
+ self,
47
+ config: LLMConfig | None = None,
48
+ *,
49
+ client: LLMClient | None = None,
50
+ transport: httpx.AsyncBaseTransport | None = None,
51
+ ) -> None:
52
+ self.config = config or LLMConfig()
53
+ self._client = client
54
+ self._transport = transport
55
+ self.validator = ValidateAgent()
56
+
57
+ async def generate(self, description: str) -> PipelineResult:
58
+ crew = Crew("scaffold", self.config, client=self._client, transport=self._transport)
59
+ async with crew:
60
+ parser = crew.agent(ParserAgent)
61
+ desc = await crew.step(parser, parser.parse(description))
62
+ spec = await crew.step("schema", crew.agent(SchemaAgent).generate_spec(desc))
63
+
64
+ work = {
65
+ "router": crew.agent(RouterAgent).generate_routes(desc),
66
+ "auth": crew.agent(AuthAgent).generate_auth(desc.auth_type),
67
+ "test_gen": crew.agent(TestAgent).generate_tests(desc),
68
+ "doc_gen": crew.agent(DocAgent).generate_docs(desc),
69
+ }
70
+ if desc.models:
71
+ work["model"] = crew.agent(ModelAgent).generate_models(desc)
72
+ out = await crew.parallel(work)
73
+ model_code = out.get("model") or ModelAgent._generate_models(desc)
74
+ validation = await crew.step("validator", self.validator.validate(spec))
75
+ return PipelineResult(
76
+ description=desc,
77
+ openapi_spec=spec,
78
+ router_code=out["router"],
79
+ model_code=model_code,
80
+ auth_code=out["auth"],
81
+ test_code=out["test_gen"],
82
+ docs=out["doc_gen"],
83
+ validation=validation,
84
+ token_summary=crew.tracker.summary(),
85
+ tracker=crew.tracker,
86
+ )
@@ -0,0 +1,68 @@
1
+ """Write a runnable FastAPI project from a pipeline result."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import json
6
+ from pathlib import Path
7
+
8
+ from .generator import CodeGenerator
9
+ from .pipeline import PipelineResult
10
+
11
+
12
+ class ProjectScaffold:
13
+ def __init__(self, output_dir: str | Path) -> None:
14
+ self.output_dir = Path(output_dir)
15
+ self.generator = CodeGenerator()
16
+
17
+ def scaffold(self, result: PipelineResult) -> dict[str, Path]:
18
+ files: dict[str, Path] = {}
19
+ self.output_dir.mkdir(parents=True, exist_ok=True)
20
+ files["routes"] = self._write("routes.py", result.router_code)
21
+ files["models"] = self._write("models.py", result.model_code)
22
+ files["auth"] = self._write("auth.py", result.auth_code)
23
+ files["tests"] = self._write("tests/test_api.py", result.test_code)
24
+ files["openapi"] = self._write("openapi.json", json.dumps(result.openapi_spec, indent=2))
25
+ files["docs"] = self._write("API.md", result.docs)
26
+ files["main"] = self._write("main.py", self._main(result))
27
+ files["requirements"] = self._write(
28
+ "requirements.txt", self.generator.render("requirements.j2", {})
29
+ )
30
+ files["dockerfile"] = self._write("Dockerfile", self.generator.render("dockerfile.j2", {}))
31
+ files["env"] = self._write(".env.example", self.generator.render("env.example.j2", {}))
32
+ files["conftest"] = self._write("tests/conftest.py", self._conftest())
33
+ return files
34
+
35
+ def _write(self, name: str, content: str) -> Path:
36
+ path = self.output_dir / name
37
+ path.parent.mkdir(parents=True, exist_ok=True)
38
+ path.write_text(content, encoding="utf-8")
39
+ return path
40
+
41
+ def _main(self, result: PipelineResult) -> str:
42
+ d = result.description
43
+ # repr() keeps model-written titles from breaking out of the string literal.
44
+ return (
45
+ f'"""{d.title.replace(chr(34) * 3, "")} -- generated by crewforge."""\n'
46
+ "from fastapi import FastAPI\n\n"
47
+ "from routes import router\n\n"
48
+ f"app = FastAPI(title={d.title!r}, description={d.description!r}, "
49
+ f"version={d.version!r})\n"
50
+ "app.include_router(router)\n\n\n"
51
+ '@app.get("/health")\n'
52
+ "async def health():\n"
53
+ ' return {"status": "ok"}\n'
54
+ )
55
+
56
+ def _conftest(self) -> str:
57
+ return (
58
+ '"""Test configuration."""\n'
59
+ "import sys\n"
60
+ "from pathlib import Path\n\n"
61
+ "import pytest\n"
62
+ "from fastapi.testclient import TestClient\n\n"
63
+ "sys.path.insert(0, str(Path(__file__).resolve().parents[1]))\n\n\n"
64
+ "@pytest.fixture\n"
65
+ "def client():\n"
66
+ " from main import app\n\n"
67
+ " return TestClient(app)\n"
68
+ )
@@ -0,0 +1,9 @@
1
+ version: "3.9"
2
+ services:
3
+ api:
4
+ build: .
5
+ ports:
6
+ - "8000:8000"
7
+ environment:
8
+ - JWT_SECRET=change-me
9
+ command: uvicorn main:app --host 0.0.0.0 --port 8000 --reload
@@ -0,0 +1,7 @@
1
+ FROM python:3.11-slim
2
+ WORKDIR /app
3
+ COPY requirements.txt .
4
+ RUN pip install --no-cache-dir -r requirements.txt
5
+ COPY . .
6
+ EXPOSE 8000
7
+ CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]
@@ -0,0 +1,2 @@
1
+ JWT_SECRET=change-this-to-a-random-string
2
+ DATABASE_URL=sqlite:///./app.db
@@ -0,0 +1,10 @@
1
+ """{{ title }} - Auto-generated by crewforge."""
2
+ from fastapi import FastAPI
3
+ {% for route in routes %}
4
+ from . import {{ route }}
5
+ {% endfor %}
6
+
7
+ app = FastAPI(title="{{ title }}")
8
+ {% for route in routes %}
9
+ app.include_router({{ route }}.router)
10
+ {% endfor %}
@@ -0,0 +1,4 @@
1
+ class {{ name }}(BaseModel):
2
+ {% for field in fields %}
3
+ {{ field.name }}: {{ field.type }}
4
+ {% endfor %}
@@ -0,0 +1,6 @@
1
+ fastapi>=0.115
2
+ uvicorn[standard]>=0.30
3
+ pydantic>=2.7
4
+ pyjwt>=2.8
5
+ httpx>=0.27
6
+ pytest>=8.0
@@ -0,0 +1,4 @@
1
+ @router.{{ method }}("{{ path }}")
2
+ async def {{ func_name }}({{ params | join(", ") }}):
3
+ """Auto-generated endpoint."""
4
+ return {}
@@ -0,0 +1,3 @@
1
+ def {{ test_name }}(client):
2
+ resp = client.{{ method }}("{{ path }}")
3
+ assert resp.status_code in (200, 201, 401, 422)
@@ -0,0 +1,134 @@
1
+ """Small helpers carried over from apiforge."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import hashlib
6
+ import json
7
+ import re
8
+ import time
9
+ from pathlib import Path
10
+ from typing import Any
11
+
12
+
13
+ def slugify(text: str) -> str:
14
+ """Convert text to URL-friendly slug."""
15
+ text = text.lower().strip()
16
+ text = re.sub(r"[^a-z0-9]+", "-", text)
17
+ text = re.sub(r"-+", "-", text)
18
+ return text.strip("-")
19
+
20
+
21
+ def truncate(text: str, max_length: int = 100, suffix: str = "...") -> str:
22
+ """Truncate text to max_length, adding suffix if truncated."""
23
+ if len(text) <= max_length:
24
+ return text
25
+ return text[: max_length - len(suffix)] + suffix
26
+
27
+
28
+ def hash_content(content: str) -> str:
29
+ """Generate SHA-256 hash of content."""
30
+ return hashlib.sha256(content.encode()).hexdigest()[:16]
31
+
32
+
33
+ def safe_filename(name: str) -> str:
34
+ """Convert string to safe filename."""
35
+ name = re.sub(r"[^\w\s-]", "", name)
36
+ name = re.sub(r"[-\s]+", "-", name)
37
+ return name.strip("-").lower()
38
+
39
+
40
+ def chunk_list(lst: list, chunk_size: int) -> list[list]:
41
+ """Split a list into chunks of chunk_size."""
42
+ return [lst[i : i + chunk_size] for i in range(0, len(lst), chunk_size)]
43
+
44
+
45
+ def deep_merge(base: dict, override: dict) -> dict:
46
+ """Deep merge two dicts, override values take precedence."""
47
+ result = base.copy()
48
+ for key, value in override.items():
49
+ if key in result and isinstance(result[key], dict) and isinstance(value, dict):
50
+ result[key] = deep_merge(result[key], value)
51
+ else:
52
+ result[key] = value
53
+ return result
54
+
55
+
56
+ def flatten_dict(d: dict, parent_key: str = "", sep: str = ".") -> dict:
57
+ """Flatten nested dict with separator."""
58
+ items: list[tuple[str, Any]] = []
59
+ for k, v in d.items():
60
+ new_key = f"{parent_key}{sep}{k}" if parent_key else k
61
+ if isinstance(v, dict):
62
+ items.extend(flatten_dict(v, new_key, sep).items())
63
+ else:
64
+ items.append((new_key, v))
65
+ return dict(items)
66
+
67
+
68
+ def timed(func):
69
+ """Decorator to time function execution."""
70
+ import functools
71
+
72
+ @functools.wraps(func)
73
+ def wrapper(*args, **kwargs):
74
+ start = time.monotonic()
75
+ result = func(*args, **kwargs)
76
+ elapsed = (time.monotonic() - start) * 1000
77
+ return result, elapsed
78
+
79
+ return wrapper
80
+
81
+
82
+ def load_json_file(path: str | Path) -> Any:
83
+ """Load and parse a JSON file."""
84
+ p = Path(path)
85
+ if not p.exists():
86
+ raise FileNotFoundError(f"File not found: {p}")
87
+ return json.loads(p.read_text())
88
+
89
+
90
+ def save_json_file(path: str | Path, data: Any, indent: int = 2) -> Path:
91
+ """Save data to JSON file."""
92
+ p = Path(path)
93
+ p.parent.mkdir(parents=True, exist_ok=True)
94
+ p.write_text(json.dumps(data, indent=indent, default=str))
95
+ return p
96
+
97
+
98
+ def estimate_tokens(text: str) -> int:
99
+ """Rough token count estimation (1 token ~ 4 chars for English)."""
100
+ return max(1, len(text) // 4)
101
+
102
+
103
+ def format_duration(seconds: float) -> str:
104
+ """Format seconds into human-readable duration."""
105
+ if seconds < 1:
106
+ return f"{seconds * 1000:.0f}ms"
107
+ if seconds < 60:
108
+ return f"{seconds:.1f}s"
109
+ minutes = int(seconds // 60)
110
+ secs = seconds % 60
111
+ return f"{minutes}m {secs:.0f}s"
112
+
113
+
114
+ def extract_json_from_text(text: str) -> dict | None:
115
+ """Extract JSON object from text (handles markdown code blocks)."""
116
+ if "```" in text:
117
+ parts = text.split("```")
118
+ for part in parts[1::2]:
119
+ if part.startswith("json"):
120
+ part = part[4:]
121
+ try:
122
+ return json.loads(part.strip())
123
+ except json.JSONDecodeError:
124
+ continue
125
+ try:
126
+ return json.loads(text)
127
+ except json.JSONDecodeError:
128
+ match = re.search(r"\{.*\}", text, re.DOTALL)
129
+ if match:
130
+ try:
131
+ return json.loads(match.group())
132
+ except json.JSONDecodeError:
133
+ pass
134
+ return None
@@ -0,0 +1,20 @@
1
+ """content recipe: research -> outline -> write -> SEO -> edit <-> quality -> translate -> publish.
2
+
3
+ Ported from contentforge (github.com/aimanmalib/contentforge).
4
+ """
5
+
6
+ from .agents import AGENT_REGISTRY, AgentResult, ContentAgent, get_agent
7
+ from .pipeline import ContentPipeline, PipelineResult
8
+ from .settings import AgentConfig, ContentSettings, PipelineConfig
9
+
10
+ __all__ = [
11
+ "AGENT_REGISTRY",
12
+ "AgentConfig",
13
+ "AgentResult",
14
+ "ContentAgent",
15
+ "ContentPipeline",
16
+ "ContentSettings",
17
+ "PipelineConfig",
18
+ "PipelineResult",
19
+ "get_agent",
20
+ ]